Difference between pages "r6:Function:ringbuffer get write element" and "r6:Function:ringbuffer new"

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/ringbuffer/ringbuffer_get_and_put.c
  /src/ringbuffer/ringbuffer_new.c
  /inc/liblfds.h
  /inc/liblfds.h


==Prototype==
==Prototype==
  struct freelist_element *ringbuffer_get_current_write_element( struct ringbuffer_state *rs, struct freelist_element **fe, int *overwrite_flag );
  int ringbuffer_new( struct ringbuffer_state **rs, atom_t number_elements,
                    int (*user_data_init_function)(void **user_data, void *user_state),
                    void *user_state );


==Parameters==
==Parameters==
''struct ringbuffer_state *rs''
''struct ringbuffer_state **rs''
: A ringbuffer state as allocated by ''[[r6:Function:ringbuffer_new|ringbuffer_new]]''.
: A pointer to a pointer onto which is allocated the state which represents this ringbuffer.  Set to NULL if ringbuffer creation fails.


''struct freelist_element **fe''
''atom_t number_elements''
: A pointer to a pointer which will be set to point to the freelist element obtained from the ringbuffer.  This function never fails, so a NULL is never returned.
: 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 *overwrite_flag''
''int (*user_data_init_function)(void **user_data, void *user_state)''
: A pointer to an integer, where the integer is set to 1 if the function consumed a data bearing element from the ringbuffer or is set to 0 if the function was able to use an existing, available elementThis argument can be NULL.
: 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 functionFor 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==
==Return Value==
Returns a pointer to the current ringbuffer write element.  This function always succeeds.
Returns 1 on success and 0 on failure, with ''*rs'' being set to NULL on failure.


==Notes==
==Notes==
The ringbuffer uses freelist elements and as such when obtaining elements from the ringbuffer, freelist elements are obtained.  As such, to set the user data in these elements, use the appropriate freelist function, ''[[r6:Function:freelist_set_user_data_in_element|freelist_set_user_data_in_element]]''.
This function instantiates a ringbuffer.
 
To permit concurrent readers and writers, there must be a way to protect an element which is being written from being read before it is fully written.  The solution adopted is for a thread performing a write to detach, if one is available, an unused element from the ringbuffer, or, if there are no unused elements, the current read element (thus leading to the over-writing of its contents).


==See Also==
==See Also==
* [[r6:API:Ringbuffer|Ringbuffer]]
* [[r6:API:Ringbuffer|Ringbuffer]]
* [[r6:Function:ringbuffer_put_write_element|ringbuffer_put_write_element]]
* [[r6:Function:ringbuffer_delete|ringbuffer_delete]]
* [[r6:Function:freelist_set_user_data_in_element|freelist_set_user_data_in_element]]

Latest revision as of 14:07, 4 January 2015

Source Files

/src/ringbuffer/ringbuffer_new.c
/inc/liblfds.h

Prototype

int ringbuffer_new( struct ringbuffer_state **rs, atom_t number_elements,
                    int (*user_data_init_function)(void **user_data, void *user_state),
                    void *user_state );

Parameters

struct 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.

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.

See Also