2.6. queue — Queue channel

The most common channel is the queue. It can be either synchronous or semi-asynchronous. In the synchronous version the writing thread will block until all written data has been read by the reader. In the semi-asynchronous version the writer writes to a buffer within the queue, and only blocks all data does not fit in the buffer. The buffer size is selected by the application when initializing the queue.

The diagram below shows how two threads communicates using a queue. The writer thread writes from its source buffer to the queue. The reader thread reads from the queue to its destination buffer.

../../_images/queue.jpg

The data is either copied directly from the source to the destination buffer (1. in the figure), or via the internal queue buffer (2. in the figure).

  1. The reader thread is waiting for data. The writer writes from its source buffer directly to the readers’ destination buffer.
  2. The reader thread is not waiting for data. The writer writes from its source buffer into the queue buffer. Later, the reader reads data from the queue buffer to its destination buffer.

2.6.1. Example usage

This is a small example of writing a value from an interrupt handler to a thread.

struct queue_t queue;
uint8_t buf[8];

/* The interrupt handler. */
ISR(foo)
{
    uint8_t byte;

    byte = 1;
    queue_write_isr(&queue, &byte, sizeof(byte));
}

/* The thread. */
void bar(void *arg_p)
{
    uint8_t byte;

    /* Must be called before any read from or write to the
       queue. */
    queue_init(&queue, &buf[0], sizeof(buf));

    queue_read(&queue, &byte, sizeof(byte))

    /* Do something with the read byte. */
}

Source code: src/sync/queue.h, src/sync/queue.c

Test code: tst/sync/queue/main.c

Test coverage: src/sync/queue.c

Example code: examples/queue/main.c

Defines

QUEUE_FLAGS_NON_BLOCKING_READ
QUEUE_INIT_DECL(_name, _buf, _size)

Enums

enum queue_state_t

Values:

QUEUE_STATE_INITIALIZED = 0

Queue initialized state.

QUEUE_STATE_RUNNING

Queue running state.

QUEUE_STATE_STOPPED

Queue stopped state.

Functions

int queue_init(struct queue_t *self_p, void *buf_p, size_t size)

Initialize given queue with given optional buffer.

Return
zero(0) or negative error code
Parameters
  • self_p: Queue to initialize.
  • buf_p: Buffer for data storage. Give as NULL to disable buffering and only allow the writer to write directly into the reader’s buffer, blocking the writer until all data has been written.
  • size: Size of given buffer.

int queue_start(struct queue_t *self_p)

Start given queue. It is not required to start a queue unless it has been stopped.

Return
zero(0) or negative error code.
Parameters
  • self_p: Queue to start.

int queue_stop(struct queue_t *self_p)

Stop given queue. Any ongoing read and write operations will return with the currently read/written number of bytes. Any read and write operations on a stopped queue will return zero(0).

Return
true(1) if a thread was resumed, false(0) if no thread was resumed, or negative error code.
Parameters
  • self_p: Queue to stop.

int queue_stop_isr(struct queue_t *self_p)

Same as queue_stop() but from isr or with the system lock taken (see sys_lock()).

ssize_t queue_read(struct queue_t *self_p, void *buf_p, size_t size)

Read from given queue. Blocks until size bytes has been read.

Return
Number of bytes read or negative error code.
Parameters
  • self_p: Queue to read from.
  • buf_p: Buffer to read into.
  • size: Number of bytes to read.

ssize_t queue_write(struct queue_t *self_p, const void *buf_p, size_t size)

Write bytes to given queue. Blocks until size bytes has been written.

Return
Number of bytes written or negative error code.
Parameters
  • self_p: Queue to write to.
  • buf_p: Buffer to write from.
  • size: Number of bytes to write.

ssize_t queue_write_isr(struct queue_t *self_p, const void *buf_p, size_t size)

Write bytes to given queue from isr or with the system lock taken (see sys_lock()). May write less than size bytes.

Return
Number of bytes written or negative error code.
Parameters
  • self_p: Queue to write to.
  • buf_p: Buffer to write from.
  • size: Number of bytes to write.

ssize_t queue_size(struct queue_t *self_p)

Get the number of bytes currently stored in the queue. May return less bytes than number of bytes stored in the channel.

Return
Number of bytes in given queue.
Parameters
  • self_p: Queue.

ssize_t queue_unused_size(struct queue_t *self_p)

Get the number of unused bytes in the queue.

Return
Number of unused bytes in given queue.
Parameters
  • self_p: Queue.

ssize_t queue_unused_size_isr(struct queue_t *self_p)

Get the number of unused bytes in the queue from isr or with the system lock taken (see sys_lock()).

Return
Number of unused bytes in given queue.
Parameters
  • self_p: Queue.

ssize_t queue_ignore(struct queue_t *self_p, size_t size)

Ignore given number of bytes at the beginning of the queue by discarding them.

Return
Number of bytes ignored or negative error code.
Parameters
  • self_p: Queue.

struct queue_t

Public Members

struct chan_t base
struct thrd_prio_list_t writers
struct queue_writer_elem_t *writer_p
char *buf_p
size_t size
size_t left
struct queue_t::@125 queue_t::reader
void *buf_p
struct circular_buffer_t buffer
queue_state_t state
int flags