KM3NeT CLB  2.0
KM3NeT CLB v2 Embedded Software
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
queue.h File Reference

Queue is created in statically allocated memory. More...

#include <stdint.h>
#include <stdbool.h>
#include <string.h>

Go to the source code of this file.

Data Structures

struct  QueueDescr
 Queue descriptor. More...
 
struct  Queue
 Queue state. More...
 

Macros

#define Q_INIT(NAME, ENTRY_SIZE, CAPACITY)
 Convenience Macro, defines and inits queue. More...
 

Functions

void * qQueueIP (Queue *q)
 Queue data to the end of the queue in place. More...
 
static bool qQueue (Queue *q, void *data)
 Queue data to the end of the queue. More...
 
bool qContains (Queue *q, void *data)
 Iterates the queue to check for an element. More...
 
void * qDeQueueIP (Queue *q)
 Dequeue an element from the front of the queue in place. More...
 
static bool qDeQueue (Queue *q, void *data)
 Dequeue an element from the front of the queue. More...
 
bool qRemoveBack (Queue *q)
 Delete element from the back for the queue. More...
 
static void * qFirst (Queue *q)
 Peek at the first element in the queue. More...
 
static void * qNext (Queue *q, void *ptr)
 Peek at the next element in the queue. More...
 
static bool qFull (Queue *q)
 Returns whether or not the queue is full. More...
 
static void qReset (Queue *q)
 Resets the queue. More...
 

Detailed Description

Queue is created in statically allocated memory.

Capacity and size can not be changed during runtime. Note that the queue definition is broken up in two parts, the descriptor and the actual queue.

To simplify creation of the queue use the Q_INIT macro.

Definition in file queue.h.

Macro Definition Documentation

#define Q_INIT (   NAME,
  ENTRY_SIZE,
  CAPACITY 
)
Value:
static uint8_t NAME ## Mem[ ( ENTRY_SIZE ) * ( CAPACITY ) ]; \
static const QueueDescr NAME ## Descr = { \
.memoryFirst = NAME ## Mem, \
.memoryLast = NAME ## Mem + ((CAPACITY) - 1) * ( ENTRY_SIZE ), \
.capacity = CAPACITY, \
.entrySize = ENTRY_SIZE \
}; \
static Queue NAME = { \
.descr = &NAME ## Descr, \
.length = 0, \
.readPtr = NAME ## Mem, \
.writePtr = NAME ## Mem \
};
const QueueDescr *const descr
pointer to the descriptor
Definition: queue.h:59
Queue state.
Definition: queue.h:58
void *const memoryFirst
first element pointer
Definition: queue.h:47
Queue descriptor.
Definition: queue.h:46

Convenience Macro, defines and inits queue.

Example of how to use it:

Q_INIT(myQueue, sizeof(MyStruct), 100);
void receive(MyStruct * myStr) {
qQueue(myQueue, myStr);
}

Must be used outside of any function scope.

Parameters
NAMEName of the queue pointer.
ENTRY_SIZESize in bytes of one element (use sizeof()).
CAPACITYMaximum number of elements in queue.

Definition at line 84 of file queue.h.

Function Documentation

bool qContains ( Queue q,
void *  data 
)

Iterates the queue to check for an element.

Searching is done by iterating though all elements and performance will drop with respect to the queue length.

Parameters
qThe queue.
dataThe element to check for.
Returns
True if that element was already in the queue, false if not.

Definition at line 55 of file queue.c.

static bool qDeQueue ( Queue q,
void *  data 
)
inlinestatic

Dequeue an element from the front of the queue.

The element will be written to the location pointed by data.

Parameters
qThe queue structure
dataWhere to write the dequeued element.
Returns
True if an element was dequeued. False if the queue is empty.

Definition at line 173 of file queue.h.

void* qDeQueueIP ( Queue q)

Dequeue an element from the front of the queue in place.

A pointer to the data will be given. Take care not to overwrite any more bytes than the size of the element.

The data is valid for as long as no elements are written to the queue.

Parameters
qThe queue.
Returns
NULL if the queue is empty, else a pointer to the location where you may read data.

Definition at line 33 of file queue.c.

static void* qFirst ( Queue q)
inlinestatic

Peek at the first element in the queue.

Returns a pointer to the first element in the queue, without dequeuing it. Note that the pointer is only valid for as long as the element is in the queue.

Use together with qNext to create an iterator.

See Also
qNext
Parameters
qThe queue structure.
Pointerto the first element in the queue, or NULL if the queue is empty.

Definition at line 209 of file queue.h.

static bool qFull ( Queue q)
inlinestatic

Returns whether or not the queue is full.

Return values
trueQueue is full
falseQueue is not full

Definition at line 249 of file queue.h.

static void* qNext ( Queue q,
void *  ptr 
)
inlinestatic

Peek at the next element in the queue.

Returns a pointer to the next element in the queue, without dequeuing it. Note that the pointer is only valid for as long as the element is in the queue.

Can be used together with qFirst to iterate though all elements of a queue. For example:

MyData * d = qFirst(q);
while (d != NULL)
{
doSomething(d);
d = qNext(q, d);
}
See Also
qFirst
Parameters
qThe queue structure.
Pointerto the net element in the queue, or NULL if you reached the end of the queue.

Definition at line 236 of file queue.h.

static bool qQueue ( Queue q,
void *  data 
)
inlinestatic

Queue data to the end of the queue.

The data is copied into the queue. The Data element must be the size as defined when creating the queue.

Parameters
qThe queue
dataThe data element to queue
Returns
True if it as added, false if the queue was full.

Definition at line 125 of file queue.h.

void* qQueueIP ( Queue q)

Queue data to the end of the queue in place.

You can write the element data to the returned pointer, but no not write any further than the size of the entry.

Parameters
qThe queue.
Returns
NULL if the queue is full, else a pointer to the location where you may write data.

Definition at line 18 of file queue.c.

bool qRemoveBack ( Queue q)

Delete element from the back for the queue.

Used for undo-ing if an operation could not be completed.

Return values
trueSuccess
falseQueue was empty.

Definition at line 45 of file queue.c.

static void qReset ( Queue q)
inlinestatic

Resets the queue.

After this call the queue is empty.

Definition at line 258 of file queue.h.