Difference between pages "r6:Function:ringbuffer get read element" and "r6:Function:ringbuffer get write element"
(Difference between pages)
Jump to navigation
Jump to search
m (1 revision imported) |
m (1 revision imported) |
||
| Line 4: | Line 4: | ||
==Prototype== | ==Prototype== | ||
struct freelist_element * | struct freelist_element *ringbuffer_get_current_write_element( struct ringbuffer_state *rs, struct freelist_element **fe, int *overwrite_flag ); | ||
==Parameters== | ==Parameters== | ||
| Line 11: | Line 11: | ||
''struct freelist_element **fe'' | ''struct freelist_element **fe'' | ||
: A pointer to a pointer which will be set to point to the freelist element obtained from the ringbuffer. | : 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. | ||
''int *overwrite_flag'' | |||
: 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 element. This argument can be NULL. | |||
==Return Value== | ==Return Value== | ||
Returns a pointer to the current ringbuffer | Returns a pointer to the current ringbuffer write element. This function always succeeds. | ||
==Notes== | ==Notes== | ||
The ringbuffer uses freelist elements and as such when obtaining elements from the ringbuffer, freelist elements are obtained. As such, to | 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]]''. | ||
To permit concurrent readers and writers, there must be a way to protect an element which is being | 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: | * [[r6:Function:ringbuffer_put_write_element|ringbuffer_put_write_element]] | ||
* [[r6:Function: | * [[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_get_and_put.c /inc/liblfds.h
Prototype
struct freelist_element *ringbuffer_get_current_write_element( struct ringbuffer_state *rs, struct freelist_element **fe, int *overwrite_flag );
Parameters
struct ringbuffer_state *rs
- A ringbuffer state as allocated by ringbuffer_new.
struct freelist_element **fe
- 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.
int *overwrite_flag
- 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 element. This argument can be NULL.
Return Value
Returns a pointer to the current ringbuffer write element. This function always succeeds.
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, freelist_set_user_data_in_element.
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).