RKH
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
rkhrq.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  * 2015.10.24 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 __RKHRQ_H__
58 #define __RKHRQ_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_RQ_IS_EMPTY(q) \
82  (rbool_t)(rkh_rq_get_num((RKH_RQ_T *)(q)) == 0)
83 
84 /* -------------------------------- Constants ------------------------------ */
85 /* ------------------------------- Data types ------------------------------ */
94 #if RKH_CFG_RQ_SIZEOF_NELEM == 8
95 typedef rui8_t RKH_RQNE_T;
96 #elif RKH_CFG_RQ_SIZEOF_NELEM == 16
97 typedef rui16_t RKH_RQNE_T;
98 #elif RKH_CFG_RQ_SIZEOF_NELEM == 32
99 typedef rui32_t RKH_RQNE_T;
100 #else
101 typedef rui8_t RKH_RQNE_T;
102 #endif
103 
108 typedef enum
109 {
110  RKH_RQ_OK, RKH_RQ_EMPTY, RKH_RQ_FULL
111 } RKH_RQCODE_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_RQI_T;
132 
167 typedef struct RKH_RQ_T
168 {
173  RKH_RQNE_T nelems;
174 
179  RKH_RQNE_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_RQ_GET_LWMARK_EN == RKH_ENABLED
222  RKH_RQNE_T nmin;
223 #endif
224 
230 #if RKH_CFG_RQ_GET_INFO_EN == RKH_ENABLED
232 #endif
233 } RKH_RQ_T;
234 
235 /* -------------------------- External variables --------------------------- */
236 /* -------------------------- Function prototypes -------------------------- */
263 void rkh_rq_init(RKH_RQ_T *q, const void * *sstart, RKH_RQNE_T ssize,
264  const struct RKH_SMA_T *sma);
265 
281 rbool_t rkh_rq_is_full(RKH_RQ_T *q);
282 
295 RKH_RQNE_T rkh_rq_get_num(RKH_RQ_T *q);
296 
315 RKH_RQNE_T rkh_rq_get_lwm(RKH_RQ_T *q);
316 
326 void *rkh_rq_get(RKH_RQ_T *q);
327 
345 void rkh_rq_put_fifo(RKH_RQ_T *q, const void *pe);
346 
367 void rkh_rq_put_lifo(RKH_RQ_T *q, const void *pe);
368 
390 void rkh_rq_deplete(RKH_RQ_T *q);
391 
411 ruint rkh_rq_read(RKH_RQ_T *q, void *pe);
412 
436 void rkh_rq_get_info(RKH_RQ_T *q, RKH_RQI_T *pqi);
437 
450 void rkh_rq_clear_info(RKH_RQ_T *q);
451 
452 /* -------------------- External C language linkage end -------------------- */
453 #ifdef __cplusplus
454 }
455 #endif
456 
457 /* ------------------------------ Module end ------------------------------- */
458 #endif
459 
460 /* ------------------------------ End of file ------------------------------ */
void rkh_rq_put_lifo(RKH_RQ_T *q, const void *pe)
Puts an element on a queue in a LIFO manner. The element is queued by reference, not by copy...
rui8_t RKH_RQNE_T
This data type defines the maximum number of elements that any queue can contain. ...
Definition: rkhrq.h:95
void * rkh_rq_get(RKH_RQ_T *q)
Get and remove an element from a queue.
Describes the SMA (active object in UML).
Definition: rkhitl.h:2930
void rkh_rq_init(RKH_RQ_T *q, const void **sstart, RKH_RQNE_T ssize, const struct RKH_SMA_T *sma)
Initializes the previously allocated queue data structure RKH_RQ_T.
Defines the data structure used to maintain information about the queue.
Definition: rkhrq.h:167
const struct RKH_SMA_T * sma
Points to the associated SMA (a.k.a Active Object) that receives the enqueued events.
Definition: rkhrq.h:213
RKH user configurations.
void rkh_rq_deplete(RKH_RQ_T *q)
Depletes a queue. Empties the contents of the queue and eliminates all stored elements.
RKH_RQNE_T rkh_rq_get_num(RKH_RQ_T *q)
Returns the number of elements currently in the queue.
RKH_RQNE_T rkh_rq_get_lwm(RKH_RQ_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 ** pout
Points to the free next place in the storage area.
Definition: rkhrq.h:185
RKH_RQNE_T qty
Number of elements currently in the queue.
Definition: rkhrq.h:179
void rkh_rq_put_fifo(RKH_RQ_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 rkh_rq_clear_info(RKH_RQ_T *q)
Clear performance information for a particular queue.
RKH_RQNE_T nelems
Number of elements.
Definition: rkhrq.h:173
void ** pin
Points to the next place of queued item.
Definition: rkhrq.h:191
RKH_RQI_T rqi
Performance information. This member is optional, thus it could be eliminated in compile-time with RK...
Definition: rkhrq.h:231
RKH_RQNE_T nmin
Minimum number of free elements ever in this queue. The nmin low-watermark provides valuable empirica...
Definition: rkhrq.h:222
RKH_RQCODE_T
Return codes from queue operations.
Definition: rkhrq.h:108
const void ** pstart
Points to beginning of the queue storage area.
Definition: rkhrq.h:197
Defines the data structure into which the performance information for queues is stored.
Definition: rkhrq.h:124
ruint rkh_rq_read(RKH_RQ_T *q, void *pe)
Read an element from a queue without remove it.
void ** pend
Points to the end of the queue storage area.
Definition: rkhrq.h:203
rbool_t rkh_rq_is_full(RKH_RQ_T *q)
This function query the queue.
Defines the data types that uses RKH.
void rkh_rq_get_info(RKH_RQ_T *q, RKH_RQI_T *pqi)
Retrieves performance information for a particular queue.