ARMmbed
/
mbed-os
mirror of https://github.com/ARMmbed/mbed-os.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

docs(api-queue): Update documentation for the Queue API

pull/8540/head
Steve Cartmell 2018-10-24 15:18:02 +01:00 committed by Cruz Monrreal II
parent de6ba91644
commit 7e8a932b6f
1 changed files with 99 additions and 44 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

143
rtos/Queue.h
View File

@ -22,14 +22,11 @@
#ifndef QUEUE_H
#define QUEUE_H
#include <stdint.h>
#include <string.h>
#include "cmsis_os2.h"
#include "mbed_rtos1_types.h"
#include "mbed_rtos_storage.h"
#include "platform/mbed_error.h"
#include "platform/NonCopyable.h"
#include "mbed_rtos1_types.h"
namespace rtos {
/** \addtogroup rtos */
@ -39,20 +36,30 @@ namespace rtos {
* @{
*/
/** The Queue class allow to control, send, receive, or wait for messages.
A message can be a integer or pointer value to a certain type T that is send
to a thread or interrupt service routine.
@tparam T data type of a single message element.
@tparam queue_sz maximum number of messages in queue.
@note
Memory considerations: The queue control structures will be created on current thread's stack, both for the mbed OS
and underlying RTOS objects (static or dynamic RTOS memory pools are not being used).
*/
/** The Queue class represents a collection of objects that are stored first by
* order of priorty, and then in first-in, first-out (FIFO) order.
*
* A queue is used to when data needs to stored and then accessed in the same
* order that it has been stored. The order in which they are retrieved is in
* order of descending priority, if multiple elements have the same priority
* they are retrieved in FIFO order.
*
* The object type stored in the queue can be an integer, pointer, or a generic
* type given by the template parameter T.
*
* @tparam T Specifies the type of elements that are stored in the queue.
* @tparam queue_sz Maximum number of messages that can be stored in the queue.
*
* @note Memory considerations: The queue control structures will be created on
* current thread's stack, both for the mbed OS and underlying RTOS
* objects (static or dynamic RTOS memory pools are not being used).
*
*/
template<typename T, uint32_t queue_sz>
class Queue : private mbed::NonCopyable<Queue<T, queue_sz> > {
public:
/** Create and initialize a message Queue.
/** Create and initialize a message Queue of objects of the parameterized
* type `T` and maximum capacity specified by `queue_sz`
*
* @note You cannot call this function from ISR context.
*/
@ -67,6 +74,7 @@ public:
_id = osMessageQueueNew(queue_sz, sizeof(T *), &attr);
MBED_ASSERT(_id);
}
/** Queue destructor
*
* @note You cannot call this function from ISR context.
@ -98,36 +106,83 @@ public:
return osMessageQueueGetSpace(_id) == 0;
}
/** Put a message in a Queue.
@param data message pointer.
@param millisec timeout value or 0 in case of no time-out. (default: 0)
@param prio priority value or 0 in case of default. (default: 0)
@return status code that indicates the execution status of the function:
@a osOK the message has been put into the queue.
@a osErrorTimeout the message could not be put into the queue in the given time.
@a osErrorResource not enough space in the queue.
@a osErrorParameter internal error or non-zero timeout specified in an ISR.
@note You may call this function from ISR context if the millisec parameter is set to 0.
*/
osStatus put(T *data, uint32_t millisec = 0, uint8_t prio = 0)
{
/** Inserts the given element to the end of the queue.
*
* This function puts the message pointed to by `data` into the queue. The
* parameter `prio` is used to sort the message according to their priority
* (higher numbers indicate higher priority) on insertion.
*
* The timeout indicated by the parameter `millisec` specifies how long the
* function will block waiting for the message to be inserted into the
* queue.
*
* The parameter `millisec` can have the following values:
* - When the timeout is 0 (the default), the function returns instantly.
* - When the timeout is osWaitForever the function will wait for an
* infinite time.
* - For all other values the function will wait for the given number of
* milliseconds.
*
* @param data Pointer to the element to insert into the queue.
* @param millisec Timeout for the operation to be executed, or 0 in case
* of no-timeout. (default: 0)
* @param prio Priority of the operation or 0 in case of default.
* (default: 0)
*
* @return Status code that indicates the execution status of the function:
* @a osOK The message has been successfully inserted
* into the queue.
* @a osErrorTimeout The message could not be inserted into the
* queue in the given time.
* @a osErrorResource The message could not be inserted because
* the queue is full.
* @a osErrorParameter Internal error or non-zero timeout specified
* in an ISR.
*
* @note You may call this function from ISR context if the millisec
* parameter is set to 0.
*
*/
osStatus put(T* data, uint32_t millisec=0, uint8_t prio=0) {
return osMessageQueuePut(_id, &data, prio, millisec);
}
/** Get a message or Wait for a message from a Queue. Messages are retrieved in a descending priority order or
first in first out when the priorities are the same.
@param millisec timeout value or 0 in case of no time-out. (default: osWaitForever).
@return event information that includes the message in event.value and the status code in event.status:
@a osEventMessage message received.
@a osOK no message is available in the queue and no timeout was specified.
@a osEventTimeout no message has arrived during the given timeout period.
@a osErrorParameter a parameter is invalid or outside of a permitted range.
@note You may call this function from ISR context if the millisec parameter is set to 0.
*/
osEvent get(uint32_t millisec = osWaitForever)
{
/** Get a message or wait for a message from the queue.
*
* This function retrieves a message from the queue. The message is stored
* in the value field of the returned `osEvent` object.
*
* The timeout specified by the parameter `millisec` specifies how long the
* function will wait to retrieve the message from the queue.
*
* The timeout parameter can have the following values:
* - When the timeout is 0, the function returns instantly.
* - When the timeout is osWaitForever (default), the function will wait
* infinite time until the message is retrieved.
* - When the timeout is any other value the function will wait for th
* specified time before returning a timeout error.
*
* Messages are retrieved in descending priority order. If two messages
* share the same priority level they are retrieved in first-in, first-out
* (FIFO) order.
*
* @param millisec Timeout value or 0 in case of no time-out.
* (default: osWaitForever).
*
* @return Event information that includes the message in event. Message
* value and the status code in event.status:
* @a osEventMessage Message successfully received.
* @a osOK No message is available in the queue and no
* timeout was specified.
* @a osEventTimeout No message was received before a timeout
* event occurred.
* @a osErrorParameter A parameter is invalid or outside of a
* permitted range.
*
* @note You may call this function from ISR context if the millisec
* parameter is set to 0.
*/
osEvent get(uint32_t millisec=osWaitForever) {
osEvent event;
T *data = NULL;
osStatus_t res = osMessageQueueGet(_id, &data, NULL, millisec);
@ -161,6 +216,6 @@ private:
/** @}*/
/** @}*/
}
#endif
} // namespace rtos
#endif // QUEUE_H