r6.1.1:lfds611_ringbuffer_new
Jump to navigation
Jump to search
Source Files
/liblfds611/src/lfds611_ringbuffer/lfds611_ringbuffer_new.c /liblfds611/inc/liblfds611.h
Prototype
int lfds611_ringbuffer_new( struct lfds611_ringbuffer_state **rs, lfds611_atom_t number_elements,
int (*user_data_init_function)(void **user_data, void *user_state),
void *user_state );
Parameters
struct lfds611_ringbuffer_state **rs
- A pointer to a pointer onto which is allocated the state which represents this ringbuffer. Set to NULL if ringbuffer creation fails.
lfds611_atom_t number_elements
- The number of elements in the ringbuffer. If not all elements could be allocated (malloc() fails, or user_data_init_function returns an error), ringbuffer creation fails.
int (*user_data_init_function)(void **user_data, void *user_state)
- This is a callback function, which can be NULL. Each element in the ringbuffer contains as its payload a single void pointer, which the user can set to any value (typically, it points to state the user has allocated). When the ringbuffer is created, this callback function will be called for each element, where the address of the user data void pointer is provided to the user, for example, to have memory allocated onto it. This function must return 1 on successful initialisation and 0 on failure.
void *user_state
- This is passed to each call of user_data_init_function as the second argument to that function. The user is expected to use this to pass state information into his initialisation function. For example, if to initialise ringbuffer elements, a lookup must occur into another data structure, that data structure can be made visible in the initialisation function by being passed in via this argument.
Return Value
Returns 1 on success and 0 on failure, with *rs being set to NULL on failure.
Notes
This function instantiates a ringbuffer. After instantiation any thread (except the instantiating thread) must before using the ringbuffer first call lfds611_ringbuffer_use.