GLAST/LAT > DAQ and FSW > FSW > Doxygen Index > PBS / V2-10-11

Constituent: pbs     Tag: sun-gcc

Interface   Data Structures   File List   Data Fields   Globals  
g » glast » flight » SVC » source » PBS » V2-10-11 » src

RW.c File Reference

Defines the Resource Wait routines. More...

#include "PBS/RW.h"

Include dependency graph for RW.c:


Functions

int RW_free (RW_ctl *rw, RW_free_cb free, void *ctx, void *resource, void *amount)
 Frees a resource, potentially waking up a task pending on an RW_get().
void * RW_get (RW_ctl *rw, RW_get_cb get, void *ctx, void *amount)
 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 RW_getW() and RW_getW_toc() for versions that implement waiting. If the resource is disabled, the routine returns NULL.
void * RW_getW (RW_ctl *rw, RW_get_cb get, void *ctx, void *amount)
 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 RW_get(). If a waiting with a timeout is desired, see RW_getW_toc().
void * RW_getW_toc (RW_ctl *rw, RW_get_cb get, void *ctx, void *amount, const TOC *toc)
 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 RW_get(). If a waiting with no timeout is desired, see RW_getW_toc().

Detailed Description

Defines the Resource Wait routines.

Author:
JJRussell - russell@slac.stanford.edu
   CVS $Id: RW.c,v 1.4 2004/10/20 14:36:53 russell Exp $

Function Documentation

int RW_free (  RW_ctl *  rw,
RW_free_cb  free,
void *  ctx,
void *  resource,
void *  amount
) 
 

Frees a resource, potentially waking up a task pending on an RW_get().

Parameters:
rw The RW handle
free User provide callback routine to implement the actual freeing of the resource. The function signature is
                     (*free)(void *ctx, void *resource, void *amount);

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

Parameters:
ctx Context parameter to the free routine
resource The resource being freed.
amount Typically the amount being freed.
Returns:
The return value of the free routine.
Note that while the three parameters to the free routine are given suggestive names, they are, in fact, just void *'s, so the user is free to pass any 32-bit value that he wishes.

void * RW_get (  RW_ctl *  rw,
RW_get_cb  get,
void *  ctx,
void *  amount
) 
 

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 RW_getW() and RW_getW_toc() for versions that implement waiting. If the resource is disabled, the routine returns NULL.

Parameters:
rw The RW handle
get A user provide 'get' routine. The function signature is
                void *resource = (*get)(void *ctx, void *amount);

Parameters:
ctx A context parameter passed to the get routine.
amount The amount of the resource being requested.
Returns:
A pointer to the garnered resource or NULL if the resource is unavailable or the resource is disabled.
This routine locks access to the resource pool while the get is being performed.

While the names of the two parameters to the get routine are suggestive, they are, in fact, just two void *'s, so the get routine may make any use of them it pleases.

void * RW_getW (  RW_ctl *  rw,
RW_get_cb  get,
void *  ctx,
void *  amount
) 
 

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 RW_get(). If a waiting with a timeout is desired, see RW_getW_toc().

Parameters:
rw The RW handle
get A user provide 'get' routine. The function signature is
                void *resource = (*get)(void *ctx, void *amount);

Parameters:
ctx A context parameter passed to the get routine.
amount The amount of the resource being requested.
Returns:
A pointer to the garnered resource
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 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 get routine are suggestive, they are, in fact, just two void *'s, so the get routine may make any use of them it pleases.

void * RW_getW_toc (  RW_ctl *  rw,
RW_get_cb  get,
void *  ctx,
void *  amount,
const TOC *  toc
) 
 

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 RW_get(). If a waiting with no timeout is desired, see RW_getW_toc().

Parameters:
rw The RW handle
get A user provide 'get' routine. The function signature is
                void *resource = (*get)(void *ctx, void *amount);

Parameters:
ctx A context parameter passed to the get routine.
amount The amount of the resource being requested.
toc The timeout control structure. TOC_NOWAIT and TOC_FOREVER may be specified.
Returns:
A pointer to the garnered resource, in reality whatever non-NULL value the user provided get routine returns.
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 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 get routine are suggestive, they are, in fact, just two void *'s, so the get routine may make any use of them it pleases.

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, 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.

Generated on Wed Dec 20 06:56:02 2006 by  doxygen 1.4.4