function lfds700_stack_pop
Source Files
└───liblfds700
├───inc
│ └───liblfds700
│ lfds700_stack.h
└───src
└───lfds700_stack
lfds700_stack_pop.c
Opaque Structures
struct lfds700_misc_prng_state; struct lfds700_stack_element; struct lfds700_stack_state;
Prototype
int lfds700_stack_pop( struct lfds700_stack_state *ss,
struct lfds700_stack_element **se,
struct lfds700_misc_prng_state *ps );
Parameters
struct lfds700_stack_state *ss
- A pointer to an initialized struct lfds700_stack_state.
struct lfds700_stack_element **se
- A pointer to a user-allocated struct lfds700_stack_state *, which is set to point to the stack element popped from the stack.
struct lfds700_misc_prng_state *ps
- A pointer to an initialized struct lfds700_misc_prng_state.
Return Value
Returns 1 on a successful pop. Returns 0 if popping failed. Popping only fails if the stack is empty.
Notes
This function pops a stack element, with its key and value, from the stack. The key and value are read from the stack element by the macros LFDS700_STACK_GET_KEY_FROM_ELEMENT and LFDS700_STACK_GET_VALUE_FROM_ELEMENT respectively, and can only be correctly read when a stack element is outside of a stack; the macros can be issued at any time, of course, but if the element has not been popped by the thread calling the macro, then there is no guarantee the key and value read will be that which was written into the element. You were warned.
The third argument, the struct lfds700_misc_prng_state, is the state for a single-threaded, fast, high quality random number generator, required by the exponential backoff code. Each thread should allocate and initialize one of these structures, and then it can be used for all API calls which take this argument.
Example
#include "liblfds700.h"
#include <stdio.h>
int main()
{
char
name[64] = "Bob the Skutter",
*temp_name;
struct lfds700_misc_prng_state
ps;
struct lfds700_stack_element
se,
*temp_se;
struct lfds700_stack_state
ss;
lfds700_misc_library_init_valid_on_current_logical_core();
lfds700_misc_prng_init( &ps );
lfds700_stack_init_valid_on_current_logical_core( &ss, NULL );
LFDS700_STACK_SET_VALUE_IN_ELEMENT( se, name );
lfds700_stack_push( &ss, &se, &ps );
lfds700_stack_pop( &ss, &temp_se, &ps );
temp_name = (char *) LFDS700_STACK_GET_VALUE_FROM_ELEMENT( *temp_se );
printf( "name = %s\n", temp_name );
lfds700_stack_cleanup( &ss, NULL );
lfds700_misc_library_cleanup();
return( EXIT_SUCCESS );
}