QI.c File Reference

Implements the non-inline Que Interlocked (QI) routines. More...

#include <PBS/Q_protos.h>
#include <PBS/RW_protos.h>
#include <PBS/QI.h>

Functions
int	QI_destroy (QI_head *que)
	Destroys the data structures associate with the que.
int	QI_init (QI_head *que, QI_type type)
	Initializes the que to an empty que of the specified type.

---

Detailed Description

Implements the non-inline Que Interlocked (QI) routines.

Author:

JJRussell - russell@slac.stanford.edu

    CVS $Id: QI.c,v 1.6 2011/03/24 23:05:46 apw Exp $

This implements the non-inline versions of the interlocked 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 and have the interlocked mechanism as a built-in feature.

See also the non-inline versions of these routines which may save code space and increase modularity at the expense of performance. The Q routines provide the same functionality without the added feature of being interlocked, and, therefore, thread safe.

---

Function Documentation

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.

References _QI_head::head, Q_destroy(), _QI_head::rw, and RW_destroy().

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.

References _QI_head::head, Q_init(), _QI_head::rw, and RW_init().