SuperTinyKernel™ RTOS 1.08.x
Lightweight, high-performance, deterministic, bare-metal C++ RTOS for resource-constrained embedded systems. MIT Open Source License.
Loading...
Searching...
No Matches
Queue
cy_rslt_t cy_rtos_queue_init (cy_queue_t *queue, size_t length, size_t itemsize)
cy_rslt_t cy_rtos_queue_put (const cy_queue_t *queue, const void *item_ptr, cy_time_t timeout_ms)
cy_rslt_t cy_rtos_queue_get (const cy_queue_t *queue, void *item_ptr, cy_time_t timeout_ms)
cy_rslt_t cy_rtos_queue_count (const cy_queue_t *queue, size_t *num_waiting)
cy_rslt_t cy_rtos_queue_space (const cy_queue_t *queue, size_t *num_spaces)
cy_rslt_t cy_rtos_queue_reset (const cy_queue_t *queue)
cy_rslt_t cy_rtos_queue_deinit (cy_queue_t *queue)
#define CY_RTOS_QUEUE_FULL   CY_RSLT_CREATE(CY_RSLT_TYPE_ERROR, CY_RSLT_MODULE_ABSTRACTION_OS, 3)
#define CY_RTOS_QUEUE_EMPTY   CY_RSLT_CREATE(CY_RSLT_TYPE_ERROR, CY_RSLT_MODULE_ABSTRACTION_OS, 4)
#define cy_rtos_init_queue(queue, length, itemsize)
#define cy_rtos_put_queue(queue, item_ptr, timeout_ms, in_isr)
#define cy_rtos_get_queue(queue, item_ptr, timeout_ms, in_isr)
#define cy_rtos_count_queue(queue, num_waiting)
#define cy_rtos_space_queue(queue, num_spaces)
#define cy_rtos_reset_queue(queue)
#define cy_rtos_deinit_queue(queue)

Detailed Description

APIs for creating and working with Queues.

Macro Definition Documentation

◆ cy_rtos_count_queue

#define cy_rtos_count_queue ( queue,
num_waiting )
Value:
cy_rtos_queue_count(queue, num_waiting)
cy_rslt_t cy_rtos_queue_count(const cy_queue_t *queue, size_t *num_waiting)

Return the number of items in the queue.

This function returns the number of items currently in the queue.

Parameters
[in]queuePointer to the queue handle
[out]num_waitingPointer to the return count
Returns
The status of the count request. Same across all RTOS kernels [CY_RSLT_SUCCESS, CY_RTOS_BAD_PARAM].
Specific for kernel:
  • THREADX: [CY_RTOS_GENERAL_ERROR].

Definition at line 1522 of file cyabs_rtos.h.

1522#define cy_rtos_count_queue(queue, num_waiting) \
1523 cy_rtos_queue_count(queue, num_waiting)

◆ cy_rtos_deinit_queue

#define cy_rtos_deinit_queue ( queue)
Value:
cy_rslt_t cy_rtos_queue_deinit(cy_queue_t *queue)

Deinitialize the queue handle.

This function de-initializes the queue and returns all resources used by the queue.

Parameters
[in]queuePointer to the queue handle
Returns
The status of the deinit request. Same across all RTOS kernels [CY_RSLT_SUCCESS, CY_RTOS_BAD_PARAM].
Specific for kernel:

Definition at line 1569 of file cyabs_rtos.h.

1569#define cy_rtos_deinit_queue(queue) \
1570 cy_rtos_queue_deinit(queue)

◆ cy_rtos_get_queue

#define cy_rtos_get_queue ( queue,
item_ptr,
timeout_ms,
in_isr )
Value:
cy_rtos_queue_get(queue, item_ptr, timeout_ms)
cy_rslt_t cy_rtos_queue_get(const cy_queue_t *queue, void *item_ptr, cy_time_t timeout_ms)

Gets an item in a queue.

This function gets an item from the queue. The item is copied out of the queue into the memory provide by item_ptr. This space must be large enough to hold a queue entry as defined when the queue was initialized.

Note
If in_isr is true, timeout_ms must be zero.
A value of CY_RTOS_NEVER_TIMEOUT assigned to timeout_ms will cause the task to block indefinitely (without a timeout).
Parameters
[in]queuePointer to the queue handle
[in]item_ptrPointer to the memory for the item from the queue
[in]timeout_msThe time to wait to get an item from the queue
[in]in_isrIf true this is being called from within an ISR
Returns
The status of the get request. Same across all RTOS kernels [CY_RSLT_SUCCESS, CY_RTOS_BAD_PARAM, CY_RTOS_GENERAL_ERROR].
Specific for kernel:

Definition at line 1507 of file cyabs_rtos.h.

1507#define cy_rtos_get_queue(queue, item_ptr, timeout_ms, in_isr) \
1508 cy_rtos_queue_get(queue, item_ptr, timeout_ms)

◆ cy_rtos_init_queue

#define cy_rtos_init_queue ( queue,
length,
itemsize )
Value:
cy_rtos_queue_init(queue, length, itemsize)
cy_rslt_t cy_rtos_queue_init(cy_queue_t *queue, size_t length, size_t itemsize)

Create a queue.

This is a queue of data where entries are placed on the back of the queue and removed from the front of the queue.

Parameters
[out]queuePointer to the queue handle
[in]lengthThe maximum length of the queue in items
[in]itemsizeThe size of each item in the queue.
Returns
The status of the init request. Same across all RTOS kernels [CY_RSLT_SUCCESS, CY_RTOS_BAD_PARAM, CY_RTOS_NO_MEMORY].
Specific for kernel:

Definition at line 1461 of file cyabs_rtos.h.

1461#define cy_rtos_init_queue(queue, length, itemsize) \
1462 cy_rtos_queue_init(queue, length, itemsize)

◆ cy_rtos_put_queue

#define cy_rtos_put_queue ( queue,
item_ptr,
timeout_ms,
in_isr )
Value:
cy_rtos_queue_put(queue, item_ptr, timeout_ms)
cy_rslt_t cy_rtos_queue_put(const cy_queue_t *queue, const void *item_ptr, cy_time_t timeout_ms)

Put an item in a queue.

This function puts an item in the queue. The item is copied into the queue using a memory copy and the data pointed to by item_ptr is no longer referenced once the call returns.

Note
If in_isr is true, timeout_ms must be zero.
Parameters
[in]queuePointer to the queue handle
[in]item_ptrPointer to the item to place in the queue
[in]timeout_msThe time to wait to place the item in the queue
[in]in_isrIf true this is being called from within and ISR
Returns
The status of the put request. Same across all RTOS kernels [CY_RSLT_SUCCESS, CY_RTOS_BAD_PARAM, CY_RTOS_GENERAL_ERROR].
Specific for kernel:

Definition at line 1483 of file cyabs_rtos.h.

1483#define cy_rtos_put_queue(queue, item_ptr, timeout_ms, in_isr) \
1484 cy_rtos_queue_put(queue, item_ptr, timeout_ms)

◆ CY_RTOS_QUEUE_EMPTY

#define CY_RTOS_QUEUE_EMPTY   CY_RSLT_CREATE(CY_RSLT_TYPE_ERROR, CY_RSLT_MODULE_ABSTRACTION_OS, 4)

The Queue is empty and has nothing to remove

Definition at line 117 of file cyabs_rtos.h.

117#define CY_RTOS_QUEUE_EMPTY \
118 CY_RSLT_CREATE(CY_RSLT_TYPE_ERROR, CY_RSLT_MODULE_ABSTRACTION_OS, 4)

◆ CY_RTOS_QUEUE_FULL

#define CY_RTOS_QUEUE_FULL   CY_RSLT_CREATE(CY_RSLT_TYPE_ERROR, CY_RSLT_MODULE_ABSTRACTION_OS, 3)

The Queue is already full and can't accept any more items at this time

Definition at line 114 of file cyabs_rtos.h.

114#define CY_RTOS_QUEUE_FULL \
115 CY_RSLT_CREATE(CY_RSLT_TYPE_ERROR, CY_RSLT_MODULE_ABSTRACTION_OS, 3)

Referenced by cy_rtos_queue_put().

◆ cy_rtos_reset_queue

#define cy_rtos_reset_queue ( queue)
Value:
cy_rslt_t cy_rtos_queue_reset(const cy_queue_t *queue)

Reset the queue.

This function sets the queue to empty.

Parameters
[in]queuepointer to the queue handle
Returns
The status of the reset request. Same across all RTOS kernels [CY_RSLT_SUCCESS, CY_RTOS_BAD_PARAM, CY_RTOS_GENERAL_ERROR].
Specific for kernel:

Definition at line 1553 of file cyabs_rtos.h.

1553#define cy_rtos_reset_queue(queue) \
1554 cy_rtos_queue_reset(queue)

◆ cy_rtos_space_queue

#define cy_rtos_space_queue ( queue,
num_spaces )
Value:
cy_rtos_queue_space(queue, num_spaces)
cy_rslt_t cy_rtos_queue_space(const cy_queue_t *queue, size_t *num_spaces)

Return the amount of empty space in the queue.

This function returns the amount of empty space in the queue. For instance, if the queue was created with 10 entries max and there are currently 2 entries in the queue, this will return 8.

Parameters
[in]queuePointer to the queue handle
[out]num_spacesPointer to the return count.
Returns
The status of the space request. Same across all RTOS kernels [CY_RSLT_SUCCESS, CY_RTOS_BAD_PARAM].
Specific for kernel:
  • THREADX: [CY_RTOS_GENERAL_ERROR].

Definition at line 1539 of file cyabs_rtos.h.

1539#define cy_rtos_space_queue(queue, num_spaces) \
1540 cy_rtos_queue_space(queue, num_spaces)

Function Documentation

◆ cy_rtos_queue_count()

cy_rslt_t cy_rtos_queue_count ( const cy_queue_t * queue,
size_t * num_waiting )

Return the number of items in the queue.

This function returns the number of items currently in the queue.

Parameters
[in]queuePointer to the queue handle
[out]num_waitingPointer to the return count
Returns
The status of the count request. Same across all RTOS kernels [CY_RSLT_SUCCESS, CY_RTOS_BAD_PARAM].
Specific for kernel:
  • THREADX: [CY_RTOS_GENERAL_ERROR].

Definition at line 1270 of file cyabs_rtos_stk.cpp.

1271{
1272 if (!IsValid(queue) || (num_waiting == nullptr))
1273 {
1274 return CY_RTOS_BAD_PARAM;
1275 }
1276
1277 *num_waiting = QueueOf(queue)->GetCount();
1278
1279 return CY_RSLT_SUCCESS;
1280}
#define CY_RTOS_BAD_PARAM
Definition cyabs_rtos.h:96

References CY_RTOS_BAD_PARAM.

◆ cy_rtos_queue_deinit()

cy_rslt_t cy_rtos_queue_deinit ( cy_queue_t * queue)

Deinitialize the queue handle.

This function de-initializes the queue and returns all resources used by the queue.

Parameters
[in]queuePointer to the queue handle
Returns
The status of the deinit request. Same across all RTOS kernels [CY_RSLT_SUCCESS, CY_RTOS_BAD_PARAM].
Specific for kernel:

Definition at line 1306 of file cyabs_rtos_stk.cpp.

1307{
1308 if (!IsValid(queue))
1309 {
1310 return CY_RTOS_BAD_PARAM;
1311 }
1312
1313 queue->id = 0U;
1314 QueueOf(queue)->~MessageQueue(); // STK contract: no thread may be waiting on it
1315 CY_RTOS_STK_FREE(queue->buffer);
1316 queue->buffer = nullptr;
1317
1318 return CY_RSLT_SUCCESS;
1319}
#define CY_RTOS_STK_FREE(ptr)
uint8_t * buffer

References cy_queue_t::buffer, CY_RTOS_BAD_PARAM, CY_RTOS_STK_FREE, and cy_queue_t::id.

◆ cy_rtos_queue_get()

cy_rslt_t cy_rtos_queue_get ( const cy_queue_t * queue,
void * item_ptr,
cy_time_t timeout_ms )

Gets an item in a queue.

This function gets an item from the queue. The item is copied out of the queue into the memory provide by item_ptr. This space must be large enough to hold a queue entry as defined when the queue was initialized.

Note
If in_isr is true, timeout_ms must be zero.
Parameters
[in]queuePointer to the queue handle
[in]item_ptrPointer to the memory for the item from the queue
[in]timeout_msThe time to wait to get an item from the queue
Returns
The status of the get request. Same across all RTOS kernels [CY_RSLT_SUCCESS, CY_RTOS_BAD_PARAM, CY_RTOS_GENERAL_ERROR].
Specific for kernel:

Definition at line 1252 of file cyabs_rtos_stk.cpp.

1253{
1254 if (!IsValid(queue) || (item_ptr == nullptr))
1255 {
1256 return CY_RTOS_BAD_PARAM;
1257 }
1258
1259 stk::Timeout timeout;
1260 cy_rslt_t error = CY_RSLT_SUCCESS;
1261
1262 if (!PrepareTimeout(timeout_ms, timeout, error))
1263 {
1264 return error;
1265 }
1266
1267 return WaitResultToCy(QueueOf(queue)->GetEx(item_ptr, timeout), CY_RTOS_TIMEOUT);
1268}
#define CY_RTOS_TIMEOUT
Definition cyabs_rtos.h:87
int32_t Timeout
Timeout time (ticks).
Definition stk_common.h:216

References CY_RTOS_BAD_PARAM, and CY_RTOS_TIMEOUT.

◆ cy_rtos_queue_init()

cy_rslt_t cy_rtos_queue_init ( cy_queue_t * queue,
size_t length,
size_t itemsize )

Create a queue.

This is a queue of data where entries are placed on the back of the queue and removed from the front of the queue.

Parameters
[out]queuePointer to the queue handle
[in]lengthThe maximum length of the queue in items
[in]itemsizeThe size of each item in the queue.
Returns
The status of the init request. Same across all RTOS kernels [CY_RSLT_SUCCESS, CY_RTOS_BAD_PARAM, CY_RTOS_NO_MEMORY].
Specific for kernel:

Definition at line 1212 of file cyabs_rtos_stk.cpp.

1213{
1214 if ((queue == nullptr) || (length == 0U) || (itemsize == 0U) ||
1215 (length > stk::sync::MessageQueue::CAPACITY_MAX) || (itemsize > (SIZE_MAX / length)))
1216 {
1217 return CY_RTOS_BAD_PARAM;
1218 }
1219
1220 uint8_t *const buffer = static_cast<uint8_t *>(CY_RTOS_STK_MALLOC(length * itemsize));
1221 if (buffer == nullptr)
1222 {
1223 return CY_RTOS_NO_MEMORY;
1224 }
1225
1226 (void)new (static_cast<void *>(queue->storage)) stk::sync::MessageQueue(buffer, length, itemsize);
1227 queue->buffer = buffer;
1228 queue->id = ID_QUEUE;
1229
1230 return CY_RSLT_SUCCESS;
1231}
#define CY_RTOS_STK_MALLOC(size)
#define CY_RTOS_NO_MEMORY
Definition cyabs_rtos.h:90
Fixed-capacity, fixed-message-size FIFO queue for inter-task communication.
static const size_t CAPACITY_MAX
Max capacity supported (number of messages).
uint64_t storage[(21U)]

References cy_queue_t::buffer, stk::sync::MessageQueue::CAPACITY_MAX, CY_RTOS_BAD_PARAM, CY_RTOS_NO_MEMORY, CY_RTOS_STK_MALLOC, cy_queue_t::id, and cy_queue_t::storage.

◆ cy_rtos_queue_put()

cy_rslt_t cy_rtos_queue_put ( const cy_queue_t * queue,
const void * item_ptr,
cy_time_t timeout_ms )

Put an item in a queue.

This function puts an item in the queue. The item is copied into the queue using a memory copy and the data pointed to by item_ptr is no longer referenced once the call returns.

Note
If in_isr is true, timeout_ms must be zero.
Parameters
[in]queuePointer to the queue handle
[in]item_ptrPointer to the item to place in the queue
[in]timeout_msThe time to wait to place the item in the queue
Returns
The status of the put request. Same across all RTOS kernels [CY_RSLT_SUCCESS, CY_RTOS_BAD_PARAM, CY_RTOS_GENERAL_ERROR].
Specific for kernel:

Definition at line 1234 of file cyabs_rtos_stk.cpp.

1235{
1236 if (!IsValid(queue) || (item_ptr == nullptr))
1237 {
1238 return CY_RTOS_BAD_PARAM;
1239 }
1240
1241 stk::Timeout timeout;
1242 cy_rslt_t error = CY_RSLT_SUCCESS;
1243
1244 if (!PrepareTimeout(timeout_ms, timeout, error))
1245 {
1246 return error;
1247 }
1248
1249 return WaitResultToCy(QueueOf(queue)->PutEx(item_ptr, timeout), CY_RTOS_QUEUE_FULL);
1250}
#define CY_RTOS_QUEUE_FULL
Definition cyabs_rtos.h:114

References CY_RTOS_BAD_PARAM, and CY_RTOS_QUEUE_FULL.

◆ cy_rtos_queue_reset()

cy_rslt_t cy_rtos_queue_reset ( const cy_queue_t * queue)

Reset the queue.

This function sets the queue to empty.

Parameters
[in]queuepointer to the queue handle
Returns
The status of the reset request. Same across all RTOS kernels [CY_RSLT_SUCCESS, CY_RTOS_BAD_PARAM, CY_RTOS_GENERAL_ERROR].
Specific for kernel:

Definition at line 1294 of file cyabs_rtos_stk.cpp.

1295{
1296 if (!IsValid(queue))
1297 {
1298 return CY_RTOS_BAD_PARAM;
1299 }
1300
1301 QueueOf(queue)->Reset();
1302
1303 return CY_RSLT_SUCCESS;
1304}

References CY_RTOS_BAD_PARAM.

◆ cy_rtos_queue_space()

cy_rslt_t cy_rtos_queue_space ( const cy_queue_t * queue,
size_t * num_spaces )

Return the amount of empty space in the queue.

This function returns the amount of empty space in the queue. For instance, if the queue was created with 10 entries max and there are currently 2 entries in the queue, this will return 8.

Parameters
[in]queuePointer to the queue handle
[out]num_spacesPointer to the return count.
Returns
The status of the space request. Same across all RTOS kernels [CY_RSLT_SUCCESS, CY_RTOS_BAD_PARAM].
Specific for kernel:
  • THREADX: [CY_RTOS_GENERAL_ERROR].

Definition at line 1282 of file cyabs_rtos_stk.cpp.

1283{
1284 if (!IsValid(queue) || (num_spaces == nullptr))
1285 {
1286 return CY_RTOS_BAD_PARAM;
1287 }
1288
1289 *num_spaces = QueueOf(queue)->GetSpace();
1290
1291 return CY_RSLT_SUCCESS;
1292}

References CY_RTOS_BAD_PARAM.