Difference between pages "r6:Function:stack push" and "r6:Function:stack 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/stack/stack_push_pop.c
  /src/stack/stack_query.c
  /inc/liblfds.h
  /inc/liblfds.h
==Enums==
enum stack_query_type
{
  STACK_QUERY_ELEMENT_COUNT
};


==Prototype==
==Prototype==
  int stack_push( struct stack_state *ss, void *user_data );
  void stack_query( struct stack_state *ss, enum stack_query_type query_type, void *query_input, void *query_output );


==Parameters==
==Parameters==
Line 10: Line 16:
: A stack state as allocated by ''[[r6:Function:stack_new|stack_new]]''.
: A stack state as allocated by ''[[r6:Function:stack_new|stack_new]]''.


''void *user_data''
''enum stack_query_type query_type''
: A void pointer of user data which will be pushed onto the stack.
: 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==
==Return Value==
The return value is 1 upon successful push, 0 upon failureFailure occurs only when the stack has exhausted its freelist of elements.  In this case, the user can call ''[[r6:Function:stack_guaranteed_push|stack_guaranteed_push]]'', which will allocate a new element and push using thatRemember however that the stack can never shrink, so any such call will permanently increase the size of the stack by one element.
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 callerCurrently, no query can fail, so there is no notion of an error value.


==Notes==
==Notes==
No notes.
The following query is currently supported;
 
* STACK_QUERY_ELEMENT_COUNT
** ''query_input'' is NULL.
** ''query_output'' must point to an ''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 ''[[r6:Function:stack_guaranteed_push|stack_guaranteed_push]]'').


==See Also==
==See Also==
* [[r6:API:Stack|Stack]]
* [[r6:API:Stack|Stack]]
* [[r6:Function:stack_pop|stack_pop]]

Latest revision as of 14:07, 4 January 2015

Source Files

/src/stack/stack_query.c
/inc/liblfds.h

Enums

enum stack_query_type
{
  STACK_QUERY_ELEMENT_COUNT
};

Prototype

void stack_query( struct stack_state *ss, enum stack_query_type query_type, void *query_input, void *query_output );

Parameters

struct stack_state *ss

A stack state as allocated by stack_new.

enum 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;

  • STACK_QUERY_ELEMENT_COUNT
    • query_input is NULL.
    • query_output must point to an 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 stack_guaranteed_push).

See Also