\hypertarget{RWF_8h}{
\section{RWF.h File Reference}
\label{RWF_8h}\index{RWF.h@{RWF.h}}
}
Resource Wait Faility, generic resource allocation and freeing. 

{\tt \#include \char`\"{}IPBS/RW\_\-comdefs.h\char`\"{}}\par
{\tt \#include \char`\"{}IPBS/TOC\_\-comdefs.h\char`\"{}}\par


Include dependency graph for RWF.h:\begin{figure}[H]
\begin{center}
\leavevmode
\includegraphics[width=193pt]{RWF_8h__incl}
\end{center}
\end{figure}


This graph shows which files directly or indirectly include this file:\begin{figure}[H]
\begin{center}
\leavevmode
\includegraphics[width=89pt]{RWF_8h__dep__incl}
\end{center}
\end{figure}
\subsection*{Typedefs}
\begin{CompactItemize}
\item 
\hypertarget{RWF_8h_a0}{
typedef \hyperlink{struct__RWF__ctl}{\_\-RWF\_\-ctl} \hyperlink{RWF_8h_a0}{RWF\_\-ctl}}
\label{RWF_8h_a0}

\begin{CompactList}\small\item\em Typedef for struct \hyperlink{struct__RWF__ctl}{\_\-RWF\_\-ctl}, the RWF control handle. \item\end{CompactList}\end{CompactItemize}
\subsection*{Functions}
\begin{CompactItemize}
\item 
int \hyperlink{RWF_8h_a1}{RWF\_\-sizeof} (void)
\begin{CompactList}\small\item\em Returns the size, in bytes, of an RWF control handle. \item\end{CompactList}\item 
int \hyperlink{RWF_8h_a2}{RWF\_\-init} (\hyperlink{struct__RWF__ctl}{RWF\_\-ctl} $\ast$rwf, \hyperlink{RW__type_8h_a2}{RW\_\-type} type, void $\ast$ctx, \hyperlink{RW__comdefs_8h_a2}{RW\_\-get\_\-cb} get, \hyperlink{RW__comdefs_8h_a3}{RW\_\-free\_\-cb} free)
\begin{CompactList}\small\item\em Initializes the RWF control structure. \item\end{CompactList}\item 
int \hyperlink{RWF_8h_a3}{RWF\_\-free} (\hyperlink{struct__RWF__ctl}{RWF\_\-ctl} $\ast$rwf, void $\ast$resource, void $\ast$amount)
\begin{CompactList}\small\item\em Frees a resource, potentially waking up a task pending on an \hyperlink{RWF_8c_a5}{RWF\_\-get\-W()} or \hyperlink{RWF_8c_a6}{RWF\_\-get\-W\_\-toc()}. \item\end{CompactList}\item 
void $\ast$ \hyperlink{RWF_8h_a4}{RWF\_\-get} (\hyperlink{struct__RWF__ctl}{RWF\_\-ctl} $\ast$rwf, void $\ast$amount)
\begin{CompactList}\small\item\em Attempts to allocate a resource using the provided free routine. Whether the resource is available or not, this routine returns immediately with the return value of the get routine. See {\em \hyperlink{RWF_8c_a5}{RWF\_\-get\-W()}\/} and {\em \hyperlink{RWF_8c_a6}{RWF\_\-get\-W\_\-toc()}\/} for versions that implement waiting. \item\end{CompactList}\item 
void $\ast$ \hyperlink{RWF_8h_a5}{RWF\_\-get\-W} (\hyperlink{struct__RWF__ctl}{RWF\_\-ctl} $\ast$rwf, void $\ast$amount)
\begin{CompactList}\small\item\em Attempts to allocate a resource using the provided get routine. This routine blocks until the get routine returns a non-NULL value. If nowaiting is desired, see {\em \hyperlink{RW_8c_a1}{RW\_\-get()}\/}. If a waiting with a timeout is desired, see {\em \hyperlink{RW_8c_a3}{RW\_\-get\-W\_\-toc()}\/}. \item\end{CompactList}\item 
void $\ast$ \hyperlink{RWF_8h_a6}{RWF\_\-get\-W\_\-toc} (\hyperlink{struct__RWF__ctl}{RWF\_\-ctl} $\ast$rwf, void $\ast$amount, const \hyperlink{struct__TOC}{TOC} $\ast$toc)
\begin{CompactList}\small\item\em Attempts to allocate a resource using the provided get routine. This routine blocks until the get routine returns a non-NULL value or until the timeout period expires. If nowaiting is desired, see {\em \hyperlink{RW_8c_a1}{RW\_\-get()}\/}. If a waiting with no timeout is desired, see {\em \hyperlink{RW_8c_a3}{RW\_\-get\-W\_\-toc()}\/}. \item\end{CompactList}\item 
int \hyperlink{RWF_8h_a7}{RWF\_\-destroy} (\hyperlink{struct__RWF__ctl}{RWF\_\-ctl} $\ast$rwf)
\begin{CompactList}\small\item\em Destroys an RWF control handle, returning any resources garnered by the \hyperlink{RWF_8c_a1}{RWF\_\-init()} routine. \item\end{CompactList}\end{CompactItemize}


\subsection{Detailed Description}
Resource Wait Faility, generic resource allocation and freeing. 

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


\footnotesize\begin{verbatim}   CVS $Id: RWF.h,v 1.1.1.1 2006/02/10 21:45:36 saxton Exp $
\end{verbatim}
\normalsize


\begin{Desc}
\item[SYNOPSIS]These routines allow a user to get and free resources in a interlocked and blind fashion. A control structure is initialized with two call back routine; one 'gets' or allocates the resource and the other frees the resource. These get and free routines need not be thread-safe, RWF does the locking. The caller is then uses \hyperlink{RWF_8c_a4}{RWF\_\-get()} (or one of its waiting variants, \hyperlink{RWF_8c_a5}{RWF\_\-get\-W()} or \hyperlink{RWF_8c_a6}{RWF\_\-get\-W\_\-toc()}) to allocate the resource and \hyperlink{RWF_8c_a3}{RWF\_\-free()} to free the resource. The caller, thus knows next to nothing about how the resource has been acquired nor need concern himself with how the resource is freed. This feature makes these routines ideal for passing resources between task threads. Typically a higher priority task allocates the resource and eventually passes this resource to a lower priority task (commonly called lending/borrowing the memory). The lower priority task need only call \hyperlink{RWF_8c_a3}{RWF\_\-free()} to return the resource.\end{Desc}
\begin{Desc}
\item[USAGE EXAMPLE]\end{Desc}


\footnotesize\begin{verbatim}   Q_head   q;
   int status;
   struct q_blk { Q_node *node; int buf[2]; } blks[2], *blk;
   RWF_ctl *rwf = MBA_alloc (RWF_sizeof ())

   / * Initialize the resource Q and make some block available * /
   Q_init   (&q);
   Q_insert (&q, &blks[0].node);
   Q_insert (&q, &blks[1].node);

   / * Initialize the RWF control block * /
   RWF_init (rwf, RW_K_TYPE_BLOCKING_FIFO_WTO, &q, Q_remove, Q_insert);
   .

   / * Allocate a block * /
   blk    = RWF_getW (rwf, NOT_NEEDED);
   .
   .
   / * Free the block * /
   status = RWF_free (rwf, blk, NOT_NEEDED);
\end{verbatim}
\normalsize


\subsection{Function Documentation}
\hypertarget{RWF_8h_a7}{
\index{RWF.h@{RWF.h}!RWF_destroy@{RWF\_\-destroy}}
\index{RWF_destroy@{RWF\_\-destroy}!RWF.h@{RWF.h}}
\subsubsection[RWF\_\-destroy]{\setlength{\rightskip}{0pt plus 5cm}int RWF\_\-destroy (\hyperlink{struct__RWF__ctl}{RWF\_\-ctl} $\ast$ {\em rwf})}}
\label{RWF_8h_a7}


Destroys an RWF control handle, returning any resources garnered by the \hyperlink{RWF_8c_a1}{RWF\_\-init()} routine. 

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em rwf}]The RWF control handle to destroy. \end{description}
\end{Desc}
\begin{Desc}
\item[Returns:]Status\end{Desc}
\hypertarget{RWF_8h_a3}{
\index{RWF.h@{RWF.h}!RWF_free@{RWF\_\-free}}
\index{RWF_free@{RWF\_\-free}!RWF.h@{RWF.h}}
\subsubsection[RWF\_\-free]{\setlength{\rightskip}{0pt plus 5cm}int RWF\_\-free (\hyperlink{struct__RWF__ctl}{RWF\_\-ctl} $\ast$ {\em rwf}, void $\ast$ {\em resource}, void $\ast$ {\em amount})}}
\label{RWF_8h_a3}


Frees a resource, potentially waking up a task pending on an \hyperlink{RWF_8c_a5}{RWF\_\-get\-W()} or \hyperlink{RWF_8c_a6}{RWF\_\-get\-W\_\-toc()}. 

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em rwf}]The RWF handle \item[{\em resource}]The resource being freed. \item[{\em amount}]Typically the amount being freed. \end{description}
\end{Desc}
\begin{Desc}
\item[Returns:]The return value of the free routine.\end{Desc}
While the name of the {\em amount\/} parameter is suggestive, it is, in fact, just a void $\ast$, so the free routine may make any use of it that it pleases.\hypertarget{RWF_8h_a4}{
\index{RWF.h@{RWF.h}!RWF_get@{RWF\_\-get}}
\index{RWF_get@{RWF\_\-get}!RWF.h@{RWF.h}}
\subsubsection[RWF\_\-get]{\setlength{\rightskip}{0pt plus 5cm}void$\ast$ RWF\_\-get (\hyperlink{struct__RWF__ctl}{RWF\_\-ctl} $\ast$ {\em rwf}, void $\ast$ {\em amount})}}
\label{RWF_8h_a4}


Attempts to allocate a resource using the provided free routine. Whether the resource is available or not, this routine returns immediately with the return value of the get routine. See {\em \hyperlink{RWF_8c_a5}{RWF\_\-get\-W()}\/} and {\em \hyperlink{RWF_8c_a6}{RWF\_\-get\-W\_\-toc()}\/} for versions that implement waiting. 

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em rwf}]The RWF handle \item[{\em amount}]The amount of the resource being requested. \end{description}
\end{Desc}
\begin{Desc}
\item[Returns:]A pointer to the acquired resource.\end{Desc}
This routine locks access to the resource pool while the get is being performed.

While the name of the {\em amount\/} parameter is suggestive, it is, in fact, just a void $\ast$, so the get routine may make any use of it that it pleases.\hypertarget{RWF_8h_a5}{
\index{RWF.h@{RWF.h}!RWF_getW@{RWF\_\-getW}}
\index{RWF_getW@{RWF\_\-getW}!RWF.h@{RWF.h}}
\subsubsection[RWF\_\-getW]{\setlength{\rightskip}{0pt plus 5cm}void$\ast$ RWF\_\-get\-W (\hyperlink{struct__RWF__ctl}{RWF\_\-ctl} $\ast$ {\em rwf}, void $\ast$ {\em amount})}}
\label{RWF_8h_a5}


Attempts to allocate a resource using the provided get routine. This routine blocks until the get routine returns a non-NULL value. If nowaiting is desired, see {\em \hyperlink{RW_8c_a1}{RW\_\-get()}\/}. If a waiting with a timeout is desired, see {\em \hyperlink{RW_8c_a3}{RW\_\-get\-W\_\-toc()}\/}. 

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em rwf}]The RWF handle \item[{\em amount}]The amount of the resource being requested. \end{description}
\end{Desc}
\begin{Desc}
\item[Returns:]A pointer to the acquired resource.\end{Desc}
This routine locks access to the resource pool while the get is being performed and waits until the resource is available. An equivalent call to \hyperlink{RWF_8c_a3}{RWF\_\-free()} will unblock this routine, and another attempt will be made to allocate the resource. If successful, as indicated by the get routine returning a non-NULL value, the resource will be returned to the caller. If unsuccessful, the routine will block again.

While the name of the {\em amount\/} parameter is suggestive, it is, in fact, just a void $\ast$, so the get routine may make any use of it that it pleases.\hypertarget{RWF_8h_a6}{
\index{RWF.h@{RWF.h}!RWF_getW_toc@{RWF\_\-getW\_\-toc}}
\index{RWF_getW_toc@{RWF\_\-getW\_\-toc}!RWF.h@{RWF.h}}
\subsubsection[RWF\_\-getW\_\-toc]{\setlength{\rightskip}{0pt plus 5cm}void$\ast$ RWF\_\-get\-W\_\-toc (\hyperlink{struct__RWF__ctl}{RWF\_\-ctl} $\ast$ {\em rwf}, void $\ast$ {\em amount}, const \hyperlink{struct__TOC}{TOC} $\ast$ {\em toc})}}
\label{RWF_8h_a6}


Attempts to allocate a resource using the provided get routine. This routine blocks until the get routine returns a non-NULL value or until the timeout period expires. If nowaiting is desired, see {\em \hyperlink{RW_8c_a1}{RW\_\-get()}\/}. If a waiting with no timeout is desired, see {\em \hyperlink{RW_8c_a3}{RW\_\-get\-W\_\-toc()}\/}. 

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em rwf}]The RWF handle \item[{\em amount}]The amount of the resource being requested. \item[{\em toc}]The timeout control structure. TOC\_\-NOWAIT and TOC\_\-FOREVER may be specified. \end{description}
\end{Desc}
\begin{Desc}
\item[Returns:]A pointer to the acquired resource.\end{Desc}
This routine locks access to the resource pool while the get is being performed and waits until the resource is available. An equivalent call to \hyperlink{RWF_8c_a3}{RWF\_\-free()} will unblock this routine, and another attempt will be made to allocate the resource. If successful, as indicated by the get routine returning a non-NULL value, the resource will be returned to the caller. If unsuccessful, the routine will block again until the timeout period expires or the resource becomes available.

While the name of the {\em amount\/} parameter is suggestive, it is, in fact, just a void $\ast$, so the get routine may make any use of it that it pleases.\hypertarget{RWF_8h_a2}{
\index{RWF.h@{RWF.h}!RWF_init@{RWF\_\-init}}
\index{RWF_init@{RWF\_\-init}!RWF.h@{RWF.h}}
\subsubsection[RWF\_\-init]{\setlength{\rightskip}{0pt plus 5cm}int RWF\_\-init (\hyperlink{struct__RWF__ctl}{RWF\_\-ctl} $\ast$ {\em rwf}, \hyperlink{RW__type_8h_a2}{RW\_\-type} {\em type}, void $\ast$ {\em ctx}, \hyperlink{RW__comdefs_8h_a2}{RW\_\-get\_\-cb} {\em get}, \hyperlink{RW__comdefs_8h_a3}{RW\_\-free\_\-cb} {\em free})}}
\label{RWF_8h_a2}


Initializes the RWF control structure. 

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em rwf}]The RWF structure to initialize \item[{\em type}]The type of RW to create, see RW\_\-type for details. \item[{\em ctx}]A context parameter passed as the first argument to both the {\em get\/} and {\em free\/} routines. \item[{\em get}]A user provide 'get' routine. The function signature is\end{description}
\end{Desc}


\footnotesize\begin{verbatim}                void *resource = (*get)(void *ctx, void *amount);
\end{verbatim}
\normalsize


A successful allocation returns resource as non-NULL. Typically {\em ctx\/} is a context parameter and {\em amount\/} is the amount of the resource being requested.

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em free}]User provide callback routine to implement the actual freeing of the resource. The function signature is\end{description}
\end{Desc}


\footnotesize\begin{verbatim}                   (*free)(void *ctx, void *resource, void *amount);
\end{verbatim}
\normalsize


where typically the {\em ctx\/} provides context to the free routine, the {\em resource\/} is a pointer to the resource being freed, and {\em amount\/} is the amount of the resource being freed.

Note that while the {\em amount\/} parameter name is suggestive that this represents the amount of a resource gathered, it is, in fact, just a void $\ast$, so the user is free to pass any 32-bit value that he wishes. Again, typically the freer will be handed the resource parameter and the amount parameter and be expected to just pass them on to \hyperlink{RW_8c_a0}{RW\_\-free()}.\hypertarget{RWF_8h_a1}{
\index{RWF.h@{RWF.h}!RWF_sizeof@{RWF\_\-sizeof}}
\index{RWF_sizeof@{RWF\_\-sizeof}!RWF.h@{RWF.h}}
\subsubsection[RWF\_\-sizeof]{\setlength{\rightskip}{0pt plus 5cm}int RWF\_\-sizeof (void)}}
\label{RWF_8h_a1}


Returns the size, in bytes, of an RWF control handle. 

\begin{Desc}
\item[Returns:]The size, in bytes, of an RWF control handle\end{Desc}