---

GLAST/LAT > DAQ and FSW > FSW > Doxygen Index > IPBS / V0-0-1

Constituent: pbs     Tag: i845e

---

         

---

LI_protos.h File Reference

Interlocked singly linked list, function prototypes, callable version. More...

#include "IPBS/LI_comdefs.h"
#include "IPBS/TOC_comdefs.h"

Include dependency graph for LI_protos.h:

This graph shows which files directly or indirectly include this file:

Functions
void	LI_append (LI_head *dst, LI_head *src)
	Appends the src list members to the dst list.
int	LI_disable (LI_head *list)
	Disables the dequeing of nodes from this list.
int	LI_enable (LI_head *list)
	Enable the dequeing of nodes from this list.
int	LI_enabled (const LI_head *list)
	Returns the state of the enabled flag for this list.
int	LI_init (LI_head *list, LI_type type)
	Initializes the list head of a singly linked list to an empty list.
int	LI_destroy (LI_head *list)
	Destroys the data structures associate with a list.
LI_node *	LI_insert (LI_head *list, LI_node *node)
	Adds a node to the tail of a previously initialized list.
LI_node *	LI_jam (LI_head *list, LI_node *node)
	Adds a node to the head of a previously initialized list.
void	LI_prepend (LI_head *dst, LI_head *src)
	Prepends the src list members to the dst list.
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.
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.
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.

---

Detailed Description

Interlocked singly linked list, function prototypes, callable version.

Author:

JJRussell - russell@slac.stanford.edu

   CVS $Id: LI_protos.h,v 1.1.1.1 2006/02/10 21:45:35 saxton Exp $

Provides ability to manipulate a singly linked list in an interlocked fashion, i.e. thread safe. The actual interlock mechanism is platform dependent.

See also the inline versions of these routines which may offer increased performance at the expense of code space and modularity. The L routines provide the same functionality without the overhead/features associated with being interlocked.

---

Function Documentation

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.

void LI_destroy (  LI_head *  list  )

Destroys the data structures associate with a list. Parameters: list  Pointer to the list to destroy. This routine releases the resources acquired when the list was initialized by LI_init.

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.

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.

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

void LI_init (  LI_head *  list, LI_type  type )

Initializes the list head of a singly linked list to an empty list. Parameters: list  Pointer to the list to initialize. type  The type of interlocking linked list The list is initialized to an empty list. This must be done before performing any other operations on the list. The type determines how the list behaves when one attempts to remove a node from an empty list.

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.

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.

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.

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.

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.

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.

---