\hypertarget{TBD_8c}{
\section{TBD.c File Reference}
\label{TBD_8c}\index{TBD.c@{TBD.c}}
}
Task Block of Data manager, callable implementation, common platform. 

{\tt \#include $<$string.h$>$}\par
{\tt \#include \char`\"{}PBS/TBD.h\char`\"{}}\par
{\tt \#include \char`\"{}TBD\_\-pvtdefs.h\char`\"{}}\par


Include dependency graph for TBD.c:\begin{figure}[H]
\begin{center}
\leavevmode
\includegraphics[width=107pt]{TBD_8c__incl}
\end{center}
\end{figure}


\subsection{Detailed Description}
Task Block of Data manager, callable implementation, common platform. 

\begin{Desc}
\item[Author:]JJRussell - \href{mailto:russell@slac.stanford.edu}{\tt russell@slac.stanford.edu}\end{Desc}


\footnotesize\begin{verbatim}    CVS $Id: TBD.c,v 1.4 2004/12/07 16:13:11 russell Exp $
\end{verbatim}
\normalsize


\begin{Desc}
\item[SYNOPSIS]TBD manages an array of N (likely 32) words that act as global, but task specific, variables. The real value of this block is that no context handle is needed to locate them. TBD acts as a green layer between the POSIX and VXWORKS implementations, although, as always in PBS, the implementation is tilted towards efficiency on the VXWORKS platform.\end{Desc}
Under POSIX, the address of the data area is associated with a task dependent key. The OS is responsible for making sure that the key is updated across task switches. Accesses to the maintained data array cost a pthread function call to translate the key to the data array address.

Under VXWORKS, the address of a location holding a pointer to the data area is made known to the OS. VXWORKS is responsible for making sure that this location is updated across task switches. Because the address of the data location is stored in a well-known external variable, no special routines are needed to reference the address. However, to ensure portability, TBD provides access routines in the form of inline functions. See the usage section for details.

\begin{Desc}
\item[USAGE]The user need provide no TBD specific initialization beyond establishing the value of his parameter. The TBD default is to initialize the data cell word with 0. The user interface consists of \#- \hyperlink{TBD_8h_a6}{TBD\_\-locate()}, to locate the storage array \#- TBD\_\-get (), to get a value from the storage array \#- TBD\_\-put (), to put a value into the storage array\end{Desc}
The user calls {\em \hyperlink{TBD_8h_a6}{TBD\_\-locate()}\/} to locate the address of the managed area. TBD\_\-locate will return a non-NULL result only to tasks that have handed the TBD facility an area to manage by doing a {\em \hyperlink{TBD_8h_a1}{TBD\_\-add()}\/}. TBD\_\-locate will return NULL not only from tasks not calling TBD\_\-add, but also if it is called from ISR (interrupt) level. As a convenience, the TBD facility also maintains one context block to be used to store context at interrupt level. Because there is extra overhead associated with using this feature, a separate call, \hyperlink{TBD_8h_a7}{TBD\_\-glocate()} (generalized locate) should be used if the caller wishes to make use of this feature. Note the {\em \hyperlink{TBD_8h_a7}{TBD\_\-glocate()}\/} will still return NULL for tasks that have not done a \hyperlink{TBD_8h_a1}{TBD\_\-add()}

Once a task has added a block of memory to be managed (the TASK routines do this call as a convenience), the rest of the code generally does accesses by calling {\em \hyperlink{TBD_8h_a6}{TBD\_\-locate()}\/} or \hyperlink{TBD_8h_a7}{TBD\_\-glocate()}. After checking that this pointer is non-NULL, the caller accesses the managed data area by calling {\em \hyperlink{TBD_8h_a5}{TBD\_\-put()}\/} for writes and {\em \hyperlink{TBD_8h_a4}{TBD\_\-get()}\/} for reads. Although a traditional call interface is provided for each routine, the user is encouraged to use the inline versions. Under Vx\-Works, the inlines are in the 3-6 instruction area.

\begin{Desc}
\item[EXAMPLE]Here are is an example of implementing a read and replace function. Note that this is not an interlocked version of the routine. It also uses the traditional callable functions. The inlines are the recommended form.\end{Desc}


\footnotesize\begin{verbatim}       static inline void *replace (int index, void *value)
       {
          void **tbd = TBD_locate ();
          void  *org = TBD_get (tbd, index);

          TBD_put (tbd, index, value);
          return org;
       }
\end{verbatim}
\normalsize
