LI.ih File Reference

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

#include <PBI/Inline.h>
#include <PBI/Attribute.h>
#include <IPBS/L.h>
#include <IPBS/L.ih>
#include <IPBS/RW.h>
#include <IPBS/RW.ih>
#include <IPBS/LI.h>
#include <IPBS/TOC_comdefs.h>

Defines
#define	LI__EXP_PROTO   INLINE_USR_EXP_PROTO
	Export Prototype spec.
#define	LI__LCL_PROTO   INLINE_USR_LCL_PROTO
	Internal Prototype spec.
#define	LI__EXP_FNC   INLINE_USR_EXP_FNC
	Export Function declaration.
#define	LI__LCL_FNC   INLINE_USR_LCL_FNC
	Internal Function declaration.
#define	_OK   ATTR_UNUSED_OK
	Abbreviation for ATTR_UNUSED_OK, undefined in this file.
Functions
LI__EXP_PROTO void	LI__append (LI_head *dst, LI_head *src) _OK
	Appends the src list members to the dst list.
LI__EXP_PROTO int	LI__disable (LI_head *list) _OK
	Disables the dequeing of nodes from this list.
LI__EXP_PROTO int	LI__enable (LI_head *list) _OK
	Enable the dequeing of nodes from this list.
LI__EXP_PROTO int	LI__enabled (const LI_head *list) _OK
	Returns the state of the enabled flag for this list.
LI__EXP_PROTO LI_node *	LI__insert (LI_head *list, LI_node *node) _OK
	Adds a node to the tail of a previously initialized list.
LI__EXP_PROTO LI_node *	LI__jam (LI_head *list, LI_node *node) _OK
	Adds a node to the head of a previously initialized list.
LI__EXP_PROTO void	LI__prepend (LI_head *dst, LI_head *src) _OK
	Prepends the src list members to the dst list.
LI__EXP_PROTO LI_node *	LI__remove (LI_head *list) _OK
	Removes the node from the tail of a previously initialized list. An empty list returns NULL as its node.
LI__EXP_PROTO LI_node *	LI__removeW (LI_head *list) _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.
LI__EXP_PROTO LI_node *	LI__removeW_toc (LI_head *list, const TOC *toc) _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.

---

Detailed Description

Interlocked singly linked list, inline versions.

Author:

JJRussell - russell@slac.stanford.edu

    CVS $Id: LI.ih,v 1.2 2011/03/25 21:15:00 saxton Exp $

SYNOPSIS

This defines the inline interlocked versions of the singly linked list routines. These routines are 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 L routines provide the same functionality without the overhead of being interlocked.

---

Function Documentation

LI__EXP_FNC void LI__append	(	LI_head *	dst,
		LI_head *	src
	)

Appends the src list members to the dst list.

Parameters:

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

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

References _LI_head::head, L__append(), _LI_head::rw, RW__lock2(), and RW__unlock2().

LI__EXP_FNC int LI__disable

(

LI_head *

list

)

Disables the dequeing of nodes from this list.

Parameters:

list

A previously initialized list.

Return values:

	0	= List was previously disabled
	!=0	= List 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 LI__removeXXX routines. Delivery of these items may resume after a call to LI__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 LI__enable can be made, i.e. deadlock.

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

References _LI_head::rw, and RW__disable().

Referenced by FORK_disable().

LI__EXP_FNC int LI__enable

(

LI_head *

list

)

Enable the dequeing of nodes from this list.

Parameters:

list

A previously initialized list.

Return values:

	0	= List was previously disabled
	!=0	= List was previously enabled

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

References _LI_head::rw, and RW__enable().

Referenced by FORK_enable().

LI__EXP_FNC int LI__enabled

(

const LI_head *

list

)

Returns the state of the enabled flag for this list.

Parameters:

list

A previously initialized list.

Return values:

	0	List is currently disabled
	!=0	List 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.

References _LI_head::rw, and RW__enabled().

Referenced by FORK_enabled(), and FORK_qenabled().

LI__EXP_FNC LI_node * LI__insert	(	LI_head *	list,
		LI_node *	node
	)

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

Parameters:

	list	A previously initialized list.
	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 list.
If return_value == list, the empty)

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

References _LI_head::head, L__insert(), _LI_head::rw, RW__lock(), RW__unlock(), and RW__wake().

LI__EXP_FNC LI_node * LI__jam	(	LI_head *	list,
		LI_node *	node
	)

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

Parameters:

	list	A previously initialized list.
	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 list.
If return_value == list, the empty)

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

References _LI_head::head, L__jam(), _LI_head::rw, RW__lock(), RW__unlock(), and RW__wake().

LI__EXP_FNC void LI__prepend	(	LI_head *	dst,
		LI_head *	src
	)

Prepends the src list members to the dst list.

Parameters:

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

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

References _LI_head::head, L_prepend(), _LI_head::rw, RW__lock2(), and RW__unlock2().

LI__EXP_FNC LI_node * LI__remove

(

LI_head *

list

)

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

Parameters:

list

A previously initialized list.

Returns:

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

References _LI_head::head, L__remove(), _LI_head::rw, RW__enabled(), RW__lock(), and RW__unlock().

Referenced by FORK_qsys(), LI__removeW(), and LI__removeW_toc().

LI__EXP_FNC LI_node * LI__removeW

(

LI_head *

list

)

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.

Parameters:

list

A previously initialized list

Returns:

A pointer to the removed node or NULL on error or timeout.

References L__remove(), LI__remove(), _LI_head::rw, and RW_getW().

Referenced by FORK_qsysW().

LI__EXP_FNC LI_node * LI__removeW_toc	(	LI_head *	list,
		const TOC *	toc
	)

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:

	list	A previously initialized list
	toc	The timeout control structure. Maybe specified as either TOC_NOWAIT or TOC_FOREVER.

Returns:

A pointer to the removed node or NULL on error or timeout.

References L_remove(), LI__remove(), _LI_head::rw, RW_getW_toc(), and TOC_IS_NOWAIT.

Referenced by FORK_qsysW_toc().