Skip to content

Commit 7e8a932

Browse files
Steve CartmellCruz Monrreal II
Steve Cartmell
authored and
Cruz Monrreal II
committed
docs(api-queue): Update documentation for the Queue API
1 parent de6ba91 commit 7e8a932

File tree

1 file changed

+99
-44
lines changed

1 file changed

+99
-44
lines changed

‎rtos/Queue.h

Lines changed: 99 additions & 44 deletions
Original file line numberDiff line numberDiff line change
@@ -22,14 +22,11 @@
2222
#ifndef QUEUE_H
2323
#define QUEUE_H
2424

25-
#include <stdint.h>
26-
#include <string.h>
27-
2825
#include "cmsis_os2.h"
26+
#include "mbed_rtos1_types.h"
2927
#include "mbed_rtos_storage.h"
3028
#include "platform/mbed_error.h"
3129
#include "platform/NonCopyable.h"
32-
#include "mbed_rtos1_types.h"
3330

3431
namespace rtos {
3532
/** \addtogroup rtos */
@@ -39,20 +36,30 @@ namespace rtos {
3936
* @{
4037
*/
4138

42-
/** The Queue class allow to control, send, receive, or wait for messages.
43-
A message can be a integer or pointer value to a certain type T that is send
44-
to a thread or interrupt service routine.
45-
@tparam T data type of a single message element.
46-
@tparam queue_sz maximum number of messages in queue.
47-
48-
@note
49-
Memory considerations: The queue control structures will be created on current thread's stack, both for the mbed OS
50-
and underlying RTOS objects (static or dynamic RTOS memory pools are not being used).
51-
*/
39+
/** The Queue class represents a collection of objects that are stored first by
40+
* order of priorty, and then in first-in, first-out (FIFO) order.
41+
*
42+
* A queue is used to when data needs to stored and then accessed in the same
43+
* order that it has been stored. The order in which they are retrieved is in
44+
* order of descending priority, if multiple elements have the same priority
45+
* they are retrieved in FIFO order.
46+
*
47+
* The object type stored in the queue can be an integer, pointer, or a generic
48+
* type given by the template parameter T.
49+
*
50+
* @tparam T Specifies the type of elements that are stored in the queue.
51+
* @tparam queue_sz Maximum number of messages that can be stored in the queue.
52+
*
53+
* @note Memory considerations: The queue control structures will be created on
54+
* current thread's stack, both for the mbed OS and underlying RTOS
55+
* objects (static or dynamic RTOS memory pools are not being used).
56+
*
57+
*/
5258
template<typename T, uint32_t queue_sz>
5359
class Queue : private mbed::NonCopyable<Queue<T, queue_sz> > {
5460
public:
55-
/** Create and initialize a message Queue.
61+
/** Create and initialize a message Queue of objects of the parameterized
62+
* type `T` and maximum capacity specified by `queue_sz`
5663
*
5764
* @note You cannot call this function from ISR context.
5865
*/
@@ -67,6 +74,7 @@ class Queue : private mbed::NonCopyable<Queue<T, queue_sz> > {
6774
_id = osMessageQueueNew(queue_sz, sizeof(T *), &attr);
6875
MBED_ASSERT(_id);
6976
}
77+
7078
/** Queue destructor
7179
*
7280
* @note You cannot call this function from ISR context.
@@ -98,36 +106,83 @@ class Queue : private mbed::NonCopyable<Queue<T, queue_sz> > {
98106
return osMessageQueueGetSpace(_id) == 0;
99107
}
100108

101-
/** Put a message in a Queue.
102-
@param data message pointer.
103-
@param millisec timeout value or 0 in case of no time-out. (default: 0)
104-
@param prio priority value or 0 in case of default. (default: 0)
105-
@return status code that indicates the execution status of the function:
106-
@a osOK the message has been put into the queue.
107-
@a osErrorTimeout the message could not be put into the queue in the given time.
108-
@a osErrorResource not enough space in the queue.
109-
@a osErrorParameter internal error or non-zero timeout specified in an ISR.
110-
111-
@note You may call this function from ISR context if the millisec parameter is set to 0.
112-
*/
113-
osStatus put(T *data, uint32_t millisec = 0, uint8_t prio = 0)
114-
{
109+
/** Inserts the given element to the end of the queue.
110+
*
111+
* This function puts the message pointed to by `data` into the queue. The
112+
* parameter `prio` is used to sort the message according to their priority
113+
* (higher numbers indicate higher priority) on insertion.
114+
*
115+
* The timeout indicated by the parameter `millisec` specifies how long the
116+
* function will block waiting for the message to be inserted into the
117+
* queue.
118+
*
119+
* The parameter `millisec` can have the following values:
120+
* - When the timeout is 0 (the default), the function returns instantly.
121+
* - When the timeout is osWaitForever the function will wait for an
122+
* infinite time.
123+
* - For all other values the function will wait for the given number of
124+
* milliseconds.
125+
*
126+
* @param data Pointer to the element to insert into the queue.
127+
* @param millisec Timeout for the operation to be executed, or 0 in case
128+
* of no-timeout. (default: 0)
129+
* @param prio Priority of the operation or 0 in case of default.
130+
* (default: 0)
131+
*
132+
* @return Status code that indicates the execution status of the function:
133+
* @a osOK The message has been successfully inserted
134+
* into the queue.
135+
* @a osErrorTimeout The message could not be inserted into the
136+
* queue in the given time.
137+
* @a osErrorResource The message could not be inserted because
138+
* the queue is full.
139+
* @a osErrorParameter Internal error or non-zero timeout specified
140+
* in an ISR.
141+
*
142+
* @note You may call this function from ISR context if the millisec
143+
* parameter is set to 0.
144+
*
145+
*/
146+
osStatus put(T* data, uint32_t millisec=0, uint8_t prio=0) {
115147
return osMessageQueuePut(_id, &data, prio, millisec);
116148
}
117149

118-
/** Get a message or Wait for a message from a Queue. Messages are retrieved in a descending priority order or
119-
first in first out when the priorities are the same.
120-
@param millisec timeout value or 0 in case of no time-out. (default: osWaitForever).
121-
@return event information that includes the message in event.value and the status code in event.status:
122-
@a osEventMessage message received.
123-
@a osOK no message is available in the queue and no timeout was specified.
124-
@a osEventTimeout no message has arrived during the given timeout period.
125-
@a osErrorParameter a parameter is invalid or outside of a permitted range.
126-
127-
@note You may call this function from ISR context if the millisec parameter is set to 0.
128-
*/
129-
osEvent get(uint32_t millisec = osWaitForever)
130-
{
150+
/** Get a message or wait for a message from the queue.
151+
*
152+
* This function retrieves a message from the queue. The message is stored
153+
* in the value field of the returned `osEvent` object.
154+
*
155+
* The timeout specified by the parameter `millisec` specifies how long the
156+
* function will wait to retrieve the message from the queue.
157+
*
158+
* The timeout parameter can have the following values:
159+
* - When the timeout is 0, the function returns instantly.
160+
* - When the timeout is osWaitForever (default), the function will wait
161+
* infinite time until the message is retrieved.
162+
* - When the timeout is any other value the function will wait for th
163+
* specified time before returning a timeout error.
164+
*
165+
* Messages are retrieved in descending priority order. If two messages
166+
* share the same priority level they are retrieved in first-in, first-out
167+
* (FIFO) order.
168+
*
169+
* @param millisec Timeout value or 0 in case of no time-out.
170+
* (default: osWaitForever).
171+
*
172+
* @return Event information that includes the message in event. Message
173+
* value and the status code in event.status:
174+
* @a osEventMessage Message successfully received.
175+
* @a osOK No message is available in the queue and no
176+
* timeout was specified.
177+
* @a osEventTimeout No message was received before a timeout
178+
* event occurred.
179+
* @a osErrorParameter A parameter is invalid or outside of a
180+
* permitted range.
181+
*
182+
* @note You may call this function from ISR context if the millisec
183+
* parameter is set to 0.
184+
*/
185+
osEvent get(uint32_t millisec=osWaitForever) {
131186
osEvent event;
132187
T *data = NULL;
133188
osStatus_t res = osMessageQueueGet(_id, &data, NULL, millisec);
@@ -161,6 +216,6 @@ class Queue : private mbed::NonCopyable<Queue<T, queue_sz> > {
161216
/** @}*/
162217
/** @}*/
163218

164-
}
165-
#endif
219+
} // namespace rtos
166220

221+
#endif // QUEUE_H

0 commit comments

Comments
 (0)