\hypertarget{RWF_8c}{
\section{RWF.c File Reference}
\label{RWF_8c}\index{RWF.c@{RWF.c}}
}
Defines the Resource Wait Facility routines. 

{\tt \#include \char`\"{}IPBS/RWF.h\char`\"{}}\par
{\tt \#include \char`\"{}IPBS/RW.h\char`\"{}}\par


Include dependency graph for RWF.c:\begin{figure}[H]
\begin{center}
\leavevmode
\includegraphics[width=319pt]{RWF_8c__incl}
\end{center}
\end{figure}
\subsection*{Data Structures}
\begin{CompactItemize}
\item 
struct \hyperlink{struct__RWF__ctl}{\_\-RWF\_\-ctl}
\begin{CompactList}\small\item\em Control handle for the RWF routines. \item\end{CompactList}\end{CompactItemize}
\subsection*{Functions}
\begin{CompactItemize}
\item 
int \hyperlink{RWF_8c_a0}{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_8c_a1}{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_8c_a2}{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}\item 
int \hyperlink{RWF_8c_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_8c_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_8c_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_8c_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}\end{CompactItemize}


\subsection{Detailed Description}
Defines the Resource Wait Facility routines. 

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


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


This is just a convenience packaging of the RW routines. One allocates and initializes an RWF control structure containing a synchronization structure (the RW\_\-ctl block), a get routine and a free routine. The user then calls RWF\_\-get and RWF\_\-free to allocate resources.

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


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_8c_a3}{
\index{RWF.c@{RWF.c}!RWF_free@{RWF\_\-free}}
\index{RWF_free@{RWF\_\-free}!RWF.c@{RWF.c}}
\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_8c_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_8c_a4}{
\index{RWF.c@{RWF.c}!RWF_get@{RWF\_\-get}}
\index{RWF_get@{RWF\_\-get}!RWF.c@{RWF.c}}
\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_8c_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_8c_a5}{
\index{RWF.c@{RWF.c}!RWF_getW@{RWF\_\-getW}}
\index{RWF_getW@{RWF\_\-getW}!RWF.c@{RWF.c}}
\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_8c_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_8c_a6}{
\index{RWF.c@{RWF.c}!RWF_getW_toc@{RWF\_\-getW\_\-toc}}
\index{RWF_getW_toc@{RWF\_\-getW\_\-toc}!RWF.c@{RWF.c}}
\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_8c_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_8c_a1}{
\index{RWF.c@{RWF.c}!RWF_init@{RWF\_\-init}}
\index{RWF_init@{RWF\_\-init}!RWF.c@{RWF.c}}
\subsubsection[RWF\_\-init]{\setlength{\rightskip}{0pt plus 5cm}init 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_8c_a1}


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_8c_a0}{
\index{RWF.c@{RWF.c}!RWF_sizeof@{RWF\_\-sizeof}}
\index{RWF_sizeof@{RWF\_\-sizeof}!RWF.c@{RWF.c}}
\subsubsection[RWF\_\-sizeof]{\setlength{\rightskip}{0pt plus 5cm}int RWF\_\-sizeof (void)}}
\label{RWF_8c_a0}


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}