ringbuffer.h File Reference

#include <stdint.h>

Go to the source code of this file.

Macros
#define	LINKED_FUNCTION   extern

Typedefs
typedef struct ringbuffer_context *	ringbuffer_context_t
	Points to an allocated memory for ringbuffer module. More...

Functions
ringbuffer_context_t	ringbuffer_init (void *target_array, const unsigned int element_size, const unsigned int element_count, const unsigned int initial_read_index, const unsigned int initial_write_index)
	Initiate a single instance of ringbuffer management. More...
void	ringbuffer_read (ringbuffer_context_t context, void *pointer_to_output)
	Copy value from an element pointed by read index, to an intended variable. More...
void	ringbuffer_write (ringbuffer_context_t context, const void *pointer_to_input)
	Put value from a variable to an element which pointed by write index. More...
unsigned int	ringbuffer_get_read_index (const ringbuffer_context_t context)
	Get the read index, which means position of read cursor of ring buffer. More...
unsigned int	ringbuffer_get_write_index (const ringbuffer_context_t context)
	Get the write index, which means position of write cursor of ring buffer. More...
unsigned int	ringbuffer_is_empty (const ringbuffer_context_t context)
	Check if the ringbuffer is empty, which indicated by 'read index == write index'. More...
void	ringbuffer_destroy (ringbuffer_context_t *pointer_to_context)
	Clean-up ringbuffer context then NULLify it. More...

Detailed Description

Contains type definitions and functions from ringbuffer module which can be applied on application source code.

Typedef Documentation

ringbuffer_context_t

typedef struct ringbuffer_context* ringbuffer_context_t

Points to an allocated memory for ringbuffer module.

The reason why this library didn't (and won't) store global variables because it would cause trouble if you want to do multiple independent ringbuffer management. You MUST clean it with ringbuffer_destroy function if not in use anymore.

Function Documentation

ringbuffer_destroy()

void ringbuffer_destroy

(

ringbuffer_context_t *

pointer_to_context

)

Clean-up ringbuffer context then NULLify it.

Parameters

pointer_to_context

must has ampersand prefix, as example &my_context

This ensures the context was cleaned-up from memory for safety. So accidental context usage won't cause segmentation fault if it's already cleaned up. Keep in mind that your array won't be cleaned up while calling this function because it's not created by this module. Thus, it's not ringbuffer module's responsibility.

Brief Example

#include <ringbuffer.h>
 
// ...
 
int main() {
    ringbuffer_context_t my_context = ringbuffer_init(
        // ...
    );
 
    // ...
 
    ringbuffer_destroy(&my_context);
    return 0;
}

Examples

pager, and simple.

ringbuffer_get_read_index()

unsigned int ringbuffer_get_read_index

(

const ringbuffer_context_t

context

)

Get the read index, which means position of read cursor of ring buffer.

Parameters

context

came from ringbuffer_init

Returns

unsigned int in bytes unit

ringbuffer_get_write_index()

unsigned int ringbuffer_get_write_index

(

const ringbuffer_context_t

context

)

Get the write index, which means position of write cursor of ring buffer.

Parameters

context

came from ringbuffer_init

Returns

unsigned int in bytes unit

Examples

pager.

ringbuffer_init()

ringbuffer_context_t ringbuffer_init	(	void *	target_array,
		const unsigned int	element_size,
		const unsigned int	element_count,
		const unsigned int	initial_read_index,
		const unsigned int	initial_write_index
	)

Initiate a single instance of ringbuffer management.

Parameters

target_array	will be treated as a ring buffer with this library, set this to NULL will cause ringbuffer_init returns NULL
element_size	in bytes, defines element size of target_array, set this to 0 will cause ringbuffer_init returns NULL
element_count	represents element count of target_array, set this to 0 will cause ringbuffer_init returns NULL
initial_read_index	allows the program to continue previous ring buffer, set to 0 if you don't need this
initial_write_index	allows the program to continue previous ring buffer, set to 0 if you don't need this

Returns

ringbuffer_context_t if parameters are valid, otherwise NULL

This function allocates a memory region for internal operation of ringbuffer management and references target_array into that memory region while also stores additional informations such as element size and count. Remember to always call ringbuffer_destroy function once if you're not using ringbuffer anymore.

Brief Example

#include <ringbuffer.h>
 
unsigned long my_array[128];
 
int main() {
    ringbuffer_context_t my_context = ringbuffer_init(my_array,
                                                      sizeof(unsigned long),
                                                      128,
                                                      0, 0);
 
    //...
}

Examples

pager, and simple.

ringbuffer_is_empty()

unsigned int ringbuffer_is_empty

(

const ringbuffer_context_t

context

)

Check if the ringbuffer is empty, which indicated by 'read index == write index'.

Parameters

context

came from ringbuffer_init

Returns

1 if empty, 0 if has element to read

Examples

simple.

ringbuffer_read()

void ringbuffer_read	(	ringbuffer_context_t	context,
		void *	pointer_to_output
	)

Copy value from an element pointed by read index, to an intended variable.

Parameters

context	came from ringbuffer_init
pointer_to_output	points where to write the data, remember to always use "&" symbol prefix (a.k.a. reference)

The ringbuffer_read function copies value from an element based on read index which stored privately in the context, into a variable which you'd pointed via pointer_to_output parameter. After called this function, the ringbuffer module automatically shifts the read index for future use, unless your app program read all elements in the array (or in other word, it's "empty"). When it's already empty and you keep reading, it won't do anything. Internally, the ringbuffer considered "empty" when read index equals write index.

Brief Example

#include <ringbuffer.h>
 
unsigned long my_array[128];
 
int main() {
    ringbuffer_context_t my_context = ringbuffer_init(my_array,
                                                      sizeof(unsigned long),
                                                      128,
                                                      0, 0);
    // Write the ringbuffer first...
 
    if (ringbuffer_is_empty(my_context)) {
        // It's empty and you can't read it.
        return 1;
    }
 
    unsigned long my_var;
    ringbuffer_read(my_context, &my_var);
 
    // my_var was modified, do something with it...
}

Examples

simple.

ringbuffer_write()

void ringbuffer_write	(	ringbuffer_context_t	context,
		const void *	pointer_to_input
	)

Put value from a variable to an element which pointed by write index.

Parameters

context	came from ringbuffer_init
pointer_to_input	points where is the variable in the memory, remember to always use "&" symbol prefix (a.k.a. reference)

When attempting to write ring buffer, you have to consider several things:

1. The variable size must equals element size of the array. Otherwise, you'll experience undefined behavior!
2. pointer_to_input always represents a pointer to a variable, so you have to prepend "&" to the variable name. See the example for clear explanation.
3. The new value will be written according to write index which privately located inside context.
4. Write index always be shifted after called this function

Brief Example

#include <ringbuffer.h>
 
unsigned long my_array[128];
 
int main() {
    ringbuffer_context_t my_context = ringbuffer_init(my_array,
                                                      sizeof(unsigned long),
                                                      128,
                                                      0, 0);
    unsigned long my_math_result = 0UL;
 
    // Do something with my_math_result variable...
 
    ringbuffer_write(my_context, &my_math_result);
 
    // ...
}

Examples

pager, and simple.