function lfds700_freelist_pop
Source Files
└───liblfds700
├───inc
│ └───liblfds700
│ lfds700_freelist.h
└───src
└───lfds700_freelist
lfds700_freelist_pop.c
Opaque Structures
struct lfds700_freelist_element; struct lfds700_freelist_state; struct lfds700_misc_prng_state;
Prototype
int lfds700_freelist_pop( struct lfds700_freelist_state *fs,
struct lfds700_freelist_element **fe,
struct lfds700_misc_prng_state *ps );
Parameters
struct lfds700_freelist_state *fs
- A pointer to an initialized struct lfds700_freelist_state.
struct lfds700_freelist_element **fe
- A pointer to a user-allocated struct lfds700_freelist_state *, which is set to point to the freelist element popped from the freelist.
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 freelist is empty.
Notes
This function pops a freelist element, with its key and value, from the freelist. The key and value are read from the freelist element by the macros LFDS700_FREELIST_GET_KEY_FROM_ELEMENT and LFDS700_FREELIST_GET_VALUE_FROM_ELEMENT respectively, and can only be correctly read when a freelist element is outside of a freelist; 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 <stdio.h>
#include "liblfds700.h"
int main()
{
char
name[64] = "Bob the Skutter",
*temp_name;
struct lfds700_freelist_element
fe,
*temp_fe;
struct lfds700_freelist_state
fs;
struct lfds700_misc_prng_state
ps;
lfds700_misc_library_init_valid_on_current_logical_core();
lfds700_misc_prng_init( &ps );
lfds700_freelist_init_valid_on_current_logical_core( &fs, NULL );
LFDS700_FREELIST_SET_VALUE_IN_ELEMENT( fe, name );
lfds700_freelist_push( &fs, &fe, &ps );
lfds700_freelist_pop( &fs, &temp_fe, &ps );
temp_name = (char *) LFDS700_FREELIST_GET_VALUE_FROM_ELEMENT( *temp_fe );
printf( "name = %s\n", temp_name );
lfds700_freelist_cleanup( &fs, NULL );
lfds700_misc_library_cleanup();
return( EXIT_SUCCESS );
}