dRonin  adbada4
dRonin firmware
 All Data Structures Namespaces Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
circqueue.c File Reference

Implements a 1 reader, 1 writer nonblocking circular queue. More...

#include <circqueue.h>

Go to the source code of this file.

Data Structures

struct  circ_queue
 

Functions

circ_queue_t circ_queue_new (uint16_t elem_size, uint16_t num_elem)
 
void * circ_queue_write_pos (circ_queue_t q, uint16_t *contig, uint16_t *avail)
 
static uint16_t advance_by_n (uint16_t num_pos, uint16_t current_pos, uint16_t num_to_advance)
 
static uint16_t next_pos (uint16_t num_pos, uint16_t current_pos)
 
int circ_queue_advance_write_multi (circ_queue_t q, uint16_t amt)
 
int circ_queue_advance_write (circ_queue_t q)
 
void * circ_queue_read_pos (circ_queue_t q, uint16_t *contig, uint16_t *avail)
 
void circ_queue_clear (circ_queue_t q)
 
void circ_queue_read_completed (circ_queue_t q)
 
void circ_queue_read_completed_multi (circ_queue_t q, uint16_t num)
 
uint16_t circ_queue_write_data (circ_queue_t q, const void *buf, uint16_t num)
 
uint16_t circ_queue_read_data (circ_queue_t q, void *buf, uint16_t num)
 

Detailed Description

Implements a 1 reader, 1 writer nonblocking circular queue.

Author
dRonin, http://dRonin.org/, Copyright (C) 2015-2016

Definition in file circqueue.c.

Function Documentation

static uint16_t advance_by_n ( uint16_t  num_pos,
uint16_t  current_pos,
uint16_t  num_to_advance 
)
inlinestatic

Definition at line 123 of file circqueue.c.

int circ_queue_advance_write ( circ_queue_t  q)

Makes the current block of data available to the reader and advances write pos. This may fail if the queue contain num_elems -1 elements, in which case the advance may be retried in the future. In this case, data already written to write_pos is preserved and the advance may be retried (or overwritten with new data).

Parameters
[in]qHandle to circular queue.
Returns
0 if the write succeeded, nonzero on error.

Definition at line 192 of file circqueue.c.

int circ_queue_advance_write_multi ( circ_queue_t  q,
uint16_t  amt 
)

Makes multiple elements available to the reader. Amt is expected to be equal or less to an 'avail' returned by circ_queue_cur_write_pos.

Parameters
[in]qThe circular q handle.
[in]amtThe number of bytes we've filled in for the reader.
Returns
0 if the write succeeded

Definition at line 149 of file circqueue.c.

void circ_queue_clear ( circ_queue_t  q)

Empties all elements from the queue.

Definition at line 246 of file circqueue.c.

circ_queue_t circ_queue_new ( uint16_t  elem_size,
uint16_t  num_elem 
)

Allocate a new circular queue.

Parameters
[in]elem_sizeThe size of each element, as obtained from sizeof().
[in]num_elemThe number of elements in the queue. The capacity is one less than this (it may not be completely filled).
Returns
The handle to the circular queue.

Definition at line 48 of file circqueue.c.

void circ_queue_read_completed ( circ_queue_t  q)

Releases an element of read data obtained by circ_queue_read_pos. Behavior is undefined if circ_queue_read_pos did not previously return a block of data.

Parameters
[in]qHandle to the circular queue.

Definition at line 256 of file circqueue.c.

void circ_queue_read_completed_multi ( circ_queue_t  q,
uint16_t  num 
)

Releases multiple elements of read data obtained by circ_queue_read_pos. Behavior is undefined if returning more than circ_queue_read_pos previously signaled in contig.

Parameters
[in]qHandle to the circula queue.
[in]numNumber of elements to release.

Definition at line 276 of file circqueue.c.

uint16_t circ_queue_read_data ( circ_queue_t  q,
void *  buf,
uint16_t  num 
)

Definition at line 331 of file circqueue.c.

void* circ_queue_read_pos ( circ_queue_t  q,
uint16_t *  contig,
uint16_t *  avail 
)

Returns a block of data to the reader. The block is "claimed" until released with circ_queue_read_completed. No new data is available until that call is made (instead the same block-in-progress will be returned).

Parameters
[in]qHandle to circular queue.
[out]contigReturns number of contig elements that can be read at once.
[out]availReturns number of elements available to read without any further writer activity.
Returns
pointer to the data, or NULL if the queue is empty.

Definition at line 208 of file circqueue.c.

uint16_t circ_queue_write_data ( circ_queue_t  q,
const void *  buf,
uint16_t  num 
)

Definition at line 302 of file circqueue.c.

void* circ_queue_write_pos ( circ_queue_t  q,
uint16_t *  contig,
uint16_t *  avail 
)

Get a pointer to the current queue write position. This position is unavailable to the reader and may be filled in with the desired data without respect to any synchronization. No promise is made that circ_queue_advance_write will succeed, though.

Alternatively, in *contig we return the number of things that can be filled in. We promise that you can circ_queue_advance_write_multi that many. You can also always write one, but no promises you'll be able to advance write.

Parameters
[in]qHandle to circular queue.
[out]contigThe num elements available for contiguous write.
[out]availThe num elements available before a reader has freed up more space. (Includes wraparound/non-contig elems).
Returns
The position for new data to be written to (of size elem_size).

Definition at line 84 of file circqueue.c.

static uint16_t next_pos ( uint16_t  num_pos,
uint16_t  current_pos 
)
inlinestatic

Definition at line 138 of file circqueue.c.