From 7e8a932b6f6456d9ae146fa85ffe813646634edc Mon Sep 17 00:00:00 2001 From: Steve Cartmell Date: Wed, 24 Oct 2018 15:18:02 +0100 Subject: [PATCH 1/2] docs(api-queue): Update documentation for the Queue API --- rtos/Queue.h | 143 +++++++++++++++++++++++++++++++++++---------------- 1 file changed, 99 insertions(+), 44 deletions(-) diff --git a/rtos/Queue.h b/rtos/Queue.h index ec515e1065..c1d0790331 100644 --- a/rtos/Queue.h +++ b/rtos/Queue.h @@ -22,14 +22,11 @@ #ifndef QUEUE_H #define QUEUE_H -#include -#include - #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 class Queue : private mbed::NonCopyable > { 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 From fbc5a381afd5a2a6bb2a09952a997c221d718780 Mon Sep 17 00:00:00 2001 From: Amanda Butler Date: Thu, 25 Oct 2018 09:22:39 -0500 Subject: [PATCH 2/2] Edit Queue.h Edit file, including existing text, mostly for active voice and consistent tense. --- rtos/Queue.h | 40 ++++++++++++++++++++-------------------- 1 file changed, 20 insertions(+), 20 deletions(-) diff --git a/rtos/Queue.h b/rtos/Queue.h index c1d0790331..acd5726cf2 100644 --- a/rtos/Queue.h +++ b/rtos/Queue.h @@ -39,19 +39,19 @@ namespace rtos { /** 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 + * You can use a queue when you need to store data and then access it in the same + * order that it has been stored. The order in which you retrieve the data 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 + * 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. + * @tparam T Specifies the type of elements stored in the queue. + * @tparam queue_sz Maximum number of messages that you can store 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 + * @note Memory considerations: The queue control structures are created on the + * current thread's stack, both for the Mbed OS and underlying RTOS * objects (static or dynamic RTOS memory pools are not being used). * */ @@ -84,7 +84,7 @@ public: osMessageQueueDelete(_id); } - /** Check if the queue is empty + /** Check if the queue is empty. * * @return True if the queue is empty, false if not * @@ -95,7 +95,7 @@ public: return osMessageQueueGetCount(_id) == 0; } - /** Check if the queue is full + /** Check if the queue is full. * * @return True if the queue is full, false if not * @@ -113,19 +113,19 @@ public: * (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 + * function blocks 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 + * - When the timeout is osWaitForever, the function waits for an * infinite time. - * - For all other values the function will wait for the given number of + * - For all other values, the function waits 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) + * of no timeout. (default: 0) * @param prio Priority of the operation or 0 in case of default. * (default: 0) * @@ -136,7 +136,7 @@ public: * 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 + * @a osErrorParameter Internal error or nonzero timeout specified * in an ISR. * * @note You may call this function from ISR context if the millisec @@ -153,17 +153,17 @@ public: * 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. + * function waits 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 + * - When the timeout is osWaitForever (default), the function waits * infinite time until the message is retrieved. - * - When the timeout is any other value the function will wait for th + * - When the timeout is any other value, the function waits for the * 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 + * 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. @@ -172,7 +172,7 @@ public: * @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 + * @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.