QI.ih File Reference

Interlocked doubly linked list, inline versions. More...

#include <PBI/Inline.h>
#include <PBI/Attribute.h>
#include <PBS/Q.h>
#include <PBS/Q.ih>
#include <PBS/RW.h>
#include <PBS/RW.ih>
#include <PBS/QI.h>
#include <PBS/TOC_comdefs.h>

Functions
QI__EXP_PROTO int	QI__disable (QI_head *e) _OK
	Disables the dequeing of nodes from this que.
QI__EXP_PROTO int	QI__enable (QI_head *que) _OK
	Enable the dequeing of nodes from this que.
QI__EXP_PROTO int	QI__enabled (const QI_head *que) _OK
	Returns the state of the disabled flag for this que.
QI__EXP_PROTO QI_node *	QI__insert (QI_head *que, QI_node *node) _OK
	Adds a node to the tail of a previously initialized que.
QI__EXP_PROTO QI_node *	QI__jam (QI_head *que, QI_node *node) _OK
	Adds a node to the head of a previously initialized que.
QI__EXP_PROTO QI_node *	QI__remove (QI_head *que) _OK
	Removes the node from the tail of a previously initialized que. An empty que returns NULL as its node.
QI__EXP_PROTO QI_node *	QI__removeW (QI_head *que) _OK
	Removes the node from the tail of a previously initialized linked list. If the list is empty, the thread of code is blocked until a node becomes available or the timeout expires.
QI__EXP_PROTO QI_node *	QI__removeW_toc (QI_head *que, const TOC *toc) _OK
	Removes the node from the head of a previously initialized que. If the que is empty, the thread of code is blocked until a node becomes available or the timeout condition is satisfied.
QI__EXP_FNC void	QI__append (QI_head *dst, QI_head *src)
	Appends the src que members to the dst que.
QI__EXP_FNC void	QI__prepend (QI_head *dst, QI_head *src)
	Prepends the src que members to the que list.

---

Detailed Description

Interlocked doubly linked list, inline versions.

Author:

JJRussell - russell@slac.stanford.edu

    CVS $Id: QI.ih,v 1.4 2011/03/24 23:05:43 apw Exp $

SYNOPSIS

This defines the inline interlocked versions of the Que routines. These allow the user to build interlocked doubly linked lists. These routines parallel some of the functionality of the VxWorks llxxxx routines, but are portable to both VxWorks and host platforms, in addition to being thread-safe.

See also the non-inlined versions of these routines which offer possible savings in code space and increased modularity at the expense of some performance. The Q routines provide the same functionality without the overhead of being interlocked.

Note:

Conspicious by its absence is an interlocked unlink. This is deliberate. There is no safe way to provide a routine to unlink a node in an interlocked fashion. If the node was located without any interlocks on the que, there is no guarantee that by the time the mythical QI__unlink routine gets called and interlocks the que, that the node is still on the que.

---

Function Documentation

void QI__append	(	QI_head *	dst,
		QI_head *	src
	)

Appends the src que members to the dst que.

Parameters:

	dst	A previously initialized que acting as the destination
	src	A previously initialized que acting as the source

Appends the source que to the destination que. After this operation the destination que will have consist of its original members followed by the members on the source que. The source que will be empty.

References _QI_head::head, Q__append(), _QI_head::rw, RW__lock2(), and RW__unlock2().

QI__EXP_FNC int QI__disable

(

QI_head *

que

)

Disables the dequeing of nodes from this que.

Parameters:

que

A previously initialized que

Return values:

	0	Que was previously disabled
	!=0	Que was previously enabled

Any items on the que and any items placed on the que after the disable call will not be dequed by any of the QI__removeXXX routines. Delivery of these items may resume after a call to QI__enable().

Warning:

Be cautious with this routine. It is very easy to deadlock the system by having the same task disable the que and place items on the que. Sooner or later in this situation the source of items to be placed on the que will become exhausted. If the user is getting these items from a resource that blocks when it the pool of items becomes exhausted, no call to issue a QI__enable can be made, i.e. deadlock.

To avoid this situation, either separate the task controlling the queue via QI__disable's and QI__enables' from the task allocating new items for the que or, if in the same task, cease to allocate new items when the QI que has been disabled.

References _QI_head::rw, and RW__disable().

QI__EXP_FNC int QI__enable

(

QI_head *

que

)

Enable the dequeing of nodes from this que.

Parameters:

que

A previously initialized que

Return values:

	0	Que was previously disabled
	!=0	Que was previously enabled

After issuing this call the QI__remove routines will deliver items once again. If any QI__remove call is currently waiting on a non-empty que, a wakeup call is issued, permitting nodes to be dequed.

References _QI_head::rw, and RW__enable().

QI__EXP_FNC int QI__enabled

(

const QI_head *

que

)

Returns the state of the disabled flag for this que.

Parameters:

que

A previously initialized que

Return values:

	0	Que is currently disabled
	!=0	Que is currently enabled

References _QI_head::rw, and RW__enabled().

QI__EXP_FNC QI_node * QI__insert	(	QI_head *	que,
		QI_node *	node
	)

Adds a node to the tail of a previously initialized que.

Parameters:

	que	A previously initialized que.
	node	The node to add at the tail of the list.

Returns:

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

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

References _QI_head::head, Q__insert(), _QI_head::rw, RW__lock(), RW__unlock(), and RW__wake().

QI__EXP_FNC QI_node * QI__jam	(	QI_head *	que,
		QI_node *	node
	)

Adds a node to the head of a previously initialized que.

Parameters:

	que	A previously initialized que.
	node	The node to add.

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 == que, the empty)

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

References _QI_head::head, Q__jam(), _QI_head::rw, RW__lock(), RW__unlock(), and RW__wake().

void QI__prepend	(	QI_head *	dst,
		QI_head *	src
	)

Prepends the src que members to the que list.

Parameters:

	dst	A previously initialized que acting as the destination
	src	A previously initialized que acting as the source

Prepends the source que to the destination que. After this operation the destination que will have consist of its original members preceded by the members on the source que. The source que will be empty.

References _QI_head::head, Q__prepend(), _QI_head::rw, RW__lock2(), and RW__unlock2().

QI__EXP_FNC QI_node * QI__remove

(

QI_head *

que

)

Removes the node from the tail of a previously initialized que. An empty que returns NULL as its node.

Parameters:

que

A previously initialized que.

Returns:

A pointer to the removed node of NULL if the que is empty. Removes the node at the head of the que. If the que is empty, NULL is returned.

References _QI_head::head, Q__remove(), _QI_head::rw, RW__enabled(), RW__lock(), and RW__unlock().

Referenced by QI__removeW(), and QI__removeW_toc().

QI__EXP_FNC QI_node * QI__removeW

(

QI_head *

que

)

Removes the node from the tail of a previously initialized linked list. If the list is empty, the thread of code is blocked until a node becomes available or the timeout expires.

Parameters:

que

A previously initialized que

Returns:

A pointer to the removed node or NULL on error.

References Q__remove(), QI__remove(), _QI_head::rw, and RW_getW().

QI__EXP_FNC QI_node * QI__removeW_toc	(	QI_head *	que,
		const TOC *	toc
	)

Removes the node from the head of a previously initialized que. If the que is empty, the thread of code is blocked until a node becomes available or the timeout condition is satisfied.

Parameters:

	que	A previously initialized que.
	toc	The timeout control structure. This may be one of the two special values TOC_NOWAIT or TOC_FOREVER.

Returns:

A pointer to the removed node. of NULL if the que is empty.

Removes the node from the head of a previously initialized que. If the que is empty, the thread of code is blocked until a node becomes available or the timeout value is reached. See also QI_removeW and QI_remove.

References Q_remove(), QI__remove(), _QI_head::rw, RW_getW_toc(), and TOC_IS_NOWAIT.