PL_protos.h File Reference

Priority Lists, function proto-types. callable version. More...

#include <PBS/PL_comdefs.h>

Defines

#define PL_K_ALL   ((PL_list)(0xffffffff))

Specifies the list of all available ques.

#define PL_LIST(_que_id)   ((unsigned int)0x80000000 >> (_que_id))

Translates a que id into the equivalant que list.

#define PL_NLIST(_nques)   ((signed int)0x80000000 >> ((_nques) - 1))

Creates a list of corresponding to _nques.

#define PL_FIND(_pl_list)   FFSL(_pl_list)

Finds the next highest available que in the list.

#define PL_ADD(_pl_list, _que_id)   ((_pl_list) | PL_LIST(_que_id))

Adds the specified que to the specified que list.

#define PL_ELIMINATE(_pl_list, _que_id)   ((_pl_list) & ~PL_LIST(_que_id))

Eliminates the specified que from the specified que list.

Functions

int PL_init (PL_ctl *pl, PL_type type, int nques)

Initializes the list head of a doubly linked list to an empty list of the specified type.

int PL_destroy (PL_ctl *pl)

Destroys the data structures associate with a PL.

PL_list PL_wake (PL_ctl *pl, PL_list wake_list)

Issues a wake up call to the PL ques if any of ques in the wakeup list are currently active.

PL_que * PL_que_get (PL_ctl *pl, int que_id)

Locates a pointer to the que specified by que_id.

PL_node * PL_insert (PL_que *que, PL_node *node)

Adds a node to the tail of a PL managed que.

PL_node * PL_jam (PL_que *que, PL_node *node)

Adds a node to the head of a PL managed que.

PL_node * PL_remove (PL_ctl *pl, volatile const PL_list *wait_list, int *que_id)

Removes a node from the head of the highest priority non-empty que. If all eligible queues are empty, then PL_remove returns NULL immediately without blocking.

PL_node * PL_removeW (PL_ctl *pl, volatile const PL_list *wait_list, int *que_id)

Removes a node from the head of the highest priority non-empty que. If all eligible queues are empty, then PL_removeW waits indefinitely.

PL_node * PL_removeW_toc (PL_ctl *pl, volatile const PL_list *wait_list, int *que_id, const TOC *toc)

Removes a node from the head of the highest priority non-empty que. If all eligible queues are empty, then PL_removeW_toc waits the specified until the timeout expires.

PL_list PL_get (PL_ctl *pl)

Returns a list of the currently active ques.

PL_list PL_getW (PL_ctl *pl, volatile const PL_list *wait_list)

Returns a list of the currently active ques which, at the time of the call, is guaranteed to include at least one member of the wait list. The routine blocks indefinitely until this condition is met.

PL_list PL_getW_toc (PL_ctl *pl, volatile const PL_list *wait_list, const TOC *toc)

Returns a list of the currently active ques which, at the time of the call, is guaranteed to include at least one member of the wait list. The routine blocks until this condition is met or the timeout expires.

Detailed Description

Priority Lists, function proto-types. callable version.

Author:: JJRussell - russell@slac.stanford.edu

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

Define Documentation

#define PL_ADD	(	_pl_list,
		_que_id		)	((_pl_list) \| PL_LIST(_que_id))

Adds the specified que to the specified que list.

Parameters:

	_pl_list	The target que list
	_que_id	The id of the que to add

Return values:

The

que list with the specified que id added

This is typically used to construct the wait list parameter in the removal routines.

Referenced by PL__insert(), and PL__jam().

#define PL_ELIMINATE	(	_pl_list,
		_que_id		)	((_pl_list) & ~PL_LIST(_que_id))

Eliminates the specified que from the specified que list.

Parameters:

	_pl_list	The target que list
	_que_id	The que id to eliminate

Return values:

The

que list with the specified que eliminated

This is typically used after finding a que with PL_FIND to eliminate the found que.

Warning:: No check is performed to see if the specified que actually exists in the list. No harm comes from doing this, the returned list is always guaranteed to not contain the specified que, whether it was in the original list or not.

Referenced by pl__remove().

#define PL_FIND ( _pl_list ) FFSL(_pl_list)

Finds the next highest available que in the list.

Parameters:

_pl_list

The que list to scan

Returns:: The id of the highest available que

Warning:: The result is not defined for empty lists. The user should always check for an empty list before using this macro..

Referenced by pl__remove().

#define PL_K_ALL ((PL_list)(0xffffffff))

Specifies the list of all available ques.

This specifies the list of all available ques and is typically used as the wait list parameter in the removal routines.

#define PL_LIST ( _que_id ) ((unsigned int)0x80000000 >> (_que_id))

Translates a que id into the equivalant que list.

Returns:: The equivalent que list with this as the que associated with que_id as its sole member

Parameters:

_que_id

The que id to calculate the equivalent que list for

EXAMPLE: If one wished to compose the list corresponding to que 3

   list_of_only_que_3 = PL_LIST (3);

This would return the value 0x1000000, i.e. a list with the 3rd most significant bit set (counting MSB = 0).

Referenced by FORK_qdisable(), FORK_qenable(), and FORK_qenabled().

#define PL_NLIST ( _nques ) ((signed int)0x80000000 >> ((_nques) - 1))

Creates a list of corresponding to _nques.

Returns:: The equivalent que list with this many ques

Parameters:

_nques

The number of ques, this must be a number between 1 and 32.

EXAMPLE: If one wished to compose a list of 6 ques

   mask_of_all_ques = PL_NLIST (6);

This would return the value 0xFC000000, i.e. a list with the 6 most significant bits set.

Referenced by PL_init().

Function Documentation

void PL_destroy ( PL_ctl * pl )

Destroys the data structures associate with a PL.

Parameters:

pl

Pointer to the PL to destroy.

This routine frees any resources the PL list gathered when it was initialized. The actual resources released depends on both the platform and whether blocking and timeouts were requested.

References _PL_ctl::rw, and RW_destroy().

Referenced by FORK_destroy().

PL_list PL_get ( PL_ctl * pl )

Returns a list of the currently active ques.

Parameters:

pl

A previously initialized PL control structure.

Returns:: A list of the currently active ques.

Warning:: The caller is cautioned that the list returned only reflects the state of the active ques at the time of the call. Writers to the que may add active nodes to previously inactive ques or, in the case of multiple readers, other readers may remove nodes causing previously active ques to become inactive.

Note that in single reader usage, the returned list will always be at least a subset of the active ques. Since no other reader is removing nodes, the active list can only stay the same or get larger.

PL_list PL_getW	(	PL_ctl *	pl,
		volatile const PL_list *	wait_list
	)

Returns a list of the currently active ques which, at the time of the call, is guaranteed to include at least one member of the wait list. The routine blocks indefinitely until this condition is met.

Parameters:

	pl	A previously initialized PL control structure.
	wait_list	A pointer to the list of the ques to wait on. The wait is treated as an OR.

Returns:: The list of active ques. It is guaranteed to include at least one member in the wait list. Note that the list is not trimmed to the wait list. This would destroy information and the trimming is easily done by user

Warning:: The caller is cautioned that the list returned only reflects the state of the active ques at the time of the call. Writers to the que may add active nodes to previously inactive ques or, in the case of multiple readers, other readers may remove nodes causing previously active ques to become inactive.

Note that in single reader usage, the returned list will always be at least a subset of the active ques. Since no other reader is removing nodes, the active list can only stay the same or get larger.

PL_list PL_getW_toc	(	PL_ctl *	pl,
		volatile const PL_list *	wait_list,
		const TOC *	toc
	)

Returns a list of the currently active ques which, at the time of the call, is guaranteed to include at least one member of the wait list. The routine blocks until this condition is met or the timeout expires.

Parameters:

	pl	A previously initialized PL control structure.
	wait_list	A pointer to the list of the ques to wait on. The wait is treated as an OR.
	toc	The timeout control structure.

Returns:: The list of active ques. It is guaranteed to include at least one member in the wait list. Note that the list is not trimmed to the wait list. This would destroy information and the trimming is easily done by user

Warning:: The caller is cautioned that the list returned only reflects the state of the active ques at the time of the call. Writers to the que may add active nodes to previously inactive ques or, in the case of multiple readers, other readers may remove nodes causing previously active ques to become inactive.

Note that in single reader usage, the returned list will always be at least a subset of the active ques. Since no other reader is removing nodes, the active list can only stay the same or get larger.

int PL_init	(	PL_ctl *	pl,
		PL_type	type,
		int	nques
	)

Initializes the list head of a doubly linked list to an empty list of the specified type.

Parameters:

	pl	Pointer to the Priority Ques control structure to initialize.
	type	The type blocking/waiting, see PL_type
	nques	The number of ques to support

Return values:

	0,Success
	ENOMEM,Insufficient	memory
	ENOTSUP,Type	not supported.

References _PL_que::head, _PL_que::id, L_init(), _PL_ctl::mactive, _PL_ctl::mcfg, _PL_ctl::nques, _PL_que::pl, PL_NLIST, _PL_ctl::ques, _PL_ctl::rw, and RW_init().

Referenced by FORK_create().

PL_node * PL_insert	(	PL_que *	que,
		PL_node *	node
	)

Adds a node to the tail of a PL managed que.

Parameters:

	que	A PL managed que.
	node	The node to add to que

Returns:: Pointer to the old backward link. This can be used to test whether this was the first item on the queue.
If return_value == que, then the que was initially empty.

Adds the specified node to the tail of the que. If all nodes are added with the PL_insert routine, the que behaves as a FIFO.

PL * PL_jam	(	PL_que *	que,
		PL_node *	node
	)

Adds a node to the head of a PL managed que.

Parameters:

	que	A PL managed que.
	node	The node to add to que

Returns:: Pointer to the old forward link. This can be used to test whether this was the first item on the queue.
If return_value == list, then the que was initially empty

Adds the specified node to the head of the list. If all nodes are added with the PL_jam routine, the que behaves as a LIFO.

PL_que * PL_que_get	(	PL_ctl *	pl,
		int	que_id
	)

Locates a pointer to the que specified by que_id.

Parameters:

	pl	The priority list
	que_id	The id of the que to locate

Returns:: A pointer to the que specified by que_id or NULL if que_id specifies an invalid or non-configured que.

PL_node * PL_remove	(	PL_ctl *	pl,
		volatile const PL_list *	wait_list,
		int *	que_id
	)

Removes a node from the head of the highest priority non-empty que. If all eligible queues are empty, then PL_remove returns NULL immediately without blocking.

Parameters:

	pl	A previously initialized PL control structure.
	wait_list	A pointer to the list of the ques to wait on. The wait is treated as an OR.
	que_id	Returned with the id of the que the node was removed from.

Returns:: A pointer to the removed node, or NULL if all the queues are empty.

Removes the node at the head of the highest priority non-empty que. If the all eligible queues are empty, NULL is immediately returned. This routine does not block.

PL_node * PL_removeW	(	PL_ctl *	pl,
		volatile const PL_list *	wait_list,
		int *	que_id
	)

Removes a node from the head of the highest priority non-empty que. If all eligible queues are empty, then PL_removeW waits indefinitely.

Parameters:

	pl	A previously initialized PL control structure.
	wait_list	A pointer to the list of the ques to wait on. The wait is treated as an OR.
	que_id	Returned with the id of the que the node was removed from.

Returns:: A pointer to the removed node, or NULL if on error

Removes the highest priority available and eligible node from a PL. If all ques are empty, the routine blocks indefinitely or until something shows up or there is an error.

If there is an error, the routine returns NULL as its node. There are only two reasons NULL will be returned:

     1. Internal error
     2. The list of eligible ques does not include any configured ques.

PL_node * PL_removeW_toc	(	PL_ctl *	pl,
		volatile const PL_list *	wait_list,
		int *	que_id,
		const TOC *	toc
	)

Removes a node from the head of the highest priority non-empty que. If all eligible queues are empty, then PL_removeW_toc waits the specified until the timeout expires.

Parameters:

	pl	A previously initialized PL control structure.
	wait_list	A pointer to the list of the ques to wait on. The wait is treated as an OR.
	que_id	Returned with the id of the que the node was removed from
	toc	The timeout control. this maybe specified as TOC_FOREVER or TOC_NOWAIT.

Returns:: A pointer to the removed node, or NULL on error

Removes the node at the head of the highest priority non-empty que. If the all eligible queues are empty, then PL_removeW_toc waits until something shows up or the timeout period, specified by toc expires.

If there is an error, the routine returns NULL as its node. There are only three reasons NULL will be returned:

# Internal error
# The list of eligible ques does not include any configured ques.
# Timeout expired.

PL__EXP_FNC PL_list PL_wake	(	PL_ctl *	pl,
		PL_list	wakeup_list
	)

Issues a wake up call to the PL ques if any of ques in the wakeup list are currently active.

Parameters:

	pl	A previously initialized PL control structure.
	wakeup_list	The list of ques to issue the wakeup call on

Returns:: The list of active ques at the time the wake up call was issued.

This routine allows the user to effectively enable and disable the servicing of lists of ques. Remember that the wait list parameter passed to PL__remove(), PL__removeW() and PL__removeW_toc is passed as a volatile pointer. This means that some other piece of code is allowed to dynamically alter the contents of the wait list. However, if the remove routines are already pending on a list, the remove routines will never notice the change. Hence the reason for this routine.


Defines
#define	PL_K_ALL ((PL_list)(0xffffffff))
	Specifies the list of all available ques.
#define	PL_LIST(_que_id) ((unsigned int)0x80000000 >> (_que_id))
	Translates a que id into the equivalant que list.
#define	PL_NLIST(_nques) ((signed int)0x80000000 >> ((_nques) - 1))
	Creates a list of corresponding to _nques.
#define	PL_FIND(_pl_list) FFSL(_pl_list)
	Finds the next highest available que in the list.
#define	PL_ADD(_pl_list, _que_id) ((_pl_list) \| PL_LIST(_que_id))
	Adds the specified que to the specified que list.
#define	PL_ELIMINATE(_pl_list, _que_id) ((_pl_list) & ~PL_LIST(_que_id))
	Eliminates the specified que from the specified que list.
Functions
int	PL_init (PL_ctl *pl, PL_type type, int nques)
	Initializes the list head of a doubly linked list to an empty list of the specified type.
int	PL_destroy (PL_ctl *pl)
	Destroys the data structures associate with a PL.
PL_list	PL_wake (PL_ctl *pl, PL_list wake_list)
	Issues a wake up call to the PL ques if any of ques in the wakeup list are currently active.
PL_que *	PL_que_get (PL_ctl *pl, int que_id)
	Locates a pointer to the que specified by que_id.
PL_node *	PL_insert (PL_que que, PL_node node)
	Adds a node to the tail of a PL managed que.
PL_node *	PL_jam (PL_que que, PL_node node)
	Adds a node to the head of a PL managed que.
PL_node *	PL_remove (PL_ctl pl, volatile const PL_list wait_list, int *que_id)
	Removes a node from the head of the highest priority non-empty que. If all eligible queues are empty, then PL_remove returns NULL immediately without blocking.
PL_node *	PL_removeW (PL_ctl pl, volatile const PL_list wait_list, int *que_id)
	Removes a node from the head of the highest priority non-empty que. If all eligible queues are empty, then PL_removeW waits indefinitely.
PL_node *	PL_removeW_toc (PL_ctl pl, volatile const PL_list wait_list, int que_id, const TOC toc)
	Removes a node from the head of the highest priority non-empty que. If all eligible queues are empty, then PL_removeW_toc waits the specified until the timeout expires.
PL_list	PL_get (PL_ctl *pl)
	Returns a list of the currently active ques.
PL_list	PL_getW (PL_ctl pl, volatile const PL_list wait_list)
	Returns a list of the currently active ques which, at the time of the call, is guaranteed to include at least one member of the wait list. The routine blocks indefinitely until this condition is met.
PL_list	PL_getW_toc (PL_ctl pl, volatile const PL_list wait_list, const TOC *toc)
	Returns a list of the currently active ques which, at the time of the call, is guaranteed to include at least one member of the wait list. The routine blocks until this condition is met or the timeout expires.