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

108
rtos/Mail.h
View File

@ -43,27 +43,30 @@ namespace rtos {
* @{ * @{
*/ */
/** The Mail class allow to control, send, receive, or wait for mail. /** The Mail class allows you to control, send, receive, or wait for mail.
A mail is a memory block that is send to a thread or interrupt service routine. * A mail is a memory block that is sent to a thread or interrupt service routine.
@tparam T data type of a single message element. * @tparam T Data type of a single mail message element.
@tparam queue_sz maximum number of messages in queue. * @tparam queue_sz Maximum number of mail messages in queue.
*
@note * @note
Memory considerations: The mail data store and control structures will be created on current thread's stack, * Memory considerations: The mail data store and control structures are part of this class - they do not (themselves)
both for the mbed OS and underlying RTOS objects (static or dynamic RTOS memory pools are not being used). * 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> template<typename T, uint32_t queue_sz>
class Mail : private mbed::NonCopyable<Mail<T, queue_sz> > { class Mail : private mbed::NonCopyable<Mail<T, queue_sz> > {
public: public:
/** Create and Initialize Mail queue. /** Create and initialize Mail queue.
* *
* @note You cannot call this function from ISR context. * @note You cannot call this function from ISR context.
*/ */
Mail() { }; 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. * @note You may call this function from ISR context.
*/ */
@ -72,9 +75,11 @@ public:
return _queue.empty(); 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. * @note You may call this function from ISR context.
*/ */
@ -83,47 +88,55 @@ public:
return _queue.full(); return _queue.full();
} }
/** Allocate a memory block of type T /** 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. * @param millisec Not used.
*
@note You may call this function from ISR context if the millisec parameter is set to 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.
*/ */
T *alloc(uint32_t millisec = 0) T* alloc(uint32_t millisec=0) {
{
return _pool.alloc(); return _pool.alloc();
} }
/** Allocate a memory block of type T and set memory block to zero. /** 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. * @param millisec Not used.
*
@note You may call this function from ISR context if the millisec parameter is set to 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.
*/ */
T *calloc(uint32_t millisec = 0) T* calloc(uint32_t millisec=0) {
{
return _pool.calloc(); return _pool.calloc();
} }
/** Put a mail in the queue. /** 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. * @param mptr Memory block previously allocated with Mail::alloc or Mail::calloc.
*
@note You may call this function from ISR context. * @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); return _queue.put(mptr);
} }
/** Get a mail from a queue. /** Get a mail from the queue.
@param millisec timeout value or 0 in case of no time-out. (default: osWaitForever). *
@return event that contains mail information or error code. * @param millisec Timeout value or 0 in case of no timeout (default: osWaitForever).
*
@note You may call this function from ISR context if the millisec parameter is set to 0. * @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); osEvent evt = _queue.get(millisec);
if (evt.status == osEventMessage) { if (evt.status == osEventMessage) {
evt.status = osEventMail; evt.status = osEventMail;
@ -132,19 +145,24 @@ public:
} }
/** Free a memory block from a mail. /** 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. * @param mptr Pointer to the memory block that was obtained with Mail::get.
*
@note You may call this function from ISR context. * @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); return _pool.free(mptr);
} }
#if !defined(DOXYGEN_ONLY)
private: private:
Queue<T, queue_sz> _queue; Queue<T, queue_sz> _queue;
MemoryPool<T, queue_sz> _pool; MemoryPool<T, queue_sz> _pool;
#endif //!defined(DOXYGEN_ONLY)
}; };
/** @}*/ /** @}*/