RW_protos.h File Reference

Resource Wait, function proto-types. callable version. More...

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

Functions
int	RW_disable (RW_ctl *rw)
	Disables wakeup calls.
int	RW_enable (RW_ctl *rw)
	Enables wakeup calls.
int	RW_enabled (const RW_ctl *rw)
	Returns the state of the enabled flag.
int	RW_init (RW_ctl *rw, RW_type type)
	Initializes the RW control structure.
int	RW_destroy (RW_ctl *rw)
	Destroys the data structures associate with an RW handle.
RW_key	RW_lock (RW_ctl *rw)
	Locks a resource so it can be manipulated in an interlocked fashion.
RW_keys	RW_lock2 (RW_ctl *rw_0, RW_ctl *rw_1)
	Locks two resource so they can be manipulated in an interlocked fashion.
int	RW_unlock (RW_ctl *rw, RW_key key)
	This routine unlocks a previously locked resource.
int	RW_unlock2 (RW_ctl *rw_0, RW_ctl *rw_1, RW_keys keys)
	This routine unlocks a previously locked resource.
RW_key	RW_wait (RW_ctl *rw, RW_key key)
	Blocks a task/thread until there is a reasonable chance that a resource is available.
RW_key	RW_wake (RW_ctl *rw, RW_key key)
	This provides the signaling mechanism to wake up a thread of code which is waiting for a resource.
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().
RW_state	RW_tmr_init (RW_tmr *tmr, RW_ctl *rw, const TOC *toc)
	Initializes a Resource Wait timer based on the toc. If TOC is TOC_NOWAIT or TOV_FOREVER, no timer is initialized.
RW_state	RW_tmr_lock (RW_tmr *tmr, RW_state state)
	Locks the resource.
RW_state	RW_tmr_wait (RW_tmr *tmr, RW_state state)
	Waits until the timer expires or another task calls RW__tmr_wake indicating that another attempt be made to allocate the resource.
RW_state	RW_tmr_unlock (RW_tmr *tmr, RW_state state)
	Unlocks the resource.
RW_state	RW_tmr_destroy (RW_tmr *tmr, RW_state state)
	Destroys the tmr RW handle. This should be called before exiting the routine doing the allocation, since it will cleanup any outstanding timers among other things.

---

Detailed Description

Resource Wait, function proto-types. callable version.

Author:

JJRussell - russell@slac.stanford.edu

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

---

Function Documentation

int RW_destroy

(

RW_ctl *

rw

)

Destroys the data structures associate with an RW handle.

Parameters:

rw

Pointer to the RW handle to destroy

References _RW_waitctl_u::bf, _RW_ctl::cond, _RW_ctl::mutex, and _RW_ctl::waiting.

Referenced by FORK_destroy(), LI_destroy(), PL_destroy(), QI_destroy(), RNG_destroy(), and RWF_destroy().

int RW_disable

(

RW_ctl *

rw

)

Disables wakeup calls.

Parameters:

rw

The resource wait control structure

Return values:

	0	RW was previously disabled
	!=0	RW was previously enabled

Wakeup calls are disabled by this call. Effectively wakeup calls issued during the time the RW control structure is disabled are pended until reenabled by calling RW_enable().

int RW_enable

(

RW_ctl *

rw

)

Enables wakeup calls.

Parameters:

rw

The resource wait control structure

Return values:

	0	RW was previously disabled
	!=0	RW was previously enabled

Wakeup calls are enabled by this call. The routine also issues a wakeup if there are any pending wakeup calls.

int RW_enabled

(

const RW_ctl *

rw

)

Returns the state of the enabled flag.

Parameters:

rw

The resource wait control structure

Return values:

	0	RW is currently disabled
	!=0	RW is currently enabled

Warning:

As with all queries of this type, the answer is only good until it changes. The user is cautioned on its usage. It is primarily provided as a debugging tool.

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().

int RW_init	(	RW_ctl *	rw,
		RW_type	type
	)

Initializes the RW control structure.

Parameters:

	rw	The RW structure to initialize
	type	The type of RW to create, see RW_type for details.

References _RW_ctl::cond, _RW_ctl::mutex, _RW_waitctl_u::si, and _RW_ctl::waiting.

Referenced by FORK_create(), LI_init(), PL_init(), QI_init(), RNG_init(), and RWF_init().

RW_key RW_lock

(

RW_ctl *

rw

)

Locks a resource so it can be manipulated in an interlocked fashion.

Parameters:

rw

The RW handle

RW_keys RW_lock2	(	RW_ctl *	rw_0,
		RW_ctl *	rw_1
	)

Locks two resource so they can be manipulated in an interlocked fashion.

Returns:

A set of keys to be passed to the RW_unlock2 routine

Parameters:

	rw_0	The RW handle of the first resource to be locked
	rw_1	The RW handle of the second resource to be locked

RW_state RW_tmr_destroy	(	RW_tmr *	tmr,
		RW_state	state
	)

Destroys the tmr RW handle. This should be called before exiting the routine doing the allocation, since it will cleanup any outstanding timers among other things.

Parameters:

	tmr	The RW timer handle
	state	The current state

Returns:

The updated state.

Warning:

Failure to call this routine if a timer is still on the WUT que is fatal.

RW_state RW_tmr_init	(	RW_tmr *	tmr,
		RW_ctl *	rw,
		const TOC *	toc
	)

Initializes a Resource Wait timer based on the toc. If TOC is TOC_NOWAIT or TOV_FOREVER, no timer is initialized.

Parameters:

	tmr	The Resource Wait Timer to initialize
	rw	The underlying Resource Wait control block
	toc	The TimeOut control block. Two special values are recognized TOC_NOWAIT and TOC_FOREVER.

Returns:

A state variable which should be passed to RW_tmr_block.

RW_state RW_tmr_lock	(	RW_tmr *	tmr,
		RW_state	state
	)

Locks the resource.

Parameters:

	tmr	The RW timer handle
	state	The current RW state

Returns:

The update RW state.

RW_state RW_tmr_unlock	(	RW_tmr *	tmr,
		RW_state	state
	)

Unlocks the resource.

Parameters:

	tmr	The RW timer handle
	state	The current RW state

Returns:

The update RW state.

RW_state RW_tmr_wait	(	RW_tmr *	tmr,
		RW_state	state
	)

Waits until the timer expires or another task calls RW__tmr_wake indicating that another attempt be made to allocate the resource.

Parameters:

	tmr	A previously initialized timer resource handle
	state	The current RW state

Returns:

The updated RW state.

int RW_unlock	(	RW_ctl *	rw,
		RW_key	key
	)

This routine unlocks a previously locked resource.

Parameters:

	rw	The RW handle
	key	The key used to lock the resource, returned from RW_lock

Referenced by RW_get().

int RW_unlock2	(	RW_ctl *	rw_0,
		RW_ctl *	rw_1,
		RW_keys	keys
	)

This routine unlocks a previously locked resource.

Parameters:

	rw_0	The RW handle of the first resource to be unlocked
	rw_1	The RW handle of the second resource to be unlocked
	keys	The keys used to lock the resources, returned from RW_lock2

int RW_wait	(	RW_ctl *	rw,
		RW_key	key
	)

Blocks a task/thread until there is a reasonable chance that a resource is available.

Parameters:

	rw	The RW handle
	key	The key used to unlock the interrupts

Returns:

Status

int RW_wake	(	RW_ctl *	rw,
		RW_key	key
	)

This provides the signaling mechanism to wake up a thread of code which is waiting for a resource.

Parameters:

	rw	The RW handle
	key	The key used to unlock the resource.

Return values:

Status

This routine checks if any thread is waiting for a resource, and if so wakes that thread. The resource should be locked on entry to this routine. This routine always exits with the resource still locked.