RKH
rkhqueue.h
Go to the documentation of this file.
1 /*
2  * --------------------------------------------------------------------------
3  *
4  * Framework RKH
5  * -------------
6  *
7  * State-machine framework for reactive embedded systems
8  *
9  * Copyright (C) 2010 Leandro Francucci.
10  * All rights reserved. Protected by international copyright laws.
11  *
12  *
13  * RKH is free software: you can redistribute it and/or modify it under the
14  * terms of the GNU General Public License as published by the Free Software
15  * Foundation, either version 3 of the License, or (at your option) any
16  * later version.
17  *
18  * RKH is distributed in the hope that it will be useful, but WITHOUT ANY
19  * WARRANTY; without even the implied warranty of MERCHANTABILITY or
20  * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for
21  * more details.
22  *
23  * You should have received a copy of the GNU General Public License along
24  * with RKH, see copying.txt file.
25  *
26  * Contact information:
27  * RKH web site: http://sourceforge.net/projects/rkh-reactivesys/
28  * e-mail: francuccilea@gmail.com
29  * ---------------------------------------------------------------------------
30  */
31 
45 /* -------------------------- Development history -------------------------- */
46 /*
47  * 2017.17.05 LeFr v2.4.05 Initial version
48  */
49 
50 /* -------------------------------- Authors -------------------------------- */
51 /*
52  * LeFr Leandro Francucci francuccilea@gmail.com
53  */
54 
55 /* --------------------------------- Notes --------------------------------- */
56 /* --------------------------------- Module -------------------------------- */
57 #ifndef __RKHQUEUE_H__
58 #define __RKHQUEUE_H__
59 
60 /* ----------------------------- Include files ----------------------------- */
61 #include "rkhcfg.h"
62 #include "rkhtype.h"
63 
64 /* ---------------------- External C language linkage ---------------------- */
65 #ifdef __cplusplus
66 extern "C" {
67 #endif
68 
69 /* --------------------------------- Macros -------------------------------- */
81 #define RKH_QUEUE_IS_EMPTY(q) \
82  (rbool_t)(rkh_queue_get_num((RKH_QUEUE_T *)(q)) == 0)
83 
84 /* -------------------------------- Constants ------------------------------ */
85 /* ------------------------------- Data types ------------------------------ */
94 #if RKH_CFG_QUE_SIZEOF_NELEM == 8
95 typedef rui8_t RKH_QUENE_T;
96 #elif RKH_CFG_QUE_SIZEOF_NELEM == 16
97 typedef rui16_t RKH_QUENE_T;
98 #elif RKH_CFG_QUE_SIZEOF_NELEM == 32
99 typedef rui32_t RKH_QUENE_T;
100 #else
101 typedef rui8_t RKH_QUENE_T;
102 #endif
103 
108 typedef enum
109 {
110  RKH_QUE_OK, RKH_QUE_EMPTY, RKH_QUE_FULL
111 } RKH_QUECODE_T;
112 
124 typedef struct RKH_QINFO_T
125 {
126  rui16_t nputs; /* # of put requests */
127  rui16_t ngets; /* # of get requests */
128  rui16_t nreads; /* # of queue read requests */
129  rui16_t nempty; /* # of queue empty retrieves */
130  rui16_t nfull; /* # of queue full retrieves */
131 } RKH_QUEI_T;
132 
167 typedef struct RKH_QUEUE_T
168 {
173  RKH_QUENE_T nelems;
174 
179  RKH_QUENE_T qty;
180 
185  void **pout;
186 
191  void **pin;
192 
197  const void **pstart;
198 
203  void **pend;
204 
213  const struct RKH_SMA_T *sma;
214 
221 #if RKH_CFG_QUE_GET_LWMARK_EN == RKH_ENABLED
222  RKH_QUENE_T nmin;
223 #endif
224 
230 #if RKH_CFG_QUE_GET_INFO_EN == RKH_ENABLED
232 #endif
233 } RKH_QUEUE_T;
234 
235 /* -------------------------- External variables --------------------------- */
236 /* -------------------------- Function prototypes -------------------------- */
263 void rkh_queue_init(RKH_QUEUE_T *q, const void * *sstart, RKH_QUENE_T ssize,
264  void *sma);
265 
281 rbool_t rkh_queue_is_full(RKH_QUEUE_T *q);
282 
295 RKH_QUENE_T rkh_queue_get_num(RKH_QUEUE_T *q);
296 
315 RKH_QUENE_T rkh_queue_get_lwm(RKH_QUEUE_T *q);
316 
326 void *rkh_queue_get(RKH_QUEUE_T *q);
327 
345 void rkh_queue_put_fifo(RKH_QUEUE_T *q, const void *pe);
346 
367 void rkh_queue_put_lifo(RKH_QUEUE_T *q, const void *pe);
368 
391 
411 ruint rkh_queue_read(RKH_QUEUE_T *q, void *pe);
412 
437 
451 
452 /* -------------------- External C language linkage end -------------------- */
453 #ifdef __cplusplus
454 }
455 #endif
456 
457 /* ------------------------------ Module end ------------------------------- */
458 #endif
459 
460 /* ------------------------------ End of file ------------------------------ */
RKH_QUENE_T rkh_queue_get_num(RKH_QUEUE_T *q)
Returns the number of elements currently in the queue.
const void ** pstart
Points to beginning of the queue storage area.
Definition: rkhqueue.h:197
Describes the SMA (active object in UML).
Definition: rkhsma.h:748
rui8_t RKH_QUENE_T
This data type defines the maximum number of elements that any queue can contain. ...
Definition: rkhqueue.h:95
RKH_QUENE_T rkh_queue_get_lwm(RKH_QUEUE_T *q)
This function returns the lowest number of free elements ever present in the pool. This number provides valuable empirical data for proper sizing of the queue.
void rkh_queue_init(RKH_QUEUE_T *q, const void **sstart, RKH_QUENE_T ssize, void *sma)
Initializes the previously allocated queue data structure RKH_QUEUE_T.
RKH_QUENE_T nmin
Minimum number of free elements ever in this queue. The nmin low-watermark provides valuable empirica...
Definition: rkhqueue.h:222
Defines the data structure used to maintain information about the queue.
Definition: rkhqueue.h:167
RKH_QUENE_T qty
Number of elements currently in the queue.
Definition: rkhqueue.h:179
rbool_t rkh_queue_is_full(RKH_QUEUE_T *q)
This function query the queue.
RKH user configurations.
Defines the data structure into which the performance information for queues is stored.
Definition: rkhqueue.h:124
const struct RKH_SMA_T * sma
Points to the associated SMA (a.k.a Active Object) that receives the enqueued events.
Definition: rkhqueue.h:213
void rkh_queue_clear_info(RKH_QUEUE_T *q)
Clear performance information for a particular queue.
RKH_QUECODE_T
Return codes from queue operations.
Definition: rkhqueue.h:108
void rkh_queue_get_info(RKH_QUEUE_T *q, RKH_QUEI_T *pqi)
Retrieves performance information for a particular queue.
void rkh_queue_deplete(RKH_QUEUE_T *q)
Depletes a queue. Empties the contents of the queue and eliminates all stored elements.
RKH_QUENE_T nelems
Number of elements.
Definition: rkhqueue.h:173
RKH_QUEI_T rqi
Performance information. This member is optional, thus it could be eliminated in compile-time with RK...
Definition: rkhqueue.h:231
void * rkh_queue_get(RKH_QUEUE_T *q)
Get and remove an element from a queue.
void rkh_queue_put_fifo(RKH_QUEUE_T *q, const void *pe)
Puts an element on a queue in a FIFO manner. The element is queued by reference, not by copy...
void ** pend
Points to the end of the queue storage area.
Definition: rkhqueue.h:203
ruint rkh_queue_read(RKH_QUEUE_T *q, void *pe)
Read an element from a queue without remove it.
void rkh_queue_put_lifo(RKH_QUEUE_T *q, const void *pe)
Puts an element on a queue in a LIFO manner. The element is queued by reference, not by copy...
void ** pout
Points to the free next place in the storage area.
Definition: rkhqueue.h:185
void ** pin
Points to the next place of queued item.
Definition: rkhqueue.h:191
Defines the data types that uses RKH.