r6.1.0:lfds610_stack_query

Source Files

/liblfds610/src/lfds610_stack/lfds610_stack_query.c
/liblfds610/inc/liblfds610.h

Enums

enum lfds610_stack_query_type
{
  LFDS610_STACK_QUERY_ELEMENT_COUNT,
  LFDS610_STACK_QUERY_VALIDATE
};

Prototype

void lfds610_stack_query( struct lfds610_stack_state *ss, enum lfds610_stack_query_type query_type, void *query_input, void *query_output );

Parameters

struct lfds610_stack_state *ss

A stack state as allocated by lfds610_stack_new.

enum lfds610_stack_query_type query_type

Indicates which query to perform.

void *query_input

A pointer to data, or data cast to a void pointer, which is input data required by requested query. Only some queries require input data. If no input data is required, set query_input to NULL.

void *query_output

The address of a variable into which the requested information is placed. The type of variable varies on the type of query; see Notes.

Return Value

No return value. The variable pointed to by query_result (the type of which will vary depending on the query, see Notes) will be set; this is the mechanism by which information is passed back to the caller. Currently, no query can fail, so there is no notion of an error value.

Notes

The following query is currently supported;

• LFDS610_STACK_QUERY_ELEMENT_COUNT
  • query_input is NULL.
  • query_output must point to an lfds610_atom_t and this variable is set to hold the total count of elements belonging to the stack's freelist (not the free count, the total count). It is an approximate value, since the count cannot be atomically updated as elements are added to the freelist. However, the count is incremented immediately after an element is added, so the value will in general be correct or very nearly correct and can at most be inaccurate by the number of threads concurrently adding new elements to the stack (which occurs by calling lfds610_stack_guaranteed_push).

• LFDS610_STACK_QUERY_VALIDITY
  • query_input may be NULL or may point to a struct validation_info. This structure contains the minimum and maximum expected number of elements currently held in the stack (set minimum and maximum to the same value if the exact value is known). The expected minimum and maximum number of elements in the stack's freelist can be derived from the numbers for the queue, since the stack begins empty and the initial number of elements in the freelist is known. If NULL, no check for missing or additional elements is performed.
  • query_output must point to an an array of two enum data_structure_validity. The validation check detects loops, missing elements and additional elements in both the stack and the stack's freelist and sets the values of stack_output accordingly. The first element in the array is used for the stack's validity state, the second for the stack's freelist's validity state. The main purpose of this query is to provide a validation function to the test program.

See Also

• lfds610_stack