Difference between pages "r6:Function:slist new next" and "r6:Function:slist query"

From liblfds.org
(Difference between pages)
Jump to navigation Jump to search
m (1 revision imported)
 
m (1 revision imported)
 
Line 1: Line 1:
==Source Files==
==Source Files==
  /src/slist/slist_new.c
  /src/slist/slist_query.c
  /inc/liblfds.h
  /inc/liblfds.h
==Enums==
enum slist_query_type
{
  SLIST_QUERY_VALIDATE
};


==Prototype==
==Prototype==
  struct slist_element *slist_new_next( struct slist_element *se, void *user_data );
  void slist_query( struct slist_state *ss, enum slist_query_type query_type, void *query_input, void *query_output );


==Parameters==
==Parameters==
''struct slist_element *se''
''struct slist_state *ss''
: An slist element as allocated by ''[[r6:Function:slist_new_head|slist_new_head]]'' or ''slist_new_next''.
: An slist state as allocated by ''[[r6:Function:slist_new|slist_new]]''.
 
''enum slist_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 *user_data''
''void *query_output''
: A void pointer of user data which will be placed into the list immediately after ''slist_element''.
: 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==
==Return Value==
Returns a pointer to the new slist elementIf element creation failed, which can only happen because of memory allocation failure, the return value is NULL.
No return value.  The variable pointed to by ''query_output'' (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 callerCurrently, no query can fail, so there is no notion of an error value.


==Notes==
==Notes==
This function creates a new slist element holding ''user_data'' and links it into the slist immediately after element ''se''.
The following query is currently supported;
 
* SLIST_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 ringbuffer (set minimum and maximum to the same value if the exact value is known).  The expected minimum and maximum number of elements in the queue, the queue's freelist and the ringbuffer's freelist can all be derived from the original numbers, since the queue 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 three ''enum data_structure_validity''.  The validation check detects loops, missing elements and additional elements in the queue, the queue's freelist and the ringbuffer's freelist and sets the values of query_output accordingly.  The first element in the array is used for the queue's validity state, the second for the queue's freelist's validity state, the third for the ringbuffer's freelist's validity state  The main purpose of this query is to provide a validation function to the test program.


==See Also==
==See Also==
* [[r6:API:SList|SList]]
* [[r6:API:SList|SList]]
* [[r6:Function:slist_new_head|slist_new_head]]

Latest revision as of 14:07, 4 January 2015

Source Files

/src/slist/slist_query.c
/inc/liblfds.h

Enums

enum slist_query_type
{
  SLIST_QUERY_VALIDATE
};

Prototype

void slist_query( struct slist_state *ss, enum slist_query_type query_type, void *query_input, void *query_output );

Parameters

struct slist_state *ss

An slist state as allocated by slist_new.

enum slist_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_output (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;

  • SLIST_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 ringbuffer (set minimum and maximum to the same value if the exact value is known). The expected minimum and maximum number of elements in the queue, the queue's freelist and the ringbuffer's freelist can all be derived from the original numbers, since the queue 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 three enum data_structure_validity. The validation check detects loops, missing elements and additional elements in the queue, the queue's freelist and the ringbuffer's freelist and sets the values of query_output accordingly. The first element in the array is used for the queue's validity state, the second for the queue's freelist's validity state, the third for the ringbuffer's freelist's validity state The main purpose of this query is to provide a validation function to the test program.

See Also