1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
|
/*******************************************************************************
* Copyright (C) ST-Ericsson SA 2011
* License terms: 3-clause BSD license
******************************************************************************/
#ifndef _R_QUEUE_H_
#define _R_QUEUE_H_
/**
* @addtogroup ldr_utilities
* @{
* @addtogroup queue
* @{
* Implementation of FIFO queue.
* Functions which names begin with Do_Fifo_* are non-reentrant.
* Functions which names begin with Do_RFifo_* are reentrant.
* Functions that are not interrupt safe are faster than the interrupt safe
* functions.
*
* @remark None of the functions check the sanity of the input parameters.
*/
/*******************************************************************************
* Includes
******************************************************************************/
#include "t_queue.h"
#include "error_codes.h"
/*******************************************************************************
* Declaration of functions
******************************************************************************/
/**
* @brief Creates a queue.
*
* @param [in] Object_p Pointer to LCM instance context.
* @param [out] Queue_pp After execution points to the allocated space
* for the queue.
* @param [in] MaxLength The maximum number of entries in the queue.
* @param [in] DestroyElement Pointer to user defined function that
* deallocates resources allocated for the
* elements in the queue. NULL if there is no need
* for deallocating resource.
*/
void Do_Fifo_Create(void *Object_p,
void **const Queue_pp,
const uint32 MaxLength,
void (*DestroyElement)(void *Element_p));
/**
* @brief Releases any resources associated with the specified queue structure.
*
* @param [in] Object_p Pointer to LCM instance context.
* @param [in,out] Queue_pp Pointer to the queue structure to destroy.
*/
void Do_Fifo_Destroy(void *Object_p, void **const Queue_pp);
/**
* @brief Enqueueing of pointers.
*
* @note Enqueueing and dequeueing are mutually reentrant, and all functions are
* reentrant across different queues, but enqueueing on the same queue is
* not necessarily reentrant.
*
* @param [in] Object_p Pointer to LCM instance context.
* @param [in] Queue_p The queue to append to.
* @param [in] Value_p The value to enqueue.
* @return E_SUCCESS - The function completed successfully.
*
* @return E_FAILED_TO_STORE_IN_FIFO - Failed to store data in fifo.
*/
ErrorCode_e Do_Fifo_Enqueue(void *Object_p,
void *const Queue_p,
void *const Value_p);
/**
* @brief Dequeueing of pointers.
*
* Dequeueing function of a reentrant, interrupt-safe FIFO queue.
*
* @note Enqueueing and dequeueing are mutually reentrant, and all functions are
* reentrant across different queues, but dequeueing on the same queue is
* not necessarily reentrant.
*
* @param [in] Object_p Pointer to LCM instance context.
* @param [in] Queue_p The queue to take an item from.
*
* @return The first pointer in the queue on success or NULL if
* the queue is empty. Note that an enqueued NULL
* pointer will be de-queued as a NULL pointer.
*/
void *Do_Fifo_Dequeue(void *Object_p, void *const Queue_p);
/**
* @brief Registers an event listener for the specified queue.
*
* @note Only one listener per queue and event type is allowed.
* @note A function invocation does not guarantee that the state of the queue is
* the same as the end-transition state, only that such a transition has
* happened.
*
* @param [in] Object_p Pointer to LCM instance context.
* @param [in] Queue_p The queue for which to register a callback.
* @param [in] Type The type of event to register the callback for.
* A value of EMPTY indicates that the specified callback
* function should be called each time queue has
* transitioned from a non-empty state to an empty state.
* A value of NONEMPTY indicates that the callback func.
* should be called each time the queue has transitioned
* from an empty to a non-empty state.
* @param [in] Callback The function to call when the specified event occurs
* or NULL to unregister a previously registered function.
* @param [in] Param_p Parameter to pass to the callback function.
* @return The previously registered callback function for this
* type.
* @return NULL If no callback was previously registered.
*/
QueueCallback_fn Do_Fifo_SetCallback(void *Object_p, void *const Queue_p,
const QueueCallbackType_e Type,
const QueueCallback_fn Callback,
void *const Param_p);
/**
* @brief Determines the empty-status of the queue.
*
* @param [in] Object_p Pointer to LCM instance context.
* @param [in] Queue_p The queue to inspect.
* @return TRUE If Fifo is empty or
* @return FALSE If Fifo is not empty.
*/
boolean Do_Fifo_IsEmpty(void *Object_p, const void *const Queue_p);
/**
* @brief Checks if the provided element is member of the fifo.
*
* @param [in] Object_p Pointer to LCM instance context.
* @param [in] Queue_p The queue to search for element.
* @param [in] Value_p The element to be searched in the queue.
* @param [in] Match Function that checks if two elements match.
* @retval TRUE If the element is member of the fifo.
* @retval FALSE If the element is not member of the fifo.
*/
boolean Do_Fifo_IsMember(void *Object_p,
const void *const Queue_p,
void *Value_p,
boolean(*Match)(void *Value1_p, void *Value2_p));
/**
* @brief Returns the number of elements in the queue.
*
* @param [in] Object_p Pointer to LCM instance context.
* @param [in] Queue_p Pointer to the queue.
* @return Number of elements in the queue.
*/
int Do_Fifo_GetNrOfElements(void *Object_p, const void *const Queue_p);
/**
* @brief Creates a queue.
*
* @param [in] Object_p Pointer to LCM instance context.
* @param [out] Queue_pp After execution points to the allocated
* space for the queue.
* @param [in] MaxLength The maximum number of entries in the queue.
* @param [in] DestroyElement Pointer to user defined function that deallocates
* resources allocated for the elements in the
* queue. NULL if there is no need for deallocating
* resource.
*/
void Do_RFifo_Create(void *Object_p,
void **const Queue_pp,
const uint32 MaxLength,
void (*DestroyElement)(void *Element_p));
/**
* @brief Releases any resources associated with the specified queue structure.
*
* @param [in] Object_p Pointer to LCM instance context.
* @param [in,out] Queue_pp Pointer to the queue structure to destroy.
*/
void Do_RFifo_Destroy(void *Object_p, void **const Queue_pp);
/**
* @brief Enqueueing of pointers.
*
* Enqueueing function of a re-entrant, interrupt-safe FIFO queue.
*
* @param [in] Object_p Pointer to LCM instance context.
* @param [in] Queue_p The queue to append to.
* @param [in] Value_p The value to enqueue.
* @return E_SUCCESS The function completed successfully.
*
* @return E_FAILED_TO_STORE_IN_FIFO - Faliled to store data in fifo.
*/
ErrorCode_e Do_RFifo_Enqueue(void *Object_p,
void *const Queue_p,
void *const Value_p);
/**
* @brief Dequeueing of pointers.
*
* Dequeueing function of a reentrant, interrupt-safe FIFO queue.
*
* @param [in] Object_p Pointer to LCM instance context.
* @param [in] Queue_p The queue to take an item from.
* @return The first pointer in the queue on success or NULL if
* the queue is empty. Note that an enqueued NULL-pointer
* will be de - queued as a NULL pointer.
*/
void *Do_RFifo_Dequeue(void *Object_p, void *const Queue_p);
/**
* @brief Registers an event listener for the specified queue.
*
* @note Only one listener per queue and event type is allowed.
* @note A function invocation does not guarantee that the state of the queue is
* the same as the end-transition state, only that such a transition has
* happened.
*
* @param [in] Object_p Pointer to LCM instance context.
* @param [in] Queue_p The queue for which to register a callback.
* @param [in] Type The type of event to register the callback for.
* - A value of EMPTY indicates that the specified
* callback function should be called each time queue has
* transitioned from a non-empty state to an empty state.
* - A value of NONEMPTY indicates that the callback
* function should be called each time the queue has
* transitioned from an empty to a non-empty state.
* @param [in] Callback The function to call when the specified event occurs
* or NULL to unregister a previously registered functions.
* @param [in] Param_p Parameter to pass to the callback function.
* @return The previously registered callback function for this
* type.
* @return NULL If no callback was previously registered.
*/
QueueCallback_fn Do_RFifo_SetCallback(void *Object_p, void *const Queue_p,
const QueueCallbackType_e Type,
const QueueCallback_fn Callback,
void *const Param_p);
/**
* @brief Determines the empty-status of the queue.
*
* @param [in] Object_p Pointer to LCM instance context.
* @param [in] Queue_p The queue to inspect.
* @retval TRUE If Fifo is empty or FALSE if is not empty.
*/
boolean Do_RFifo_IsEmpty(void *Object_p, const void *const Queue_p);
/**
* @brief Checks if the provided element is member of the fifo.
*
* @param [in] Object_p Pointer to LCM instance context.
* @param [in] Queue_p The queue to search for element.
* @param [in] Value_p The element to be searched in the queue.
* @param [in] Match Function that checks if two elements match.
* @retval TRUE If the element is member of the fifo.
* @retval FALSE If the element is not member of the fifo.
*/
boolean Do_RFifo_IsMember(void *Object_p,
const void *const Queue_p,
void *Value_p,
boolean(*Match)(void *Value1_p, void *Value2_p));
/**
* @brief Returns the number of elements in the queue.
*
* @param [in] Object_p Pointer to LCM instance context.
* @param [in] Queue_p Pointer to the queue.
* @return Number of elements in the queue.
*/
int Do_RFifo_GetNrOfElements(void *Object_p, const void *const Queue_p);
/** @} */
/** @} */
#endif /*_R_QUEUE_H_*/
|
