KM3NeT CLB  2.0
KM3NeT CLB v2 Embedded Software
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
varqueue.h
Go to the documentation of this file.
1 /*
2  * KM3NeT CLB v2 Firmware
3  *
4  * Copyright 2013 KM3NeT Collaboration
5  *
6  * All Rights Reserved.
7  *
8  * varqueue.h
9  *
10  * Created on: 24 mei 2013
11  * Author: Vincent van Beveren
12  */
13 
14 
15 #ifndef VARQUEUE_H_
16 #define VARQUEUE_H_
17 
18 /**
19  * @file
20  *
21  * @ingroup collections
22  *
23  * A variable length queue implementation. Queue is currently limited to 16 bits, e.g. it can not
24  * be larger than 64K.
25  *
26  * To create a queue you will first need to initialize the a byte array, and configure the
27  * VarQueue structure, like this:
28  *
29  * \code
30  * static uint8_t _myQueueMem[1024];
31  * static VarQueue _myQueue = {
32  * .mem = _myQueueMem,
33  * .size = sizeof(_myQueueMem),
34  * }
35  * \endcode
36  *
37  * Note that the actual capacity of the queue is less, since each element requires a 2 byte header.
38  * So, you can store one 1022 sized element in the queue above, or two 510 sized elements, etc...
39  *
40  * The code above is also written down my the VQ_INIT function, which you may also use.
41  */
42 
43 #include <stdint.h>
44 #include <stdbool.h>
45 
46 /**
47  * Variable length queue structure.
48  * Use VQ_INIT as a convenience function.
49  */
50 typedef struct
51 {
52  uint8_t * const mem; //!< Pointer to memory
53  const uint16_t size; //!< Size of the memory
54  uint16_t used; //!< bytes used
55  uint16_t read; //!< read index
56  uint16_t write; //!< write index
57 } VarQueue;
58 
59 /**
60  * Initializes the variable length queue.
61  *
62  * @param NAME Variable name of the queue structure. A byte array named NAME_mem will be
63  * created as heap.
64  * @param SIZE The size of the queue in bytes.
65  */
66 #define VQ_INIT(NAME, SIZE) \
67  static uint8_t NAME ## _mem[SIZE];\
68  static VarQueue NAME = { \
69  .mem = NAME ## _mem, \
70  .size = SIZE, \
71  .used = 0, \
72  .read = 0, \
73  .write = 0 \
74  }
75 
76 
77 
78 /**
79  * Queues an element on the queue.
80  *
81  * @param vq Pointer to the variable queue structure
82  * @param length length of the element in the buffer
83  * @param buffer The buffer to copy the element from
84  *
85  * @retval true Element was queued.
86  * false The element was not queued (out of space?).
87  */
88 bool vqQueue(VarQueue * const vq, uint16_t length, uint8_t * buffer);
89 
90 /**
91  * DeQueues an element from the queue.
92  *
93  * @param vq Pointer to the queue structure.
94  * @param length Pointer containing the length of the buffer. On return this will be filled with
95  * the actual length of the element.
96  * @param buffer The buffer to copy into.
97  *
98  * @retval true Element was dequeued and is now in the buffer
99  * false Element was not dequeued, either the length of the buffer is not sufficient
100  * or there is no element in the queue.
101  */
102 bool vqDeQueue(VarQueue * const vq, uint16_t * length, uint8_t * buffer);
103 
104 /**
105  * Peeks an element from the queue. The actual element is not removed from the queue.
106  *
107  * @param vq Pointer to the queue structure.
108  * @param length Pointer containing the length of the buffer. On return this will be filled with
109  * the actual length of the element.
110  * @param buffer The buffer to copy into.
111  *
112  * @retval true Element was dequeued and is now in the buffer
113  * false Element was not dequeued, either the length of the buffer is not sufficient
114  */
115 bool vqPeek(VarQueue * const vq, uint16_t * length, uint8_t * buffer);
116 
117 
118 /**
119  * Removes the first element from the queue (not the last).
120  *
121  * @param vq The pointer to the queue structure.
122  * @retval true Element was removed.
123  * false Element was not removed because the queue was already empty.
124  */
125 bool vqRemove(VarQueue * const vq);
126 
127 /**
128  * Returns the lenght of the next element to dequeue.
129  *
130  * @param vq The pointer to the queue structure.
131  * @return Either the size of the next element, or 0 if there are no elements on the queue.
132  */
133 uint16_t vqDeQueueLength(VarQueue * const vq);
134 
135 /**
136  * Returns the number of bytes free for the next element. The header is already substracted from
137  * this number, so this is really the number of bytes you can still put into the queue.
138  *
139  * @param vq The pointer to the queue structure.
140  * @return Number of bytes free for the next element.
141  */
142 uint16_t vqFree(VarQueue * const vq);
143 
144 
145 /**
146  * Resets the queue, such that is is empty.
147  *
148  * @param vq Pointer the the variable queue element.
149  */
150 static inline void vqReset(VarQueue * const vq)
151 {
152  vq->read = 0;
153  vq->write = 0;
154  vq->used = 0;
155 }
156 
157 #endif /* VARQUEUE_H_ */
bool vqDeQueue(VarQueue *const vq, uint16_t *length, uint8_t *buffer)
DeQueues an element from the queue.
Definition: varqueue.c:50
bool vqQueue(VarQueue *const vq, uint16_t length, uint8_t *buffer)
Queues an element on the queue.
Definition: varqueue.c:24
uint8_t *const mem
Pointer to memory.
Definition: varqueue.h:52
static void vqReset(VarQueue *const vq)
Resets the queue, such that is is empty.
Definition: varqueue.h:150
Variable length queue structure.
Definition: varqueue.h:50
uint16_t vqDeQueueLength(VarQueue *const vq)
Returns the lenght of the next element to dequeue.
Definition: varqueue.c:108
bool vqPeek(VarQueue *const vq, uint16_t *length, uint8_t *buffer)
Peeks an element from the queue.
const uint16_t size
Size of the memory.
Definition: varqueue.h:53
uint16_t read
read index
Definition: varqueue.h:55
uint16_t used
bytes used
Definition: varqueue.h:54
uint16_t vqFree(VarQueue *const vq)
Returns the number of bytes free for the next element.
Definition: varqueue.c:114
uint16_t write
write index
Definition: varqueue.h:56
bool vqRemove(VarQueue *const vq)
Removes the first element from the queue (not the last).
Definition: varqueue.c:98