circqueue.h File Reference

Public header for 1 reader, 1 writer circular queue. More...

#include <pios.h>
#include <stdint.h>

Go to the source code of this file.

Typedefs
typedef struct circ_queue *	circ_queue_t

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)
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_read_completed (circ_queue_t q)
void	circ_queue_read_completed_multi (circ_queue_t q, uint16_t num)
uint16_t	circ_queue_read_data (circ_queue_t q, void *buf, uint16_t num)
uint16_t	circ_queue_write_data (circ_queue_t q, const void *buf, uint16_t num)
void	circ_queue_clear (circ_queue_t q)

Detailed Description

Public header for 1 reader, 1 writer circular queue.

Author

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

Definition in file circqueue.h.

Typedef Documentation

typedef struct circ_queue* circ_queue_t

Definition at line 32 of file circqueue.h.

Function Documentation

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]

q

Handle 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]	q	The circular q handle.
[in]	amt	The 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_size	The size of each element, as obtained from sizeof().
[in]	num_elem	The 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]

q

Handle 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]	q	Handle to the circula queue.
[in]	num	Number 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]	q	Handle to circular queue.
[out]	contig	Returns number of contig elements that can be read at once.
[out]	avail	Returns 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]	q	Handle to circular queue.
[out]	contig	The num elements available for contiguous write.
[out]	avail	The 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.