diff options
Diffstat (limited to 'os/kernel/src/chmsg.c')
| -rw-r--r-- | os/kernel/src/chmsg.c | 48 |
1 files changed, 22 insertions, 26 deletions
diff --git a/os/kernel/src/chmsg.c b/os/kernel/src/chmsg.c index 96bf61452..09acf7b42 100644 --- a/os/kernel/src/chmsg.c +++ b/os/kernel/src/chmsg.c @@ -30,20 +30,22 @@ * that messages are not copied between the client and server threads
* but just a pointer passed so the exchange is very time
* efficient.<br>
+ * Messages are scalar data types of type @p msg_t that are guaranteed
+ * to be size compatible with data pointers. Note that on some
+ * architectures function pointers can be larger that @p msg_t.<br>
* Messages are usually processed in FIFO order but it is possible to
* process them in priority order by enabling the
* @p CH_USE_MESSAGES_PRIORITY option in @p chconf.h.<br>
- * Applications do not need to allocate buffers for synchronous
- * message queues, the mechanism just requires two extra pointers in
- * the @p Thread structure (the message queue header).<br>
- * In order to use the Messages APIs the @p CH_USE_MESSAGES option
+ * @pre In order to use the message APIs the @p CH_USE_MESSAGES option
* must be enabled in @p chconf.h.
+ * @post Enabling messages requires 6-12 (depending on the architecture)
+ * extra bytes in the @p Thread structure.
* @{
*/
#include "ch.h"
-#if CH_USE_MESSAGES
+#if CH_USE_MESSAGES || defined(__DOXYGEN__)
#if CH_USE_MESSAGES_PRIORITY
#define msg_insert(tp, qp) prio_insert(tp, qp)
@@ -79,13 +81,13 @@ msg_t chMsgSend(Thread *tp, msg_t msg) { /**
* @brief Suspends the thread and waits for an incoming message.
- * @note You can assume that the data contained in the message is stable
- * until you invoke @p chMsgRelease() because the sending thread is
- * suspended until then.
+ * @post After receiving a message the function @p chMsgRelease() must be
+ * invoked in order to acknowledge the reception and send the answer.
+ * @note If the message is a pointer then you can assume that the data
+ * pointed by the message is stable until you invoke @p chMsgRelease()
+ * because the sending thread is suspended until then.
*
- * @return The pointer to the message structure. Note, it is
- * always the message associated to the thread on the
- * top of the messages queue.
+ * @return The message.
*/
msg_t chMsgWait(void) {
msg_t msg;
@@ -104,16 +106,14 @@ msg_t chMsgWait(void) { /**
* @brief Returns the next message in the queue.
- * @note You can assume that the data pointed by the message is stable until
- * you invoke @p chMsgRelease() because the sending thread is
- * suspended until then. Always remember that the message data is not
- * copied between the sender and the receiver, just a pointer is
- * passed.
+ * @post After receiving a message the function @p chMsgRelease() must be
+ * invoked in order to acknowledge the reception and send the answer.
+ * @note If the message is a pointer then you can assume that the data
+ * pointed by the message is stable until you invoke @p chMsgRelease()
+ * because the sending thread is suspended until then.
*
- * @return The pointer to the message structure. Note, it is
- * always the message associated to the thread on the
- * top of the messages queue.
- * @retval NULL if the queue is empty.
+ * @return The message.
+ * @retval 0 if the queue is empty.
*/
msg_t chMsgGet(void) {
msg_t msg;
@@ -126,12 +126,8 @@ msg_t chMsgGet(void) { /**
* @brief Releases the thread waiting on top of the messages queue.
- * @note You can call this function only if there is a message already in
- * the queue else the result will be unpredictable (a crash most likely).
- * Exiting from the @p chMsgWait() ensures you have at least one
- * message in the queue so it is not a big deal.<br>
- * The condition is only tested in debug mode in order to make this
- * code as fast as possible.
+ * @pre Invoke this function only after a message has been received
+ * using @p chMsgWait() or @p chMsgGet().
*
* @param[in] msg the message returned to the message sender
*/
|