QI_protos.h File Reference
Interlocked doubly linked list, function prototypes, callable version.
More...
#include <PBS/QI_comdefs.h>
#include <PBS/TOC_comdefs.h>
|
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.4 2011/03/24 23:05:43 apw 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
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.
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.
References _QI_head::head, Q_destroy(), _QI_head::rw, and RW_destroy().
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.
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.
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.
References _QI_head::head, Q_init(), _QI_head::rw, and RW_init().
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.
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.
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.
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.
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.
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.