\documentclass[a4paper,11pt,final]{article}
\input{config.tex}



\begin{document}
\bbtkGuide[Developer's Guide]





% ==========================================
\tableofcontents
% ==========================================

% ==========================================
\newpage
\hrule

% ==========================================
\section{Introduction}
% ==========================================

% ==========================================
\section{Pipeline processing algorithm}
% ==========================================

Each input of a black box instance has a Status, 
of type IOStatus (defined in bbtkConnection.h) 
which can take one of the three values:
\begin{itemize}
\item UPTODATE (==0): The input did not change since last processing 
\item MODIFIED (==1): [Initial value on construction] The input changed since last processing but is up-to-date with the amont box to which it is connected, if any.
\item OUTOFDATE (==2): The input changed since last processing and is out-of-date with the amont box to which it is connected.
\end{itemize}
The status of an input is stored by the class BlackBoxInputConnector.

Each output of a black box instance also has a Status, 
of type IOStatus but which can only take the two values:
\begin{itemize}
\item UPTODATE (==0): The output is up-to-date (the box need not be reprocessed).
\item OUTOFDATE (==2): [Initial value on construction] The output is out-of-date (the box need to be reprocessed).
\end{itemize}
The status of an output is stored by the class BlackBoxOutputConnector.


The main execution method of a black box is bbExecute.
bbExecute checks werther the box is not already executing (bbGetExecuting()) 
to prevent reentrance and 
checks werther the execution is not frozen (bbGlobalGetFreezeExecution()).
If it is not the case then it calls bbBackwardUpdate which is 
the main recursive pipeline processing method of a box, giving it a 
NULL Connection::Pointer.

bbBackwardUpdate is defined in AtomicBlackBox:

\bigskip\hrule\begin{verbatim}
void AtomicBlackBox::bbBackwardUpdate ( Connection::Pointer caller )
{
  // Updates the box inputs. Returns the max input IOStatus after update
  IOStatus s = bbUpdateInputs();
  // If at least one input is modified or BoxProcessMode=='Always'
  if ( (s != UPTODATE) || bbBoxProcessModeIsAlways() )
    {
      // User process
      bbProcess();
      // Displays the window (overloaded in widget Blackboxes, WxBlackBox, KWBlackBox, etc.)
      bbShowWindow(caller);
      // Compute the final status of inputs and outputs
      bbComputePostProcessStatus();
    }
}
\end{verbatim}\hrule\bigskip

bbUpdateInputs iterates over the InputConnector of the box and 
calls BackwardUpdate on each one. It returns the max of the final 
status of the input connectors:
\bigskip\hrule\begin{verbatim}
IOStatus BlackBox::bbUpdateInputs()
{
  IOStatus s = UPTODATE;
  InputConnectorMapType::iterator i;
  for ( i = bbGetInputConnectorMap().begin(); 
        i!= bbGetInputConnectorMap().end(); ++i) 
    {
      i->second->BackwardUpdate();
      IOStatus t = i->second->GetStatus();
      if (t > s) s = t;
    }
  return s;    
 
}
\end{verbatim}\hrule\bigskip

\bigskip\hrule\begin{verbatim}
void BlackBoxInputConnector::BackwardUpdate()
{
  // If connected and OUTOFDATE : recursive update
  // Post-update status is updated by the connection 
  // (either MODIFIED or OUTOFDATE)
   if ( mConnection && (mStatus == OUTOFDATE) ) 
    {
      mConnection->BackwardUpdate();
    }
}
\end{verbatim}\hrule\bigskip

\bigskip\hrule\begin{verbatim}
void Connection::BackwardUpdate()
{
  // Calls bbBackwardUpdate on the initial box
  mFrom->bbBackwardUpdate(GetThisPointer<Connection>());
  // Transfers the data from the initial box output to the 
  // final box input adapting it if necessary
  TransferData();
  // Updates the status of the final box input
  IOStatus s = MODIFIED;
  if ( mFrom->bbGetOutputConnector(mOutput).GetStatus() == OUTOFDATE) 
    s = OUTOFDATE,
  mTo->bbGetInputConnector(mInput).SetStatus(s);
}
\end{verbatim}\hrule\bigskip



% ==========================================
\section{Misc}
% ==========================================

\subsection{Displaying messages}

\begin{verbatim}
bbtkMessage("Kind",level,"message "<<"to "<<" display : i="<<i<<std::endl);
bbtkDebugMessage("Kind",level,"message "<<"to "<<" display : i="<<i<<std::endl);
\end{verbatim}

\section{Types and RTTI}



In \bbtk the class conveying the information on a type is 
\begin{verbatim}
bbtk::TypeInfo
\end{verbatim}
which is simply a typedef on 
\begin{verbatim}
const std::type_info&
\end{verbatim}
Remember that all constructors of the std::type\_info class are private, 
hence objects can only be created by the operator \texttt{typeid} 
which returns a const reference on a type\_info. 
Hence the \bbtk type TypeInfo conveys that const reference 
and cannot be itself referenced. 
Any function or method which takes or returns a TypeInfo must take 
or return it \emph{by value} (see e.g. the TypeName function below).
To print the name of a type use one of the template functions 
\begin{verbatim}
template <class T> std::string TypeName();
template <class T> std::string TypeName(const T&);
template <class T> std::string TypeName(bbtk::TypeInfo);
\end{verbatim}


\begin{verbatim}
BBTK_DEFINE_HUMAN_READABLE_TYPE_NAME(std::string,"string");
\end{verbatim}

\end{document} 
