RW.c File Reference

Defines the Resource Wait routines. More...

#include <PBS/RW.h>

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.7 2011/03/31 01:09:46 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.

References RW__lock(), RW__unlock(), and RW__wake().

Referenced by RWF_free().

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.

References _RW_waitctl_u::bf, RW__lock(), RW_unlock(), and _RW_ctl::waiting.

Referenced by RWF_get().

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.

References _RW_waitctl_u::bf, RW__lock(), RW__unlock(), RW__wait(), and _RW_ctl::waiting.

Referenced by FPA_getW(), LI__removeW(), PL__getW(), PL__removeW(), QI__removeW(), and RWF_getW().

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.

References _RW_waitctl_u::bf, RW__tmr_destroy(), RW__tmr_init(), RW__tmr_lock(), RW__tmr_unlock(), RW__tmr_wait(), RW_M_TIMEDOUT, and _RW_ctl::waiting.

Referenced by FPA_getW_toc(), LI__removeW_toc(), PL__getW_toc(), PL__removeW_toc(), QI__removeW_toc(), and RWF_getW_toc().