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

fix docs in Mail

pull/8530/head
paul-szczepanek-arm 2018-10-24 14:43:49 +01:00 committed by Cruz Monrreal II
parent de6ba91644
commit 1b38b5a717
1 changed files with 71 additions and 53 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

110
rtos/Mail.h
View File

@ -43,27 +43,30 @@ namespace rtos {
* @{
*/
/** The Mail class allow to control, send, receive, or wait for mail.
A mail is a memory block 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 mail data store and 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 Mail class allows you to control, send, receive, or wait for mail.
* A mail is a memory block that is sent to a thread or interrupt service routine.
* @tparam T Data type of a single mail message element.
* @tparam queue_sz Maximum number of mail messages in queue.
*
* @note
* Memory considerations: The mail data store and control structures are part of this class - they do not (themselves)
* allocate memory on the heap, 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 Mail : private mbed::NonCopyable<Mail<T, queue_sz> > {
public:
/** Create and Initialize Mail queue.
/** Create and initialize Mail queue.
*
* @note You cannot call this function from ISR context.
*/
Mail() { };
/** Check if the mail queue is empty
/** Check if the mail queue is empty.
*
* @return True if the mail queue is empty, false if not
* @return State of queue.
* @retval true Mail queue is empty.
* @retval false Mail queue contains mail.
*
* @note You may call this function from ISR context.
*/
@ -72,9 +75,11 @@ public:
return _queue.empty();
}
/** Check if the mail queue is full
/** Check if the mail queue is full.
*
* @return True if the mail queue is full, false if not
* @return State of queue.
* @retval true Mail queue is full.
* @retval false Mail queue is not full.
*
* @note You may call this function from ISR context.
*/
@ -83,47 +88,55 @@ public:
return _queue.full();
}
/** Allocate a memory block of type T
@param millisec timeout value or 0 in case of no time-out. (default: 0).
@return pointer to memory block that can be filled with mail or NULL in case error.
@note You may call this function from ISR context if the millisec parameter is set to 0.
/** Allocate a memory block of type T.
*
* @param millisec Not used.
*
* @return Pointer to memory block that can be filled with mail or NULL in case error.
*
* @note You may call this function from ISR context.
*/
T *alloc(uint32_t millisec = 0)
{
T* alloc(uint32_t millisec=0) {
return _pool.alloc();
}
/** Allocate a memory block of type T and set memory block to zero.
@param millisec timeout value or 0 in case of no time-out. (default: 0).
@return pointer to memory block that can be filled with mail or NULL in case error.
@note You may call this function from ISR context if the millisec parameter is set to 0.
*
* @param millisec Not used.
*
* @return Pointer to memory block that can be filled with mail or NULL in case error.
*
* @note You may call this function from ISR context.
*/
T *calloc(uint32_t millisec = 0)
{
T* calloc(uint32_t millisec=0) {
return _pool.calloc();
}
/** Put a mail in the queue.
@param mptr memory block previously allocated with Mail::alloc or Mail::calloc.
@return status code that indicates the execution status of the function.
@note You may call this function from ISR context.
*
* @param mptr Memory block previously allocated with Mail::alloc or Mail::calloc.
*
* @return Status code that indicates the execution status of the function (osOK on success).
*
* @note You may call this function from ISR context.
*/
osStatus put(T *mptr)
{
osStatus put(T *mptr) {
return _queue.put(mptr);
}
/** Get a mail from a queue.
@param millisec timeout value or 0 in case of no time-out. (default: osWaitForever).
@return event that contains mail information or error code.
@note You may call this function from ISR context if the millisec parameter is set to 0.
/** Get a mail from the queue.
*
* @param millisec Timeout value or 0 in case of no timeout (default: osWaitForever).
*
* @return Event that contains mail information or error code.
* @retval osEventMessage Message received.
* @retval osOK No mail is available (and no timeout was specified).
* @retval osEventTimeout No mail has arrived during the given timeout period.
* @retval 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 get(uint32_t millisec=osWaitForever) {
osEvent evt = _queue.get(millisec);
if (evt.status == osEventMessage) {
evt.status = osEventMail;
@ -132,19 +145,24 @@ public:
}
/** Free a memory block from a mail.
@param mptr pointer to the memory block that was obtained with Mail::get.
@return status code that indicates the execution status of the function.
@note You may call this function from ISR context.
*
* @param mptr Pointer to the memory block that was obtained with Mail::get.
*
* @return Status code that indicates the execution status of the function (osOK on success).
*
* @note You may call this function from ISR context.
*/
osStatus free(T *mptr)
{
osStatus free(T *mptr) {
return _pool.free(mptr);
}
#if !defined(DOXYGEN_ONLY)
private:
Queue<T, queue_sz> _queue;
MemoryPool<T, queue_sz> _pool;
#endif //!defined(DOXYGEN_ONLY)
};
/** @}*/