GLAST/LAT > DAQ and FSW > FSW > Doxygen Index > PBS / V2-10-15

Constituent: pbs     Tag: rad750

Interface   Data Structures   File List   Data Fields   Globals  
g » glast » flight » SVC » source » PBS » V2-10-15 » PBS

QI_protos.h File Reference

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

#include "PBS/QI_comdefs.h"
#include "PBS/TOC_comdefs.h"

Include dependency graph for QI_protos.h:

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


Functions

void QI_append (QI_head *dst, QI_head *src)
 Appends the src que members to the dst que.
int QI_destroy (QI_head *que)
 Destroys the data structures associate with the que.
int QI_disable (QI_head *que)
 Disables the dequeing of nodes from this que.
int QI_enable (QI_head *que)
 Enable the dequeing of nodes from this que.
int QI_enabled (const QI_head *que)
 Returns the state of the enabled flag for this que.
int QI_init (QI_head *que, QI_type type)
 Initializes the que to an empty que of the specified type.
QI_node * QI_insert (QI_head *que, QI_node *node)
 Adds a node to the tail of a previously initialized que.
QI_node * QI_jam (QI_head *que, QI_node *node)
 Adds a node to the head of a previously initialized que.
void QI_prepend (QI_head *dst, QI_head *src)
 Prepends the src que members to the que list.
QI_node * QI_remove (QI_head *que)
 Removes the node from the tail of a previously que.An empty que returns NULL as its node.
QI_node * QI_removeW (QI_head *que)
 Removes the node from the head of a previously initialized que. If the que is empty, the thread of code is blocked indefinitely until a node becomes available.
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.

Detailed Description

Interlocked doubly linked list, function prototypes, callable version.

Author:
JJRussell - russell@slac.stanford.edu
   CVS $Id: QI_protos.h,v 1.3 2004/10/20 14:36:51 russell Exp $

SYNOPSIS
Provides ability to manipulate a doubly 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 Q routines provide the same functionality without the overhead/features associated with being interlocked.

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.

int QI_destroy (  QI_head *  que  ) 
 

Destroys the data structures associate with the que.

Parameters:
que Pointer to the que to destroy.
This routine frees any resources the que gathered when it was initialized. The actual resources released depends on both the platform and whether blocking and timeouts were requested.

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.

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.

int * QI_enabled (  const QI_head *  que  ) 
 

Returns the state of the enabled flag for this que.

Parameters:
que A previously initialized que.
Return values:
0 Que is currently disabled
!=0 Que 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.

int QI_init (  QI_head *  que,
QI_type  type
) 
 

Initializes the que to an empty que of the specified type.

Parameters:
que Pointer to the que to initialize.
type The type of interlocked que.
Return values:
0,Success 
ENOMEM,Insufficient memory
ENOTSUP,Type not supported.
The que is initialized to an empty que. This must be done before performing any other operations on the que. The type determines whether the que is capable of blocking when attempting to remove a node from an empty que. See the enum QI_opt_blocking for the available blocking types. For ques that block, one can also specify that timeouts are available. Since timeout support may demand additional resources, the user is asked to state upfront whether timeouts are needed.

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.

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 que.
Returns:
Pointer to the old backward link. This can be used to test whether this was the first node 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 QI_insert routine, then the que behaves as a FIFO.

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 node on the queue.
If return_value == que, then the que was initially 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.

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.

QI_node * QI_remove (  QI_head *  que  ) 
 

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

Parameters:
que A previously initialized que.
Returns:
A pointer to the removed node or NULL if the que is empty.
Removes the node at the head of the que. If the que is empty, NULL is returned.

QI_node * QI_removeW (  QI_head *  que  ) 
 

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

Parameters:
que A previously initialized que.
Returns:
A pointer to the removed node or NULL if the que is empty.
Removes the node from the tail of a previously initialized que. If the que is empty, the thread of code is blocked until a node becomes available. See QI_remove and QI_removeW_toc for nowait and timed out versions of the removal routines.

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.

Generated on Thu Mar 22 05:51:41 2007 by  doxygen 1.4.4