kernel/doc/bbtkDevelopersGuide/bbtkDevelopersGuide.tex

   1 \documentclass[a4paper,11pt,final]{article}
   2 \input{config.tex}
   3
   4
   5
   6 \begin{document}
   7 \bbtkGuide[Developer's Guide]
   8
   9
  10
  11
  12
  13 % ==========================================
  14 \tableofcontents
  15 % ==========================================
  16
  17 % ==========================================
  18 \newpage
  19 \hrule
  20
  21 % ==========================================
  22 \section{Introduction}
  23 % ==========================================
  24
  25 % ==========================================
  26 \section{Pipeline processing algorithm}
  27 % ==========================================
  28
  29 % ==========================================
  30 \subsection{Input and output status}
  31 % ==========================================
  32 Each input of a black box has a Status,
  33 of type IOStatus (defined in bbtkConnection.h)
  34 which can take one of the three values:
  35 \begin{itemize}
  36 \item UPTODATE (==0): The input did not change since last processing
  37 \item MODIFIED (==1): [Initial value on construction] The input changed since last processing but is synchronized with the amont box output to which it is connected, if any. This status has only a NOTIFICATION purpose, to let the processing method of the box know which inputs have changed since last time. If it is connected, a MODIFIED input will not call the amont box update during pipeline execution.
  38 \item OUTOFDATE (==2): The input changed since last processing and is NOT synchronized with the amont box output to which it is connected. This means that the pipeline update must recurse to the amont box next time it is executed, in order to update the input value.
  39 \end{itemize}
  40 The status of an input is stored by the class BlackBoxInputConnector.
  41
  42 Each output of a black box instance also has a Status,
  43 of type IOStatus but which can only take the two values:
  44 \begin{itemize}
  45 \item UPTODATE (==0): The output is up-to-date (the box does not need to be reprocessed).
  46 \item OUTOFDATE (==2): [Initial value on construction] The output is out-of-date (the box needs to be reprocessed).
  47 \end{itemize}
  48 The status of an output is stored by the class BlackBoxOutputConnector.
  49
  50 If a box output 'O' is connected to another box input 'I' then there are some consistency constraints on their I/O statuses:
  51 \begin{itemize}
  52 \item If 'I' is UPTODATE then 'O' is necesseraly UPTODATE
  53 \item If 'I' is MODIFIED then 'O' is necesseraly UPTODATE
  54 \item If 'I' is OUTOFDATE then 'O' can be in any Status (The case 'O' is UPTODATE occurs for example when the amont box was created and executed - hence setting its outputs UPTODATE - *BEFORE* being connected to the aval box)
  55 \item If 'O' is UPTODATE then 'I' can be in any Status
  56 \item If 'O' is OUTOFDATE then 'I' is necessarly OUTOFDATE
  57 \end{itemize}
  58
  59 The status of an input can be modified:
  60 \begin{itemize}
  61 \item By BlackBox::bbSetStatusAndPropagate which is called by:
  62 \begin{itemize}
  63 \item BlackBox::bbSetInput : it is set to MODIFIED
  64 \item BlackBox::bbSignalOutputModification
  65 \item BlackBox::bbConnectInput which is called when a Connection is connected to the input : it is set to OUTOFDATE
  66 \item Connection::OnOutputChange
  67 \end{itemize}
  68 \item By BlackBox::bbComputePostProcessStatus which is called after bbProcess in AtomicBlackBox::bbBackwardUpdate : if the input status is MODIFIED then it is changed to UPTODATE.
  69 \item By Connection::BackwardUpdate which is responsible for updating its amont box, transfering the output value to the input and updating the input status. If, after processing the amont box, the output status is UPTODATE then the new input status is MODIFIED, else if the output status is OUTOFDATE then the new input status is OUTOFDATE.
  70 \end{itemize}
  71
  72 The status of an output is modifed in:
  73 \begin{itemize}
  74 \item By BlackBox::bbSetStatusAndPropagate, when propagating the new input status to the outputs.
  75 \item By BlackBox::bbComputePostProcessStatus, which is called after bbProcess in AtomicBlackBox::bbBackwardUpdate. The new output status is :
  76 \begin{itemize}
  77 \item UPTODATE if all the box inputs are UPTODATE and the BoxProcessMode is *NOT* 'Always'
  78 \item OUTOFDATE in other cases
  79 \end{itemize}
  80 \end{itemize}
  81
  82 % ==========================================
  83 \subsection{Pipeline execution}
  84 % ==========================================
  85 The main execution method of a black box is bbExecute.
  86 bbExecute checks werther the box is not already executing (bbGetExecuting())
  87 to prevent reentrance and
  88 checks werther the execution is not frozen (bbGlobalGetFreezeExecution()).
  89 If it is not the case then it calls bbBackwardUpdate which is
  90 the main recursive pipeline processing method of a box, giving it a
  91 NULL Connection::Pointer.
  92
  93 bbBackwardUpdate is defined in AtomicBlackBox:
  94
  95 \bigskip\hrule\begin{verbatim}
  96 void AtomicBlackBox::bbBackwardUpdate ( Connection::Pointer caller )
  97 {
  98   // Updates the box inputs. Returns the max input IOStatus after update
  99   IOStatus s = bbUpdateInputs();
 100   // If at least one input is modified or BoxProcessMode=='Always'
 101   if ( (s != UPTODATE) || bbBoxProcessModeIsAlways() )
 102     {
 103       // User process
 104       bbProcess();
 105       // Displays the window (overloaded in widget Blackboxes, WxBlackBox, KWBlackBox, etc.)
 106       bbShowWindow(caller);
 107       // Compute the final status of inputs and outputs
 108       bbComputePostProcessStatus();
 109     }
 110 }
 111 \end{verbatim}\hrule\bigskip
 112
 113 bbUpdateInputs iterates over the InputConnector of the box and
 114 calls BackwardUpdate on each one. It returns the max of the final
 115 status of the input connectors:
 116 \bigskip\hrule\begin{verbatim}
 117 IOStatus BlackBox::bbUpdateInputs()
 118 {
 119   IOStatus s = UPTODATE;
 120   InputConnectorMapType::iterator i;
 121   for ( i = bbGetInputConnectorMap().begin();
 122         i!= bbGetInputConnectorMap().end(); ++i)
 123     {
 124       i->second->BackwardUpdate();
 125       IOStatus t = i->second->GetStatus();
 126       if (t > s) s = t;
 127     }
 128   return s;
 129
 130 }
 131 \end{verbatim}\hrule\bigskip
 132
 133 \bigskip\hrule\begin{verbatim}
 134 void BlackBoxInputConnector::BackwardUpdate()
 135 {
 136   // If connected and OUTOFDATE : recursive update
 137   // Post-update status is updated by the connection
 138   // (either MODIFIED or OUTOFDATE)
 139    if ( mConnection && (mStatus == OUTOFDATE) )
 140     {
 141       mConnection->BackwardUpdate();
 142     }
 143 }
 144 \end{verbatim}\hrule\bigskip
 145
 146 \bigskip\hrule\begin{verbatim}
 147 void Connection::BackwardUpdate()
 148 {
 149   // Calls bbBackwardUpdate on the initial box
 150   mFrom->bbBackwardUpdate(GetThisPointer<Connection>());
 151   // Transfers the data from the initial box output to the
 152   // final box input adapting it if necessary
 153   TransferData();
 154   // Updates the status of the final box input
 155   IOStatus s = MODIFIED;
 156   if ( mFrom->bbGetOutputConnector(mOutput).GetStatus() == OUTOFDATE)
 157     s = OUTOFDATE;
 158   mTo->bbGetInputConnector(mInput).SetStatus(s);
 159 }
 160 \end{verbatim}\hrule\bigskip
 161
 162
 163
 164 % ==========================================
 165 \section{Misc}
 166 % ==========================================
 167
 168 \subsection{Displaying messages}
 169
 170 \begin{verbatim}
 171 bbtkMessage("Kind",level,"message "<<"to "<<" display : i="<<i<<std::endl);
 172 bbtkDebugMessage("Kind",level,"message "<<"to "<<" display : i="<<i<<std::endl);
 173 \end{verbatim}
 174
 175 \section{Types and RTTI}
 176
 177
 178
 179 In \bbtk the class conveying the information on a type is
 180 \begin{verbatim}
 181 bbtk::TypeInfo
 182 \end{verbatim}
 183 which is simply a typedef on
 184 \begin{verbatim}
 185 const std::type_info&
 186 \end{verbatim}
 187 Remember that all constructors of the std::type\_info class are private,
 188 hence objects can only be created by the operator \texttt{typeid}
 189 which returns a const reference on a type\_info.
 190 Hence the \bbtk type TypeInfo conveys that const reference
 191 and cannot be itself referenced.
 192 Any function or method which takes or returns a TypeInfo must take
 193 or return it \emph{by value} (see e.g. the TypeName function below).
 194 To print the name of a type use one of the template functions
 195 \begin{verbatim}
 196 template <class T> std::string TypeName();
 197 template <class T> std::string TypeName(const T&);
 198 template <class T> std::string TypeName(bbtk::TypeInfo);
 199 \end{verbatim}
 200
 201
 202 \begin{verbatim}
 203 BBTK_DEFINE_HUMAN_READABLE_TYPE_NAME(std::string,"string");
 204 \end{verbatim}
 205
 206 \end{document}