Ring Buffer

Data Structures
struct	_amxc_rbuffer
	The ring buffer structure. More...

Typedefs
typedef struct _amxc_rbuffer	amxc_rbuffer_t
	The ring buffer structure. More...

Functions
int	amxc_rbuffer_new (amxc_rbuffer_t **rb, const size_t size)
	Allocates a ring buffer. More...
void	amxc_rbuffer_delete (amxc_rbuffer_t **rb)
	Frees the previously allocated ring buffer. More...
int	amxc_rbuffer_init (amxc_rbuffer_t *const rb, const size_t size)
	Initializes a ring buffer. More...
void	amxc_rbuffer_clean (amxc_rbuffer_t *const rb)
	Frees the buffer and sets all pointers of the ring buffer structure to NULL. More...
int	amxc_rbuffer_grow (amxc_rbuffer_t *const rb, const size_t size)
	Grows the ring buffer. More...
int	amxc_rbuffer_shrink (amxc_rbuffer_t *const rb, const size_t size)
	Shrinks the ring buffer. More...
ssize_t	amxc_rbuffer_read (amxc_rbuffer_t *const rb, char *const buf, size_t count)
	Reads a number of bytes from the ring buffer. More...
ssize_t	amxc_rbuffer_write (amxc_rbuffer_t *const rb, const char *const buf, const size_t count)
	Writes a number of bytes to the ring buffer. More...
size_t	amxc_rbuffer_size (const amxc_rbuffer_t *const rb)
	Get the size of the data stored in the ring buffer. More...
AMXC_INLINE size_t	amxc_rbuffer_capacity (const amxc_rbuffer_t *const rb)
	Get the capacity of the ring buffer. More...
AMXC_INLINE bool	amxc_rbuffer_is_empty (const amxc_rbuffer_t *const rb)
	Checks that the ring buffer is empty. More...

Detailed Description

Typedef Documentation

amxc_rbuffer_t

typedef struct _amxc_rbuffer amxc_rbuffer_t

The ring buffer structure.

Function Documentation

amxc_rbuffer_capacity()

AMXC_INLINE size_t amxc_rbuffer_capacity

(

const amxc_rbuffer_t *const

rb

)

Get the capacity of the ring buffer.

The capacity is the maximum bytes that can be stored in the ring buffer. The capacity - the size is the number of bytes that is currently not used.

Parameters

rb	a pointer to the ring buffer structure

Returns

The number of bytes that can be stored in the ring buffer

Definition at line 286 of file amxc_rbuffer.h.

                                                             {
    return rb != NULL ? rb->buffer_end - rb->buffer_start : 0;
}

amxc_rbuffer_clean()

void amxc_rbuffer_clean

(

amxc_rbuffer_t *const

rb

)

Frees the buffer and sets all pointers of the ring buffer structure to NULL.

Parameters

rb	a pointer to the ring buffer structure

Definition at line 134 of file amxc_rbuffer.c.

                                                  {
    when_null(rb, exit);
 
    free(rb->buffer_start);
    rb->buffer_start = NULL;
    rb->buffer_end = NULL;
    rb->read_pos = NULL;
    rb->write_pos = NULL;
 
exit:
    return;
}

amxc_rbuffer_delete()

void amxc_rbuffer_delete

(

amxc_rbuffer_t **

rb

)

Frees the previously allocated ring buffer.

Frees the ring buffer, all data that is still in the buffer will be lost. Also frees the allocated memory to store the ring buffer structure and sets the pointer in the structure to NULL.

Note

Only call this function for ring buffers that are allocated on the heap using amxc_rbuffer_new

Parameters

rb	a pointer to the location where the pointer to the ring buffer is stored

Definition at line 96 of file amxc_rbuffer.c.

                                              {
    when_null(rb, exit);
 
    amxc_rbuffer_clean(*rb);
    free(*rb);
    *rb = NULL;
 
exit:
    return;
}

amxc_rbuffer_grow()

int amxc_rbuffer_grow	(	amxc_rbuffer_t *const	rb,
		const size_t	size
	)

Grows the ring buffer.

Increases the capacity of the ring buffer with a number of bytes. The extra memory is always allocated behind the current position of the write pointer. Growing the ring buffer has no effect on the data that is already in the ring buffer.

Parameters

rb	a pointer to the ring buffer structure
size	the number of bytes the ring buffer has to grow

Returns

0 on success. -1 if an error has occurred.

Definition at line 147 of file amxc_rbuffer.c.

                                                                   {
    int retval = -1;
    size_t read_pos = 0;
    size_t write_pos = 0;
    size_t new_size = 0;
    char* new_buffer = NULL;
 
    when_null(rb, exit);
 
    read_pos = rb->read_pos - rb->buffer_start;
    write_pos = rb->write_pos - rb->buffer_start;
 
    new_size = (rb->buffer_end - rb->buffer_start) + size;
    new_buffer = amxc_rbuffer_alloc(rb, new_size);
    if(!new_buffer) {
        goto exit;
    }
 
    rb->buffer_start = new_buffer;
    rb->buffer_end = rb->buffer_start + new_size;
    rb->read_pos = rb->buffer_start + read_pos;
    rb->write_pos = rb->buffer_start + write_pos;
 
    // if the read pointer is after the write pointer,
    // the read pointer must be move the number of bytes
    // the buffer has grown, and the data has to be moved
    if(rb->read_pos > rb->write_pos) {
        memmove(rb->buffer_start + read_pos + size,
                rb->buffer_start + read_pos,
                size);
        memset(rb->buffer_start + read_pos, 0, size);
        rb->read_pos += size;
    } else {
        memset(rb->buffer_start + write_pos, 0, size);
    }
 
    retval = 0;
 
exit:
    return retval;
}

amxc_rbuffer_init()

int amxc_rbuffer_init	(	amxc_rbuffer_t *const	rb,
		const size_t	size
	)

Initializes a ring buffer.

Initializes the ring buffer structure. Memory is allocated from the heap to be able to store the number of bytes requested.

This function is typically called for ring buffers that are on the stack. Allocating and initializing a ring buffer on the heap can be done using amxc_rbuffer_new

Note

When calling this function on an already allocated and initialized ring buffer a memory leak occurs, the previously allocated buffer is not reachable anymore. Use amxc_rbuffer_clean to free the buffer and reset all the pointers in the ring buffer structure to NULL.

Parameters

rb	a pointer to the ring buffer structure.
size	the size of the ring buffer in number of bytes

Returns

0 on success or -1 when an error occured.

Definition at line 107 of file amxc_rbuffer.c.

                                                                   {
    int retval = -1;
    when_null(rb, exit);
 
    rb->buffer_start = NULL;
    rb->buffer_end = NULL;
    rb->read_pos = NULL;
    rb->write_pos = NULL;
 
    if(size == 0) {
        retval = 0;
        goto exit;
    }
 
    rb->buffer_start = amxc_rbuffer_alloc(rb, size);
    when_null(rb->buffer_start, exit);
 
    rb->buffer_end = rb->buffer_start + size;
    rb->read_pos = rb->buffer_start;
    rb->write_pos = rb->buffer_start;
 
    retval = 0;
 
exit:
    return retval;
}

amxc_rbuffer_is_empty()

AMXC_INLINE bool amxc_rbuffer_is_empty

(

const amxc_rbuffer_t *const

rb

)

Checks that the ring buffer is empty.

Parameters

rb	a pointer to the ring buffer structure

Returns

true when there is no data in the ring buffer, or false when there is at least 1 byte of data stored in the ring buffer.

Definition at line 302 of file amxc_rbuffer.h.

                                                           {
    return rb != NULL ? (rb->read_pos == rb->write_pos) : true;
}

amxc_rbuffer_new()

int amxc_rbuffer_new	(	amxc_rbuffer_t **	rb,
		const size_t	size
	)

Allocates a ring buffer.

Allocates and initializes memory to store a ring buffer. This functions allocates memory for the ring buffer structure as well as memory for the ring buffer itself. This function allocates memory from the heap, if a ring buffer structure is on the stack, it can be initialized using function amxc_rbuffer_init

The size of the ring buffer is not fixed and can be changed with the functions amxc_rbuffer_grow or amxc_rbuffer_shrink

The size of the ring buffer is expressed in number of bytes that can be stored in the ring buffer.

Note

The allocated memory must be freed when not used anymore, use amxc_rbuffer_delete to free the memory of the ring buffer and the ring buffer structure and amxc_rbuffer_clean to free the buffer itself, but keep the ring buffer structure.

Parameters

rb	a pointer to the location where the pointer to the new ring buffer structure can be stored
size	the size of the ring buffer in number of bytes

Returns

-1 if an error occurred. 0 on success

Definition at line 79 of file amxc_rbuffer.c.

                                                             {
    int retval = -1;
    when_null(rb, exit);
 
    *rb = (amxc_rbuffer_t*) calloc(1, sizeof(amxc_rbuffer_t));
    when_null(*rb, exit);
 
    retval = amxc_rbuffer_init(*rb, size);
    if(retval == -1) {
        free(*rb);
        *rb = NULL;
    }
 
exit:
    return retval;
}

amxc_rbuffer_read()

ssize_t amxc_rbuffer_read	(	amxc_rbuffer_t *const	rb,
		char *const	buf,
		size_t	count
	)

Reads a number of bytes from the ring buffer.

Copies bytes from the ring buffer, starting from the current read position, into the provided buffer to a maximum number of bytes specified. When less bytes then the specified count are copied in the provided buffer, no more data is available in the ring buffer.

Parameters

rb	a pointer to the ring buffer structure
buf	a pointer to a buffer where the data can be copied in.
count	the maximum number of bytes that can be copied

Returns

The number of bytes copied, when less then the specified maximum, the ring buffer is empty.

Definition at line 250 of file amxc_rbuffer.c.

                                        {
    ssize_t retval = -1;
    when_null(rb, exit);
    when_null(buf, exit);
 
    if((count == 0) || (rb->read_pos == rb->write_pos)) {
        retval = 0;
        goto exit;
    }
 
    if(rb->read_pos > rb->write_pos) {
        size_t data_size = rb->buffer_end - rb->read_pos;
        if(count > data_size) {
            size_t max_size = 0;
            memcpy(buf, rb->read_pos, data_size);
            count -= data_size;
            max_size = rb->write_pos - rb->buffer_start;
            memcpy(buf + data_size,
                   rb->buffer_start,
                   count > max_size ? max_size : count);
            retval = data_size + (count > max_size ? max_size : count);
            rb->read_pos = rb->buffer_start +
                (count > max_size ? max_size : count);
        } else {
            data_size = rb->write_pos - rb->read_pos;
            memcpy(buf, rb->read_pos, data_size > count ? count : data_size);
            rb->read_pos += data_size > count ? count : data_size;
            retval = data_size > count ? count : data_size;
        }
    } else {
        size_t data_size = rb->write_pos - rb->read_pos;
        memcpy(buf, rb->read_pos, data_size > count ? count : data_size);
        rb->read_pos += data_size > count ? count : data_size;
        retval = data_size > count ? count : data_size;
    }
 
exit:
    return retval;
}

amxc_rbuffer_shrink()

int amxc_rbuffer_shrink	(	amxc_rbuffer_t *const	rb,
		const size_t	size
	)

Shrinks the ring buffer.

Shrinks the ring buffer by the given number of bytes. The memory is freed.

Note

Shrinking the ring buffer could lead to data loss. The buffer shrinks from the current read pointer to the write pointer. The data loss will always be the last part written in the ring buffer.

Parameters

rb	a pointer to the ring buffer structure
size	the number of bytes the ring buffer has to shrink

Returns

0 on success. -1 if an error has occurred.

Definition at line 190 of file amxc_rbuffer.c.

                                                                     {
    int retval = -1;
    size_t buffer_size = 0;
    size_t new_size = 0;
    size_t read_pos = 0;
    size_t write_pos = 0;
    char* new_buffer = NULL;
    when_null(rb, exit);
 
    buffer_size = rb->buffer_end - rb->buffer_start;
    when_true(size > buffer_size, exit);
 
    if(size == buffer_size) {
        amxc_rbuffer_clean(rb);
        retval = 0;
        goto exit;
    }
 
    new_size = (rb->buffer_end - rb->buffer_start) - size;
    if(rb->read_pos > rb->write_pos) {
        size_t bytes = rb->read_pos - rb->buffer_start;
        size_t move = (size > bytes) ? bytes : size;
        memmove(rb->buffer_start + move,
                rb->read_pos,
                rb->buffer_end - rb->read_pos);
        rb->read_pos -= move;
        if(rb->read_pos > rb->buffer_start) {
            if(rb->write_pos > rb->read_pos) {
                rb->write_pos = rb->read_pos - 1;
            }
        } else {
            rb->write_pos = rb->buffer_start + new_size;
        }
    } else {
        size_t move = rb->write_pos - rb->read_pos;
        memmove(rb->buffer_start, rb->read_pos, move);
        rb->read_pos = rb->buffer_start;
        if(move > new_size) {
            rb->write_pos = rb->buffer_start + new_size;
        } else {
            rb->write_pos = rb->buffer_start + move;
        }
    }
 
    read_pos = rb->read_pos - rb->buffer_start;
    write_pos = rb->write_pos - rb->buffer_start;
 
    new_buffer = (char*) realloc(rb->buffer_start, new_size);
 
    rb->buffer_start = new_buffer;
    rb->buffer_end = rb->buffer_start + new_size;
    rb->read_pos = rb->buffer_start + read_pos;
    rb->write_pos = rb->buffer_start + write_pos;
 
    retval = 0;
 
exit:
    return retval;
}

amxc_rbuffer_size()

size_t amxc_rbuffer_size

(

const amxc_rbuffer_t *const

rb

)

Get the size of the data stored in the ring buffer.

Parameters

rb	a pointer to the ring buffer structure

Returns

The number of bytes stored in the ring buffer

Definition at line 327 of file amxc_rbuffer.c.

                                                         {
    size_t retval = 0;
    when_null(rb, exit);
    when_true(rb->read_pos == rb->write_pos, exit);
 
    if(rb->read_pos > rb->write_pos) {
        retval = (rb->buffer_end - rb->read_pos) +
            (rb->write_pos - rb->buffer_start);
    } else {
        retval = (rb->write_pos - rb->read_pos);
    }
 
exit:
    return retval;
}

amxc_rbuffer_write()

ssize_t amxc_rbuffer_write	(	amxc_rbuffer_t *const	rb,
		const char *const	buf,
		const size_t	count
	)

Writes a number of bytes to the ring buffer.

Copies the specified number of bytes to the ring buffer, starting from the current write position, from the provided buffer. The ring buffer grows when there is not enough space left in the ring buffer.

Parameters

rb	a pointer to the ring buffer structure
buf	a pointer to a buffer that contains the data that must be put in the ring buffer.
count	the number of bytes that need to be copied in the ring buffer

Returns

The number of bytes copied or -1 when failed to copy the bytes in the ring buffer.

Definition at line 292 of file amxc_rbuffer.c.

                                               {
    ssize_t retval = -1;
    size_t free_space = 0;
    when_null(rb, exit);
 
    // check space, grow if needed
    free_space = (rb->buffer_end - rb->buffer_start) - amxc_rbuffer_size(rb);
    if(free_space < count) {
        when_failed(amxc_rbuffer_grow(rb, count * 2), exit);
    }
 
    // check border
    if(rb->write_pos >= rb->read_pos) {
        free_space = rb->buffer_end - rb->write_pos;
        if(count > free_space) {
            memcpy(rb->write_pos, buf, free_space);
            memcpy(rb->buffer_start, buf + free_space, count - free_space);
            rb->write_pos = rb->buffer_start + (count - free_space);
        } else {
            memcpy(rb->write_pos, buf, count);
            rb->write_pos += count;
        }
    } else {
        memcpy(rb->write_pos, buf, count);
        rb->write_pos += count;
    }
 
    retval = count;
 
exit:
    return retval;
}