RWF.h File Reference

Resource Wait Faility, generic resource allocation and freeing. More...

#include <PBS/RW_comdefs.h>
#include <PBS/TOC_comdefs.h>

Typedefs
typedef struct _RWF_ctl	RWF_ctl
	Typedef for struct _RWF_ctl, the RWF control handle.
Functions
int	RWF_sizeof (void)
	Returns the size, in bytes, of an RWF control handle.
int	RWF_init (RWF_ctl *rwf, RW_type type, void *ctx, RW_get_cb get, RW_free_cb free)
	Initializes the RWF control structure.
int	RWF_free (RWF_ctl *rwf, void *resource, void *amount)
	Frees a resource, potentially waking up a task pending on an RWF_getW() or RWF_getW_toc().
void *	RWF_get (RWF_ctl *rwf, void *amount)
	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 RWF_getW() and RWF_getW_toc() for versions that implement waiting.
void *	RWF_getW (RWF_ctl *rwf, 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 *	RWF_getW_toc (RWF_ctl *rwf, 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().
int	RWF_destroy (RWF_ctl *rwf)
	Destroys an RWF control handle, returning any resources garnered by the RWF_init() routine.

---

Detailed Description

Resource Wait Faility, generic resource allocation and freeing.

Author:

JJRussell - russell@slac.stanford.edu

   CVS $Id: RWF.h,v 1.3 2011/03/24 23:05:44 apw Exp $

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 RWF_get() (or one of its waiting variants, RWF_getW() or RWF_getW_toc()) to allocate the resource and 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 RWF_free() to return the resource.

USAGE EXAMPLE

   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);

---

Function Documentation

int RWF_destroy

(

RWF_ctl *

rwf

)

Destroys an RWF control handle, returning any resources garnered by the RWF_init() routine.

Parameters:

rwf

The RWF control handle to destroy.

Returns:

Status

References _RWF_ctl::rw, and RW_destroy().

int RWF_free	(	RWF_ctl *	rwf,
		void *	resource,
		void *	amount
	)

Frees a resource, potentially waking up a task pending on an RWF_getW() or RWF_getW_toc().

Parameters:

	rwf	The RWF handle
	resource	The resource being freed.
	amount	Typically the amount being freed.

Returns:

The return value of the free routine.

While the name of the amount parameter is suggestive, it is, in fact, just a void *, so the free routine may make any use of it that it pleases.

References _RWF_ctl::ctx, _RWF_ctl::free, _RWF_ctl::rw, and RW_free().

void* RWF_get	(	RWF_ctl *	rwf,
		void *	amount
	)

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 RWF_getW() and RWF_getW_toc() for versions that implement waiting.

Parameters:

	rwf	The RWF handle
	amount	The amount of the resource being requested.

Returns:

A pointer to the acquired resource.

This routine locks access to the resource pool while the get is being performed.

While the name of the amount parameter is suggestive, it is, in fact, just a void *, so the get routine may make any use of it that it pleases.

References _RWF_ctl::ctx, _RWF_ctl::get, _RWF_ctl::rw, and RW_get().

void* RWF_getW	(	RWF_ctl *	rwf,
		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:

	rwf	The RWF handle
	amount	The amount of the resource being requested.

Returns:

A pointer to the acquired 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 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 amount parameter is suggestive, it is, in fact, just a void *, so the get routine may make any use of it that it pleases.

References _RWF_ctl::ctx, _RWF_ctl::get, _RWF_ctl::rw, and RW_getW().

void* RWF_getW_toc	(	RWF_ctl *	rwf,
		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:

	rwf	The RWF handle
	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 acquired 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 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 amount parameter is suggestive, it is, in fact, just a void *, so the get routine may make any use of it that it pleases.

References _RWF_ctl::ctx, _RWF_ctl::get, _RWF_ctl::rw, and RW_getW_toc().

int RWF_init	(	RWF_ctl *	rwf,
		RW_type	type,
		void *	ctx,
		RW_get_cb	get,
		RW_free_cb	free
	)

Initializes the RWF control structure.

Parameters:

	rwf	The RWF structure to initialize
	type	The type of RW to create, see RW_type for details.
	ctx	A context parameter passed as the first argument to both the get and free routines.
	get	A user provide 'get' routine. The function signature is

                void *resource = (*get)(void *ctx, void *amount);

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

Parameters:

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

Note that while the amount parameter name is suggestive that this represents the amount of a resource gathered, it is, in fact, just a void *, 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 RW_free().

References _RWF_ctl::ctx, _RWF_ctl::free, _RWF_ctl::get, _RWF_ctl::rw, and RW_init().

int RWF_sizeof

(

void

)

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

Returns:

The size, in bytes, of an RWF control handle