<< Previous | Next >>

preorder

void * preorder( Pool_t *p, void *e, void *where, word options );

Description

Atomically remove allocated element "e" and re-insert it before or after element "where." "Atomically" means that the POOL_IPSET level is used to lock out other CPU contexts from altering the pool while this operation is in progress.

The pool MUST be set to being a linked pool by using:

   

pool_link(p, <non-zero>)

Otherwise the results are undefined.

Parameters

p

Pool handle structure, as previously passed to pool_init().

e

Address of element to move, obtained by e.g., plast(). This must be an allocated element in the given pool; otherwise, the results are undefined. If null, then the last element is implied (i.e., whatever plast() would return). If there are no elements at all, or this parameter does not point to a valid allocated element, then the results are undefined (and probably catastrophic).

where

The reference element. The element "e" will be inserted before or after this element, depending on the options parameter. If e==where, then there is no action. If this parameter is null, then the reference element is assumed to be the first element (i.e., whatever pfirst() would return). If there are no elements at all, or this parameter does not point to a valid allocated element, then the results are undefined (and probably catastrophic).

options

Option flags. Currently, the only options are:

POOL_INSERT_BEFORE
POOL_INSERT_AFTER

which specifies whether "e" is to be inserted before or after "where."

Return Value

Returns the parameter value "e" unless "e" was null, in which case the value of plast(), when called at function entry, would be returned.

IMPORTANT: If null is returned, that means that some other task (context, or ISR) modified the linked list while this operation was in progress. In this case, the application should call this function again with the same parameters, since this operation will NOT have completed. This would be a rare occurrence; however, multitasking applications should handle this case correctly.

Examples

   

void * r;
void * s;

s = pnext(p, pfirst(p);       // s is second element
r = plast(p);                 // r is last element
preorder(p, s, r, POOL_INSERT_AFTER);

// If s != r, then s will become the new last element. You can use null
// parameters to perform the common case of moving the last element 
// to the head of the list:
preorder(p, NULL, NULL, POOL_INSERT_BEFORE);

// which is identical to:.
preorder(p, plast(p), pfirst(p), POOL_INSERT_BEFORE);

Library

POOL.LIB

See Also

pool_init, pool_link, plast, pfirst, pnext, pprev, pmovebetween