View source for Atomqueue.c File Reference

__NOTOC__
== Queue library ==

This module implements a queue / message-passing library with the following features:

* '''Flexible blocking APIs'''
*: Threads which wish to make a call which may block can choose whether to block, block with timeout, or not block and return a relevent status code.
* '''Interrupt-safe calls'''
*: All APIs can be called from interrupt context. Any calls which could potentially block have optional parameters to prevent blocking if you wish to call them from interrupt context. Any attempt to make a call which would block from interrupt context will be automatically and safely prevented.
* '''Priority-based queueing'''
*: Where multiple threads are blocking on a queue, they are woken in order of the threads' priorities. Where multiple threads of the same priority are blocking, they are woken in FIFO order.
* '''Configurable queue sizes'''
*: Queues can be created with any sized message, and any number of stored messages.
* '''Smart queue deletion'''
*: Where a queue is deleted while threads are blocking on it, all blocking threads are woken and returned a status code to indicate the reason for being woken.

== Usage instructions ==
All queue objects must be initialised before use by calling atomQueueCreate(). Once initialised atomQueueGet() and atomQueuePut() are used to send and receive messages via the queue respectively.

Messages can be added to a queue by calling atomQueuePut(). If the queue is full the caller will block until space becomes available (by a message being removed from the queue). Optionally a non-blocking call can be made in which case the call will return with a status code indicating that the queue is full. This allows messages to be posted from interrupt handlers or threads which you do not wish to block, providing it is not fatal that the call could fail if the queue was full.

Messages can be received from the queue by calling atomQueueGet(). This will return the first message available in the queue in FIFO order. If the queue is empty then the call will block. Optionally, a non-blocking call can be made in which case the call will return with a status code indicating that the queue is full. This allows messages to be received by interrupt handlers or threads which you do not wish to block.

A queue which is no longer required can be deleted using atomQueueDelete(). This function automatically wakes up any threads which are waiting on the deleted queue.


<syntaxhighlight lang="c">
#include <stdio.h>
#include <string.h>
#include "atom.h"
#include "atomqueue.h"
#include "atomtimer.h"
</syntaxhighlight>

== Data Structures ==
struct  queue_timer
== Typedefs ==
typedef struct queue_timer QUEUE_TIMER

== Functions ==
uint8_t [[EmSys:Atomthread Queue Functions Reference#atomQueueCreate()|atomQueueCreate]](ATOM_QUEUE *qptr, uint8_t *buff_ptr, uint32_t unit_size, uint32_t max_num_msgs)<br />
uint8_t [[EmSys:Atomthread Queue Functions Reference#atomQueueDelete()|atomQueueDelete]](ATOM_QUEUE *qptr)<br />
uint8_t [[EmSys:Atomthread Queue Functions Reference#atomQueueGet()|atomQueueGet]](ATOM_QUEUE *qptr, int32_t timeout, uint8_t *msgptr)<br />
uint8_t [[EmSys:Atomthread Queue Functions Reference#atomQueuePut()|atomQueuePut]](ATOM_QUEUE *qptr, int32_t timeout, uint8_t *msgptr)<br />