\hypertarget{RW_8c}{
\section{RW.c File Reference}
\label{RW_8c}\index{RW.c@{RW.c}}
}
Defines the Resource Wait routines. 

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


Include dependency graph for RW.c:\begin{figure}[H]
\begin{center}
\leavevmode
\includegraphics[width=316pt]{RW_8c__incl}
\end{center}
\end{figure}
\subsection*{Functions}
\begin{CompactItemize}
\item 
int \hyperlink{RW_8c_a0}{RW\_\-free} (\hyperlink{struct__RW__ctl}{RW\_\-ctl} $\ast$rw, \hyperlink{RW__comdefs_8h_a3}{RW\_\-free\_\-cb} free, void $\ast$ctx, void $\ast$resource, void $\ast$amount)
\begin{CompactList}\small\item\em Frees a resource, potentially waking up a task pending on an \hyperlink{RW_8c_a1}{RW\_\-get()}. \item\end{CompactList}\item 
void $\ast$ \hyperlink{RW_8c_a1}{RW\_\-get} (\hyperlink{struct__RW__ctl}{RW\_\-ctl} $\ast$rw, \hyperlink{RW__comdefs_8h_a2}{RW\_\-get\_\-cb} get, void $\ast$ctx, void $\ast$amount)
\begin{CompactList}\small\item\em Attempts to allocate a resource using the provided get routine. Whether the resource is available or not, this routine returns immediately with the return value of the get routine. See \hyperlink{RW_8c_a2}{RW\_\-get\-W()} and \hyperlink{RW_8c_a3}{RW\_\-get\-W\_\-toc()} for versions that implement waiting. If the resource is disabled, the routine returns NULL. \item\end{CompactList}\item 
void $\ast$ \hyperlink{RW_8c_a2}{RW\_\-get\-W} (\hyperlink{struct__RW__ctl}{RW\_\-ctl} $\ast$rw, \hyperlink{RW__comdefs_8h_a2}{RW\_\-get\_\-cb} get, void $\ast$ctx, 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 \hyperlink{RW_8c_a1}{RW\_\-get()}. If a waiting with a timeout is desired, see \hyperlink{RW_8c_a3}{RW\_\-get\-W\_\-toc()}. \item\end{CompactList}\item 
void $\ast$ \hyperlink{RW_8c_a3}{RW\_\-get\-W\_\-toc} (\hyperlink{struct__RW__ctl}{RW\_\-ctl} $\ast$rw, \hyperlink{RW__comdefs_8h_a2}{RW\_\-get\_\-cb} get, void $\ast$ctx, 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 \hyperlink{RW_8c_a1}{RW\_\-get()}. If a waiting with no timeout is desired, see \hyperlink{RW_8c_a3}{RW\_\-get\-W\_\-toc()}. \item\end{CompactList}\end{CompactItemize}


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

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


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


\subsection{Function Documentation}
\hypertarget{RW_8c_a0}{
\index{RW.c@{RW.c}!RW_free@{RW\_\-free}}
\index{RW_free@{RW\_\-free}!RW.c@{RW.c}}
\subsubsection[RW\_\-free]{\setlength{\rightskip}{0pt plus 5cm}int RW\_\-free (\hyperlink{struct__RW__ctl}{RW\_\-ctl} $\ast$ {\em rw}, \hyperlink{RW__comdefs_8h_a3}{RW\_\-free\_\-cb} {\em free}, void $\ast$ {\em ctx}, void $\ast$ {\em resource}, void $\ast$ {\em amount})}}
\label{RW_8c_a0}


Frees a resource, potentially waking up a task pending on an \hyperlink{RW_8c_a1}{RW\_\-get()}. 

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em rw}]The RW handle \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 {\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.

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em ctx}]Context parameter to the free routine \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}
Note that while the three parameters to the free routine are given suggestive names, they are, in fact, just void $\ast$'s, so the user is free to pass any 32-bit value that he wishes.\hypertarget{RW_8c_a1}{
\index{RW.c@{RW.c}!RW_get@{RW\_\-get}}
\index{RW_get@{RW\_\-get}!RW.c@{RW.c}}
\subsubsection[RW\_\-get]{\setlength{\rightskip}{0pt plus 5cm}void $\ast$ RW\_\-get (\hyperlink{struct__RW__ctl}{RW\_\-ctl} $\ast$ {\em rw}, \hyperlink{RW__comdefs_8h_a2}{RW\_\-get\_\-cb} {\em get}, void $\ast$ {\em ctx}, void $\ast$ {\em amount})}}
\label{RW_8c_a1}


Attempts to allocate a resource using the provided get routine. Whether the resource is available or not, this routine returns immediately with the return value of the get routine. See \hyperlink{RW_8c_a2}{RW\_\-get\-W()} and \hyperlink{RW_8c_a3}{RW\_\-get\-W\_\-toc()} for versions that implement waiting. If the resource is disabled, the routine returns NULL. 

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em rw}]The RW handle \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


\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em ctx}]A context parameter passed to the {\em get\/} routine. \item[{\em amount}]The amount of the resource being requested.\end{description}
\end{Desc}
\begin{Desc}
\item[Returns:]A pointer to the garnered resource or NULL if the resource is unavailable or the resource is disabled.\end{Desc}
This routine locks access to the resource pool while the get is being performed.

While the names of the two parameters to the {\em get\/} routine are suggestive, they are, in fact, just two void $\ast$'s, so the get routine may make any use of them it pleases.\hypertarget{RW_8c_a2}{
\index{RW.c@{RW.c}!RW_getW@{RW\_\-getW}}
\index{RW_getW@{RW\_\-getW}!RW.c@{RW.c}}
\subsubsection[RW\_\-getW]{\setlength{\rightskip}{0pt plus 5cm}void $\ast$ RW\_\-get\-W (\hyperlink{struct__RW__ctl}{RW\_\-ctl} $\ast$ {\em rw}, \hyperlink{RW__comdefs_8h_a2}{RW\_\-get\_\-cb} {\em get}, void $\ast$ {\em ctx}, void $\ast$ {\em amount})}}
\label{RW_8c_a2}


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 \hyperlink{RW_8c_a1}{RW\_\-get()}. If a waiting with a timeout is desired, see \hyperlink{RW_8c_a3}{RW\_\-get\-W\_\-toc()}. 

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em rw}]The RW handle \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


\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em ctx}]A context parameter passed to the {\em get\/} routine. \item[{\em amount}]The amount of the resource being requested. \end{description}
\end{Desc}
\begin{Desc}
\item[Returns:]A pointer to the garnered 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{RW_8c_a0}{RW\_\-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 names of the two parameters to the {\em get\/} routine are suggestive, they are, in fact, just two void $\ast$'s, so the get routine may make any use of them it pleases.\hypertarget{RW_8c_a3}{
\index{RW.c@{RW.c}!RW_getW_toc@{RW\_\-getW\_\-toc}}
\index{RW_getW_toc@{RW\_\-getW\_\-toc}!RW.c@{RW.c}}
\subsubsection[RW\_\-getW\_\-toc]{\setlength{\rightskip}{0pt plus 5cm}void $\ast$ RW\_\-get\-W\_\-toc (\hyperlink{struct__RW__ctl}{RW\_\-ctl} $\ast$ {\em rw}, \hyperlink{RW__comdefs_8h_a2}{RW\_\-get\_\-cb} {\em get}, void $\ast$ {\em ctx}, void $\ast$ {\em amount}, const \hyperlink{struct__TOC}{TOC} $\ast$ {\em toc})}}
\label{RW_8c_a3}


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 \hyperlink{RW_8c_a1}{RW\_\-get()}. If a waiting with no timeout is desired, see \hyperlink{RW_8c_a3}{RW\_\-get\-W\_\-toc()}. 

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em rw}]The RW handle \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


\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em ctx}]A context parameter passed to the {\em get\/} routine. \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 garnered resource, in reality whatever non-NULL value the user provided get routine returns.\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{RW_8c_a0}{RW\_\-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 names of the two parameters to the {\em get\/} routine are suggestive, they are, in fact, just two void $\ast$'s, so the get routine may make any use of them it pleases.

\begin{Desc}
\item[Warning:]Also note that timeouts are not disabled even if the RW has been disabled. In other words, if the timeout period expires during the time the RW is disabled, NULL is returned. This leaves the caller in somewhat of a quandry, did the routine timeout because the resource was exhausted or because it was disabled. This routine cannot determine this fact any better than the caller. If necessary, the caller has two tools at his disposal for resolving this issue, he can poll his own resource to see if it is exhausted and he can query the RW as to its enabled/disabled state. Both these methods have the same problem, {\em i.e\/}. the state can at any time. The issue of why a routine times out is largely philosophical for the same reason. It may have been that a wait was initially caused by a lack of resources, but before the resource was refreashed, the controlling RW was diabled.\end{Desc}