PL.ih File Reference

Priority Lists, inline versions. More...

#include <PBS/FFS.ih>
#include <PBS/L.ih>
#include <PBS/RW.ih>
#include <PBS/PL.h>
#include <PBI/Inline.h>
#include <PBI/Attribute.h>
#include <PBI/PTR.h>

Defines
#define	PL__EXP_PROTO   INLINE_USR_EXP_PROTO
	Export Prototype spec.
#define	PL__LCL_PROTO   INLINE_USR_LCL_PROTO
	Internal Prototype spec.
#define	PL__EXP_FNC   INLINE_USR_EXP_FNC
	Export Function declaration.
#define	PL__LCL_FNC   INLINE_USR_LCL_FNC
	Internal Function declaration.
Functions
PL__EXP_PROTO PL_que *	PL__que_get (PL_ctl *pl, int que_id) ATTR_UNUSED_OK
	Locates a pointer to the que specified by que_id.
PL__EXP_PROTO PL_node *	PL__insert (PL_que *que, PL_node *node) ATTR_UNUSED_OK
	Adds a node to the tail of a PL managed que.
PL__EXP_PROTO PL_node *	PL__jam (PL_que *que, PL_node *node) ATTR_UNUSED_OK
	Adds a node to the head of a PL managed que.
PL__EXP_PROTO PL_node *	PL__remove (PL_ctl *pl, volatile const PL_list *wait_list, int *que_id) ATTR_UNUSED_OK
	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__EXP_PROTO PL_node *	PL__removeW (PL_ctl *pl, volatile const PL_list *wait_list, int *que_id) ATTR_UNUSED_OK
	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__EXP_PROTO PL_node *	PL__removeW_toc (PL_ctl *pl, volatile const PL_list *wait_list, int *que_id, const TOC *toc) ATTR_UNUSED_OK
	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__EXP_PROTO PL_list	PL__get (PL_ctl *pl) ATTR_UNUSED_OK
	Returns a list of the currently active ques.
PL__EXP_PROTO PL_list	PL__getW (PL_ctl *pl, volatile const PL_list *list) ATTR_UNUSED_OK
	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__EXP_PROTO PL_list	PL__getW_toc (PL_ctl *pl, volatile const PL_list *list, const TOC *toc) ATTR_UNUSED_OK
	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.
PL__LCL_FNC PL_node *	pl__remove (PL_ctl *pl, volatile const PL_list *wait_list, int *que_id)
	Bare bones, non-interlocked removal routine. This is for internal use only.
PL__EXP_FNC PL_list	PL__wake (PL_ctl *pl, PL_list wait_list)
	Issues a wake up call to the PL ques if any of ques in the wait list is currently active.
PL__LCL_FNC PL_list	pl__test_or (PL_ctl *pl, volatile const PL_list *list)
	Tests whether the current active list of ques contains any member of the specified list.

---

Detailed Description

Priority Lists, inline versions.

Author:

JJRussell - russell@slac.stanford.edu

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

SYNOPSIS

This defines the Priority List routines. A Priority List is a an array of interlocked singly linked lists. A producer places items on one queues managed by the PL facility using one of the insertion routines, PL_insert or PL_jam. The consumer then removes the highest priority non-empty queue using one of the PL__remove routines.

This facility allows multiple producers to insert on any or all of the managed queues. While nothing prohibits multiply consumers to pend on the PL set of managed queues, this would be fairly unusual.

Internally, the interlocking of the queues may or may not be private to each queue. This is a platform implementation decision depending on the cost of interlock mechanism. However, the blocking mechanism is always shared among all the queues. This, in fact, is the distinguishing feature.

---

Function Documentation

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

References _PL_ctl::mactive.

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

References pl__test_or(), _PL_ctl::rw, and RW_getW().

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

References pl__test_or(), _PL_ctl::rw, RW_getW_toc(), and TOC_IS_NOWAIT.

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

References _PL_que::head, _PL_que::id, L__insert(), _PL_ctl::mactive, _PL_que::pl, PL_ADD, _PL_ctl::rw, RW__lock(), RW__unlock(), and RW__wake().

PL__EXP_FNC PL_node * 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.

References _PL_que::head, _PL_que::id, L__jam(), _PL_ctl::mactive, _PL_que::pl, PL_ADD, _PL_ctl::rw, RW__lock(), RW__unlock(), and RW__wake().

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

References _PL_ctl::ques.

Referenced by FORK_que_get().

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

Bare bones, non-interlocked removal routine. This is for internal use only.

Parameters:

	pl	The priority list
	wait_list	Pointer to The list of ques to wait on.
	que_id	Returned with the id of the que the node was removed from

Returns:

A pointer to the deque'd node of the highest priority active que in the wait_list. If the wait_list does not specify any configured ques, NULL is returned.

References _PL_que::head, L__remove(), L_IS_EMPTY, _PL_ctl::mactive, PL_ELIMINATE, PL_FIND, and _PL_ctl::ques.

Referenced by PL__remove().

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

References pl__remove(), _PL_ctl::rw, RW__lock(), and RW__unlock().

Referenced by PL__removeW(), and PL__removeW_toc().

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

References PL__remove(), _PL_ctl::rw, and RW_getW().

PL__EXP_FNC 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.
	toc	The TimeOut control structure. This may be specified as TOC_NOWAIT or TOC_FOREVER.
	que_id	Returned with the id of the que the node was removed from

Returns:

A pointer to the removed node, or NULL on error

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

References PL__remove(), _PL_ctl::rw, RW_getW_toc(), and TOC_IS_NOWAIT.

pl__test_or	(	PL_ctl *	pl,
		volatile const PL_list *	list
	)

Tests whether the current active list of ques contains any member of the specified list.

Parameters:

	pl	The PL control structure
	list	A pointer to the list of the ques to test.

Returns:

The list of active queues. Note that this list is not trimmed by the list. The caller is free to do this if he wishes. If the list does not contain any members of list, 0 is returned.

Warning:

This is an internal routine primarily used as a RW_get callback.

References _PL_ctl::mactive.

Referenced by PL__getW(), and PL__getW_toc().

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 wait list is 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.

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.

References _PL_ctl::mactive, _PL_ctl::rw, RW__lock(), RW__unlock(), and RW__wake().

Referenced by FORK_enable().