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{The library architecture}
  27 % ==========================================
  28
  29 % ==========================================
  30 \subsection{BlackBox and related classes}
  31 % ==========================================
  32
  33 % ==========================================
  34 \subsection{Factory and Package}
  35 % ==========================================
  36
  37 % ==========================================
  38 \subsection{Interpreter, VirtualExec, Executer and Transcriptor}
  39 % ==========================================
  40
  41 % ==========================================
  42 \subsection{WxGUI elements}
  43 % ==========================================
  44
  45 % ==========================================
  46 \subsection{Utilities}
  47 % ==========================================
  48
  49 % ==========================================
  50 \section{Pipeline processing algorithm}
  51 % ==========================================
  52
  53 % ==========================================
  54 \subsection{Input and output status}
  55 % ==========================================
  56 Each input of a black box has a Status,
  57 of type IOStatus (defined in bbtkConnection.h)
  58 which can take one of the three values:
  59 \begin{itemize}
  60 \item UPTODATE (==0): The input did not change since last processing
  61 \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.
  62 \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.
  63 \end{itemize}
  64 The status of an input is stored by the class BlackBoxInputConnector.
  65
  66 Each output of a black box instance also has a Status,
  67 of type IOStatus but which can only take the two values:
  68 \begin{itemize}
  69 \item UPTODATE (==0): The output is up-to-date (the box does not need to be reprocessed).
  70 \item OUTOFDATE (==2): [Initial value on construction] The output is out-of-date (the box needs to be reprocessed).
  71 \end{itemize}
  72 The status of an output is stored by the class BlackBoxOutputConnector.
  73
  74 If a box output 'O' is connected to another box input 'I' then there are some consistency constraints on their I/O statuses:
  75
  76 \begin{tabular}{|l|p{10cm}|}
  77 \hline
  78 If & then \\ \hline
  79 'I' is UPTODATE & 'O' is necesseraly UPTODATE\\
  80 'I' is MODIFIED & 'O' is necesseraly UPTODATE\\
  81 'I' is OUTOFDATE & '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)\\ \hline
  82 'O' is UPTODATE & 'I' can be in any Status\\
  83 'O' is OUTOFDATE & 'I' is necessarly OUTOFDATE\\ \hline
  84 \end{tabular}
  85
  86 The status of an input can be modified:
  87 \begin{itemize}
  88 \item By BlackBox::bbSetStatusAndPropagate which is called by:
  89 \begin{itemize}
  90 \item BlackBox::bbSetInput when a new value of an input is set.
  91 \item BlackBox::bbSignalOutputModification when the output which is connected to it is signaled as modified.
  92 \item BlackBox::bbConnectInput which is called when a Connection is connected to the input.
  93 \item Connection::OnOutputChange
  94 \end{itemize}
  95 \item By BlackBox::bbComputePostProcessStatus which is called after bbProcess in BlackBox::bbRecursiveExecute.
  96 \item By Connection::RecursiveExecute which is responsible for updating its amont box, transfering the output value to the input and updating the input status.
  97 \end{itemize}
  98
  99 The status of an output can be modifed in:
 100 \begin{itemize}
 101 \item By BlackBox::bbSetStatusAndPropagate, when propagating the new input status to the outputs.
 102 \item By BlackBox::bbComputePostProcessStatus, which is called after bbProcess in BlackBox::bbRecursiveExecute.
 103 \end{itemize}
 104
 105
 106 % ==========================================
 107 \subsection{Pipeline execution}
 108 % ==========================================
 109 The main execution method of a black box is bbExecute.
 110 bbExecute checks werther the box is not already executing (bbGetExecuting())
 111 to prevent reentrance and
 112 checks werther the execution is not frozen (bbGlobalGetFreezeExecution()).
 113 If it is not the case then it calls bbRecursiveExecute which is
 114 the main recursive pipeline processing method of a box.
 115
 116 bbRecursiveExecute does:
 117 \begin{enumerate}
 118 \item Update the inputs of the box calling bbUpdateInputs
 119 \item If at least one input is MODIFIED or OUTOFDATE or the
 120 BoxProcessMode is 'Always' then it:
 121 \begin{enumerate}
 122 \item Calls the virtual method bbProcess
 123 which is responsible for the actual box processing.
 124 bbProcess is overloaded in AtomicBlackBox to call a user defined method
 125 and in widget box descendents (WxBlackBox, KWBlackBox) to handle
 126 the widget creation.
 127 \item Compute the post-process statuses of inputs and outputs calling
 128 bbComputePostProcessStatus.
 129 \end{enumerate}
 130 \end{enumerate}
 131 \bigskip\hrule\begin{verbatim}
 132 void BlackBox::bbRecursiveExecute ( Connection::Pointer caller )
 133 {
 134   // Updates the box inputs. Returns the max input IOStatus after update
 135   IOStatus s = bbUpdateInputs();
 136   // If at least one input is modified or BoxProcessMode=='Always'
 137   if ( (s != UPTODATE) || bbBoxProcessModeIsAlways() )
 138     {
 139       // User process (virtual)
 140       bbProcess();
 141       // Compute the final status of inputs and outputs
 142       bbComputePostProcessStatus();
 143     }
 144 }
 145 \end{verbatim}\hrule\bigskip
 146
 147 bbUpdateInputs iterates the InputConnectorMap of the box and
 148 calls RecursiveExecute on each BlackBoxInputConnector.
 149 It returns the max of the final status of the input connectors:
 150 \bigskip\hrule\begin{verbatim}
 151 IOStatus BlackBox::bbUpdateInputs()
 152 {
 153   IOStatus s = UPTODATE;
 154   InputConnectorMapType::iterator i;
 155   for ( i = bbGetInputConnectorMap().begin();
 156         i!= bbGetInputConnectorMap().end(); ++i)
 157     {
 158       i->second->RecursiveExecute();
 159       IOStatus t = i->second->GetStatus();
 160       if (t > s) s = t;
 161     }
 162   return s;
 163 }
 164 \end{verbatim}\hrule\bigskip
 165
 166 bbComputPostProcessStatus computes the new status of inputs and outputs
 167 after box processing.
 168
 169 The input status update rules are simple:
 170
 171 \begin{tabular}{|lll|}
 172 \hline
 173 UPTODATE & remains & UPTODATE\\ \hline
 174 MODIFIED & becomes & UPTODATE\\ \hline
 175 OUTOFDATE & remains & OUTOFDATE\\ \hline
 176 \end{tabular}
 177
 178 The new output status is:
 179
 180 \begin{tabular}{|ll|}
 181 \hline
 182 OUTOFDATE & if any input is OUTOFDATE\\
 183 & or bbBoxProcessModeIsAlways() is true\\ \hline
 184 UPTODATE & in any other case\\ \hline
 185 \end{tabular}
 186
 187 \bigskip\hrule\begin{verbatim}
 188 void BlackBox::bbComputePostProcessStatus()
 189 {
 190   // A priori, the new output status is UPTODATE
 191   // except if the BoxProcessMode is always
 192   IOStatus new_output_status = UPTODATE;
 193   if (bbBoxProcessModeIsAlways()) new_output_status = OUTOFDATE;
 194
 195   // Update the input statuses
 196   InputConnectorMapType::iterator i;
 197   for ( i = bbGetInputConnectorMap().begin();
 198         i!= bbGetInputConnectorMap().end(); ++i)
 199   {
 200     IOStatus t = i->second->GetStatus();
 201     // If any input is OUTOFDATE then the outputs also are
 202     if (t == OUTOFDATE) new_output_status = OUTOFDATE;
 203     // A previously MODIFIED status turns to UPTODATE
 204     if (t==MODIFIED) i->second->SetStatus(UPTODATE);
 205   }
 206
 207   // Update the output statuses
 208   OutputConnectorMapType::iterator o;
 209   for ( o = bbGetOutputConnectorMap().begin();
 210         o!= bbGetOutputConnectorMap().end(); ++o)
 211   {
 212     o->second->SetStatus(new_output_status);
 213   }
 214 }
 215 \end{verbatim}\hrule\bigskip
 216
 217
 218 BlackBox::bbUpdateInputs may calls BlackBoxInputConnector::RecursiveExecute
 219 which is responsible for recursive update of the input value.
 220 If it is connected and its status is OUTOFDATE then it calls
 221 RecursiveExecute on the Connection which is plugged into:
 222 \bigskip\hrule\begin{verbatim}
 223 void BlackBoxInputConnector::RecursiveExecute()
 224 {
 225   // If connected and OUTOFDATE : recursive update
 226   // Post-update status is updated by the connection
 227   // (either MODIFIED or OUTOFDATE)
 228    if ( mConnection && (mStatus == OUTOFDATE) )
 229     {
 230       mConnection->RecursiveExecute();
 231     }
 232 }
 233 \end{verbatim}\hrule\bigskip
 234
 235 Connection::RecursiveExecute does:
 236 \begin{enumerate}
 237 \item Call bbRecursiveExecute on the initial box of the connection
 238 \item Transfer the data from the initial box output to the final box input, adpating it if needed (add crossref).
 239 \item Update the final box input status. It sets it to:
 240
 241 \begin{tabular}{lll}
 242 MODIFIED  & If the initial box output is & UPTODATE \\
 243 OUTOFDATE & If the initial box output is & OUTOFDATE
 244 \end{tabular}
 245 \end{enumerate}
 246
 247 \bigskip\hrule\begin{verbatim}
 248 void Connection::RecursiveExecute()
 249 {
 250   // Calls bbRecursiveExecute on the initial box
 251   mFrom->bbRecursiveExecute(GetThisPointer<Connection>());
 252   // Transfers the data from the initial box output to the
 253   // final box input adapting it if necessary
 254   TransferData();
 255   // Updates the status of the final box input
 256   IOStatus s = MODIFIED;
 257   if ( mFrom->bbGetOutputConnector(mOutput).GetStatus() == OUTOFDATE)
 258     s = OUTOFDATE;
 259   mTo->bbGetInputConnector(mInput).SetStatus(s);
 260 }
 261 \end{verbatim}\hrule\bigskip
 262
 263 % ==========================================
 264 \subsection{The main processing method (bbProcess) overloads}
 265 % ==========================================
 266
 267 BlackBox::bbProcess
 268
 269
 270
 271
 272 % ==========================================
 273 \section{Misc}
 274 % ==========================================
 275
 276 \subsection{Displaying messages}
 277
 278 \begin{verbatim}
 279 bbtkMessage("Kind",level,"message "<<"to "<<" display : i="<<i<<std::endl);
 280 bbtkDebugMessage("Kind",level,"message "<<"to "<<" display : i="<<i<<std::endl);
 281 \end{verbatim}
 282
 283 \section{Types and RTTI}
 284
 285
 286
 287 In \bbtk the class conveying the information on a type is
 288 \begin{verbatim}
 289 bbtk::TypeInfo
 290 \end{verbatim}
 291 which is simply a typedef on
 292 \begin{verbatim}
 293 const std::type_info&
 294 \end{verbatim}
 295 Remember that all constructors of the std::type\_info class are private,
 296 hence objects can only be created by the operator \texttt{typeid}
 297 which returns a const reference on a type\_info.
 298 Hence the \bbtk type TypeInfo conveys that const reference
 299 and cannot be itself referenced.
 300 Any function or method which takes or returns a TypeInfo must take
 301 or return it \emph{by value} (see e.g. the TypeName function below).
 302 To print the name of a type use one of the template functions
 303 \begin{verbatim}
 304 template <class T> std::string TypeName();
 305 template <class T> std::string TypeName(const T&);
 306 template <class T> std::string TypeName(bbtk::TypeInfo);
 307 \end{verbatim}
 308
 309
 310 \begin{verbatim}
 311 BBTK_DEFINE_HUMAN_READABLE_TYPE_NAME(std::string,"string");
 312 \end{verbatim}
 313
 314 \end{document}