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 Each input of a black box instance has a Status,
  30 of type IOStatus (defined in bbtkConnection.h)
  31 which can take one of the three values:
  32 \begin{itemize}
  33 \item UPTODATE (==0): The input did not change since last processing
  34 \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.
  35 \item OUTOFDATE (==2): The input changed since last processing and is out-of-date with the amont box to which it is connected.
  36 \end{itemize}
  37 The status of an input is stored by the class BlackBoxInputConnector.
  38
  39 Each output of a black box instance also has a Status,
  40 of type IOStatus but which can only take the two values:
  41 \begin{itemize}
  42 \item UPTODATE (==0): The output is up-to-date (the box need not be reprocessed).
  43 \item OUTOFDATE (==2): [Initial value on construction] The output is out-of-date (the box need to be reprocessed).
  44 \end{itemize}
  45 The status of an output is stored by the class BlackBoxOutputConnector.
  46
  47
  48 The main execution method of a black box is bbExecute.
  49 bbExecute checks werther the box is not already executing (bbGetExecuting())
  50 to prevent reentrance and
  51 checks werther the execution is not frozen (bbGlobalGetFreezeExecution()).
  52 If it is not the case then it calls bbBackwardUpdate which is
  53 the main recursive pipeline processing method of a box, giving it a
  54 NULL Connection::Pointer.
  55
  56 bbBackwardUpdate is defined in AtomicBlackBox:
  57
  58 \bigskip\hrule\begin{verbatim}
  59 void AtomicBlackBox::bbBackwardUpdate ( Connection::Pointer caller )
  60 {
  61   // Updates the box inputs. Returns the max input IOStatus after update
  62   IOStatus s = bbUpdateInputs();
  63   // If at least one input is modified or BoxProcessMode=='Always'
  64   if ( (s != UPTODATE) || bbBoxProcessModeIsAlways() )
  65     {
  66       // User process
  67       bbProcess();
  68       // Displays the window (overloaded in widget Blackboxes, WxBlackBox, KWBlackBox, etc.)
  69       bbShowWindow(caller);
  70       // Compute the final status of inputs and outputs
  71       bbComputePostProcessStatus();
  72     }
  73 }
  74 \end{verbatim}\hrule\bigskip
  75
  76 bbUpdateInputs iterates over the InputConnector of the box and
  77 calls BackwardUpdate on each one. It returns the max of the final
  78 status of the input connectors:
  79 \bigskip\hrule\begin{verbatim}
  80 IOStatus BlackBox::bbUpdateInputs()
  81 {
  82   IOStatus s = UPTODATE;
  83   InputConnectorMapType::iterator i;
  84   for ( i = bbGetInputConnectorMap().begin();
  85         i!= bbGetInputConnectorMap().end(); ++i)
  86     {
  87       i->second->BackwardUpdate();
  88       IOStatus t = i->second->GetStatus();
  89       if (t > s) s = t;
  90     }
  91   return s;
  92
  93 }
  94 \end{verbatim}\hrule\bigskip
  95
  96 \bigskip\hrule\begin{verbatim}
  97 void BlackBoxInputConnector::BackwardUpdate()
  98 {
  99   // If connected and OUTOFDATE : recursive update
 100   // Post-update status is updated by the connection
 101   // (either MODIFIED or OUTOFDATE)
 102    if ( mConnection && (mStatus == OUTOFDATE) )
 103     {
 104       mConnection->BackwardUpdate();
 105     }
 106 }
 107 \end{verbatim}\hrule\bigskip
 108
 109 \bigskip\hrule\begin{verbatim}
 110 void Connection::BackwardUpdate()
 111 {
 112   // Calls bbBackwardUpdate on the initial box
 113   mFrom->bbBackwardUpdate(GetThisPointer<Connection>());
 114   // Transfers the data from the initial box output to the
 115   // final box input adapting it if necessary
 116   TransferData();
 117   // Updates the status of the final box input
 118   IOStatus s = MODIFIED;
 119   if ( mFrom->bbGetOutputConnector(mOutput).GetStatus() == OUTOFDATE)
 120     s = OUTOFDATE,
 121   mTo->bbGetInputConnector(mInput).SetStatus(s);
 122 }
 123 \end{verbatim}\hrule\bigskip
 124
 125
 126
 127 % ==========================================
 128 \section{Misc}
 129 % ==========================================
 130
 131 \subsection{Displaying messages}
 132
 133 \begin{verbatim}
 134 bbtkMessage("Kind",level,"message "<<"to "<<" display : i="<<i<<std::endl);
 135 bbtkDebugMessage("Kind",level,"message "<<"to "<<" display : i="<<i<<std::endl);
 136 \end{verbatim}
 137
 138 \section{Types and RTTI}
 139
 140
 141
 142 In \bbtk the class conveying the information on a type is
 143 \begin{verbatim}
 144 bbtk::TypeInfo
 145 \end{verbatim}
 146 which is simply a typedef on
 147 \begin{verbatim}
 148 const std::type_info&
 149 \end{verbatim}
 150 Remember that all constructors of the std::type\_info class are private,
 151 hence objects can only be created by the operator \texttt{typeid}
 152 which returns a const reference on a type\_info.
 153 Hence the \bbtk type TypeInfo conveys that const reference
 154 and cannot be itself referenced.
 155 Any function or method which takes or returns a TypeInfo must take
 156 or return it \emph{by value} (see e.g. the TypeName function below).
 157 To print the name of a type use one of the template functions
 158 \begin{verbatim}
 159 template <class T> std::string TypeName();
 160 template <class T> std::string TypeName(const T&);
 161 template <class T> std::string TypeName(bbtk::TypeInfo);
 162 \end{verbatim}
 163
 164
 165 \begin{verbatim}
 166 BBTK_DEFINE_HUMAN_READABLE_TYPE_NAME(std::string,"string");
 167 \end{verbatim}
 168
 169 \end{document}