RW.ih File Reference

Resource Wait, inline version. More...

#include <PBI/Inline.h>
#include <PBI/Attribute.h>
#include <PBS/RW.h>
#include <PBS/RW_pubdefs.h>

Defines
#define	RW__EXP_PROTO   INLINE_USR_EXP_PROTO
	Export Prototype spec.
#define	RW__LCL_PROTO   INLINE_USR_LCL_PROTO
	Internal Prototype spec.
#define	RW__EXP_FNC   INLINE_USR_EXP_FNC
	Export Function declaration.
#define	RW__LCL_FNC   INLINE_USR_LCL_FNC
	Internal Function declaration.
Functions
RW__EXP_PROTO int	RW__disable (RW_ctl *rw) ATTR_UNUSED_OK
	Disables wakeup calls.
RW__EXP_PROTO int	RW__enable (RW_ctl *rw) ATTR_UNUSED_OK
	Enables wakeup calls.
RW__EXP_PROTO int	RW__enabled (const RW_ctl *rw) ATTR_UNUSED_OK
	Returns the state of the enabled flag.
RW__EXP_PROTO RW_key	RW__lock (RW_ctl *rw) ATTR_UNUSED_OK
	Locks a resource so it can be manipulated in an interlocked fashion.
RW__EXP_PROTO RW_keys	RW__lock2 (RW_ctl *rw_0, RW_ctl *rw_1) ATTR_UNUSED_OK
	Locks two resource so they can be manipulated in an interlocked fashion.
RW__EXP_PROTO int	RW__unlock (RW_ctl *rw, RW_key key) ATTR_UNUSED_OK
	This routine unlocks a previously locked resource.
RW__EXP_PROTO int	RW__unlock2 (RW_ctl *rw_0, RW_ctl *rw_1, RW_keys keys) ATTR_UNUSED_OK
	This routine unlocks a previously locked resource.
RW__EXP_PROTO RW_key	RW__wait (RW_ctl *rw, RW_key key) ATTR_UNUSED_OK
	Blocks a task/thread until there is a reasonable chance that a resource is available.
RW__EXP_PROTO int	RW__wake (RW_ctl *rw, RW_key key) ATTR_UNUSED_OK
	This provides the signaling mechanism to wake up a thread of code which is waiting for a resource.

---

Detailed Description

Resource Wait, inline version.

Author:

JJRussell - russell@slac.stanford.edu

   CVS $Id: RW.ih,v 1.6 2011/03/24 23:05:44 apw Exp $

---

Function Documentation

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

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

Referenced by LI__disable(), and QI__disable().

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

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

Referenced by LI__enable(), and QI__enable().

RW__EXP_FNC 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 was previously disabled
	!=0	RW was previously 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.

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

Referenced by LI__enabled(), LI__remove(), QI__enabled(), and QI__remove().

RW__EXP_PROTO RW_key RW__lock

(

RW_ctl *

rw

)

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

Returns:

A key to be passed to the RW__unlock routine.

Parameters:

rw

The RW handle

References BUG_check(), and _RW_ctl::mutex.

Referenced by FORK_disable(), FORK_enable(), FPA_free(), FPA_get(), LI__insert(), LI__jam(), LI__remove(), PL__insert(), PL__jam(), PL__remove(), PL__wake(), QI__insert(), QI__jam(), QI__remove(), RNG_free(), RW__disable(), RW__enable(), RW_free(), RW_get(), and RW_getW().

RW__EXP_PROTO 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

References BUG_check(), and _RW_ctl::mutex.

Referenced by LI__append(), LI__prepend(), QI__append(), and QI__prepend().

RW__EXP_PROTO 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

References BUG_check(), and _RW_ctl::mutex.

Referenced by FORK_disable(), FORK_enable(), FPA_free(), FPA_get(), LI__insert(), LI__jam(), LI__remove(), PL__insert(), PL__jam(), PL__remove(), PL__wake(), QI__insert(), QI__jam(), QI__remove(), RNG_free(), RW__disable(), RW__enable(), RW_free(), and RW_getW().

RW__EXP_PROTO 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

References BUG_check(), and _RW_ctl::mutex.

Referenced by LI__append(), LI__prepend(), QI__append(), and QI__prepend().

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

Parameters:

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

Returns:

Status

References _RW_waitctl_u::bf, BUG_check(), _RW_ctl::cond, _RW_ctl::mutex, and _RW_ctl::waiting.

Referenced by RW_getW().

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

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

Referenced by FPA_free(), LI__insert(), LI__jam(), PL__insert(), PL__jam(), PL__wake(), QI__insert(), QI__jam(), RNG_free(), RW__enable(), and RW_free().