Main Page | Data Structures | File List | Globals | Related Pages

variable_queue.h File Reference

Generalized queue module for data collection. More...

Go to the source code of this file.

Defines

#define Q_NEW_HEAD(Q_HEAD_TYPE, Q_ELEM_TYPE)   ;
 Generates a new structure of type Q_HEAD_TYPE representing the head of a queue of elements of type Q_ELEM_TYPE.

#define Q_NEW_LINK(Q_ELEM_TYPE)   ;
 Instantiates a link within a structure, allowing that structure to be collected into a queue created with Q_NEW_HEAD.

#define Q_INIT_HEAD(Q_HEAD)   ;
 Initializes the head of a queue so that the queue head can be used properly.

#define Q_INIT_ELEM(Q_ELEM, LINK_NAME)   ;
 Initializes the link named LINK_NAME in an instance of the structure Q_ELEM.

#define Q_INSERT_FRONT(Q_HEAD, Q_ELEM, LINK_NAME)   ;
 Inserts the queue element pointed to by Q_ELEM at the front of the queue headed by the structure Q_HEAD.

#define Q_INSERT_TAIL(Q_HEAD, Q_ELEM, LINK_NAME)   ;
 Inserts the queue element pointed to by Q_ELEM at the end of the queue headed by the structure pointed to by Q_HEAD.

#define Q_GET_FRONT(Q_HEAD)   ;
 Returns a pointer to the first element in the queue, or NULL (memory address 0) if the queue is empty.

#define Q_GET_TAIL(Q_HEAD)   ;
 Returns a pointer to the last element in the queue, or NULL (memory address 0) if the queue is empty.

#define Q_GET_NEXT(Q_ELEM, LINK_NAME)   ;
 Returns a pointer to the next element in the queue, as linked to by the link specified with LINK_NAME.

#define Q_GET_PREV(Q_ELEM, LINK_NAME)   ;
 Returns a pointer to the previous element in the queue, as linked to by the link specified with LINK_NAME.

#define Q_INSERT_AFTER(Q_HEAD, Q_INQ, Q_TOINSERT, LINK_NAME)   ;
 Inserts the queue element Q_TOINSERT after the element Q_INQ in the queue.

#define Q_INSERT_BEFORE(Q_HEAD, Q_INQ, Q_TOINSERT, LINK_NAME)   ;
 Inserts the queue element Q_TOINSERT before the element Q_INQ in the queue.

#define Q_REMOVE(Q_HEAD, Q_ELEM, LINK_NAME)   ;
 Detaches the element Q_ELEM from the queue organized by LINK_NAME, and returns a pointer to the element.

#define Q_FOREACH(CURRENT_ELEM, Q_HEAD, LINK_NAME)   ;
 Constructs an iterator block (like a for block) that operates on each element in Q_HEAD, in order.


Detailed Description

Generalized queue module for data collection.

Author:
Your name here

Define Documentation

#define Q_FOREACH CURRENT_ELEM,
Q_HEAD,
LINK_NAME   )     ;
 

Constructs an iterator block (like a for block) that operates on each element in Q_HEAD, in order.

Q_FOREACH constructs the head of a block of code that will iterate through each element in the queue headed by Q_HEAD. Each time through the loop, the variable named by CURRENT_ELEM will be set to point to a subsequent element in the queue.

Usage:
Q_FOREACH(CURRENT_ELEM,Q_HEAD,LINK_NAME)
{
... operate on the variable CURRENT_ELEM ...
}

If LINK_NAME is not used to organize the queue headed by Q_HEAD, then the behavior of this macro is undefined.

Parameters:
CURRENT_ELEM name of the variable to use for iteration. On each loop through the Q_FOREACH block, CURRENT_ELEM will point to the current element in the queue. CURRENT_ELEM should be an already- defined variable name, and its type should be a pointer to the type of data organized by Q_HEAD
Q_HEAD Pointer to the head of the queue to iterate through
LINK_NAME The name of the link used to organize the queue headed by Q_HEAD.

#define Q_GET_FRONT Q_HEAD   )     ;
 

Returns a pointer to the first element in the queue, or NULL (memory address 0) if the queue is empty.

Parameters:
Q_HEAD Pointer to the head of the queue
Returns:
Pointer to the first element in the queue, or NULL if the queue is empty

#define Q_GET_NEXT Q_ELEM,
LINK_NAME   )     ;
 

Returns a pointer to the next element in the queue, as linked to by the link specified with LINK_NAME.

If Q_ELEM is not in a queue or is the last element in the queue, Q_GET_NEXT should return NULL.

Parameters:
Q_ELEM Pointer to the queue element before the desired element
LINK_NAME Name of the link organizing the queue
Returns:
The element after Q_ELEM, or NULL if there is no next element

#define Q_GET_PREV Q_ELEM,
LINK_NAME   )     ;
 

Returns a pointer to the previous element in the queue, as linked to by the link specified with LINK_NAME.

If Q_ELEM is not in a queue or is the first element in the queue, Q_GET_NEXT should return NULL.

Parameters:
Q_ELEM Pointer to the queue element after the desired element
LINK_NAME Name of the link organizing the queue
Returns:
The element before Q_ELEM, or NULL if there is no next element

#define Q_GET_TAIL Q_HEAD   )     ;
 

Returns a pointer to the last element in the queue, or NULL (memory address 0) if the queue is empty.

Parameters:
Q_HEAD Pointer to the head of the queue
Returns:
Pointer to the last element in the queue, or NULL if the queue is empty

#define Q_INIT_ELEM Q_ELEM,
LINK_NAME   )     ;
 

Initializes the link named LINK_NAME in an instance of the structure Q_ELEM.

Once initialized, the link can be used to organized elements in a queue.

Parameters:
Q_ELEM Pointer to the structure instance containing the link
LINK_NAME The name of the link to initialize

#define Q_INIT_HEAD Q_HEAD   )     ;
 

Initializes the head of a queue so that the queue head can be used properly.

Parameters:
Q_HEAD Pointer to queue head to initialize

#define Q_INSERT_AFTER Q_HEAD,
Q_INQ,
Q_TOINSERT,
LINK_NAME   )     ;
 

Inserts the queue element Q_TOINSERT after the element Q_INQ in the queue.

Inserts an element into a queue after a given element. If the given element is the last element, Q_HEAD should be updated appropriately (so that Q_TOINSERT becomes the tail element)

Parameters:
Q_HEAD head of the queue into which Q_TOINSERT will be inserted
Q_INQ Element already in the queue
Q_TOINSERT Element to insert into queue
LINK_NAME Name of link field used to organize the queue

#define Q_INSERT_BEFORE Q_HEAD,
Q_INQ,
Q_TOINSERT,
LINK_NAME   )     ;
 

Inserts the queue element Q_TOINSERT before the element Q_INQ in the queue.

Inserts an element into a queue before a given element. If the given element is the first element, Q_HEAD should be updated appropriately (so that Q_TOINSERT becomes the front element)

Parameters:
Q_HEAD head of the queue into which Q_TOINSERT will be inserted
Q_INQ Element already in the queue
Q_TOINSERT Element to insert into queue
LINK_NAME Name of link field used to organize the queue

#define Q_INSERT_FRONT Q_HEAD,
Q_ELEM,
LINK_NAME   )     ;
 

Inserts the queue element pointed to by Q_ELEM at the front of the queue headed by the structure Q_HEAD.

The link identified by LINK_NAME will be used to organize the element and record its location in the queue.

Parameters:
Q_HEAD Pointer to the head of the queue into which Q_ELEM will be inserted
Q_ELEM Pointer to the element to insert into the queue
LINK_NAME Name of the link used to organize the queue
Returns:
Void (you may change this if your implementation calls for a return value)

#define Q_INSERT_TAIL Q_HEAD,
Q_ELEM,
LINK_NAME   )     ;
 

Inserts the queue element pointed to by Q_ELEM at the end of the queue headed by the structure pointed to by Q_HEAD.

The link identified by LINK_NAME will be used to organize the element and record its location in the queue.

Parameters:
Q_HEAD Pointer to the head of the queue into which Q_ELEM will be inserted
Q_ELEM Pointer to the element to insert into the queue
LINK_NAME Name of the link used to organize the queue
Returns:
Void (you may change this if your implementation calls for a return value)

#define Q_NEW_HEAD Q_HEAD_TYPE,
Q_ELEM_TYPE   )     ;
 

Generates a new structure of type Q_HEAD_TYPE representing the head of a queue of elements of type Q_ELEM_TYPE.

Usage: Q_NEW_HEAD(Q_HEAD_TYPE, Q_ELEM_TYPE); //create the type
Q_HEAD_TYPE headName; //instantiate a head of the given type

Parameters:
Q_HEAD_TYPE the type you wish the newly-generated structure to have.
Q_ELEM_TYPE the type of elements stored in the queue. Q_ELEM_TYPE must be a structure.

#define Q_NEW_LINK Q_ELEM_TYPE   )     ;
 

Instantiates a link within a structure, allowing that structure to be collected into a queue created with Q_NEW_HEAD.

Usage:
typedef struct Q_ELEM_TYPE {
Q_NEW_LINK(Q_ELEM_TYPE) LINK_NAME; //instantiate the link
} Q_ELEM_TYPE;

A structure can have more than one link defined within it, as long as they have different names. This allows the structure to be placed in more than one queue simultanteously.

Parameters:
Q_ELEM_TYPE the type of the structure containing the link

#define Q_REMOVE Q_HEAD,
Q_ELEM,
LINK_NAME   )     ;
 

Detaches the element Q_ELEM from the queue organized by LINK_NAME, and returns a pointer to the element.

If Q_HEAD does not use the link named LINK_NAME to organize its elements or if Q_ELEM is not a member of Q_HEAD's queue, the behavior of this macro is undefined.

Parameters:
Q_HEAD Pointer to the head of the queue containing Q_ELEM. If Q_REMOVE removes the first, last, or only element in the queue, Q_HEAD should be updated appropriately.
Q_ELEM Pointer to the element to remove from the queue headed by Q_HEAD.
LINK_NAME The name of the link used to organize Q_HEAD's queue
Returns:
Void (if you would like to return a value, you may change this specification)


Generated on Fri Apr 9 21:59:16 2004 for 15-410 Project 3 by doxygen 1.3.2