riot-ci/RIOT
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

Fix documentation for msg.h

Browse Source
This commit is contained in:
Martin Lenders 2014-04-01 15:45:06 +02:00
parent c35a7555a3
commit 24db4eee8c
1 changed files with 70 additions and 53 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

123
core/include/msg.h
View File

@ -11,13 +11,14 @@
* @ingroup core
* @brief Messaging API for inter process communication
*
* There are two ways to use the IPC Messaging system of RIOT. The default is synchronous
* messaging. In this manner, messages are either dropped when the receiver is not waiting and the
* message was sent non-blocking, or will be delivered immediately when the receiver calls
* msg_receive(msg_t* m). To use asynchronous messaging any thread can create its own queue by
* calling msg_init_queue(msg_t* array, int num). Messages sent to a thread with a non full message
* queue are never dropped and the sending never blocks. Threads with a full message queue behaves
* like in synchronous mode.
* There are two ways to use the IPC Messaging system of RIOT. The default is
* synchronous messaging. In this manner, messages are either dropped when the
* receiver is not waiting and the message was sent non-blocking, or will be
* delivered immediately when the receiver calls msg_receive(msg_t* m). To use
* asynchronous messaging any thread can create its own queue by calling
* msg_init_queue(msg_t* array, int num). Messages sent to a thread with a non
* full message queue are never dropped * and the sending never blocks. Threads
* with a full message queue behaves like in synchronous mode.
*
* @{
*
@ -29,16 +30,12 @@
* @author Kévin Roussel <Kevin.Roussel@inria.fr>
*/
#ifndef __MSG_H
#define __MSG_H
#ifndef __MSG_H_
#define __MSG_H_
#include <stdint.h>
#include <stdbool.h>
#define MESSAGE_SENT 1
#define MESSAGE_PROCESS_NOT_WAITING 0
#define MESSAGE_PROCESS_UNKNOWN 2
/**
* @brief Describes a message object which can be sent between threads.
*
@ -48,31 +45,35 @@
*
*/
typedef struct msg {
uint16_t sender_pid; ///< PID of sending thread. Will be filled in by msg_send
uint16_t type; ///< Type field.
uint16_t sender_pid; /**< PID of sending thread. Will be filled in
by msg_send. */
uint16_t type; /**< Type field. */
union {
char *ptr; ///< pointer content field
uint32_t value; ///< value content field
} content;
char *ptr; /**< Pointer content field. */
uint32_t value; /**< Value content field. */
} content; /**< Content of the message. */
} msg_t;
/**
* @brief Send a message.
*
* This function sends a message to another thread.
* The msg structure has to be allocated (e.g. on the stack)
* before calling the function and can be freed afterwards.
* If called from an interrupt, this function will never block.
* This function sends a message to another thread. The ``msg_t`` structure has
* to be allocated (e.g. on the stack) before calling the function and can be
* freed afterwards. If called from an interrupt, this function will never
* block.
*
* @param m Pointer to message structure
* @param target_pid PID of target thread
* @param block If true and receiver is not receive-blocked, function will block. If not, function
* returns.
* @param[in] m Pointer to preallocated ``msg_t`` structure, must
* not be NULL.
* @param[in] target_pid PID of target thread
* @param[in] block If not 0 and receiver is not receive-blocked,
* function will block. If not, function returns.
*
* @return 1 if sending was successful (message delivered directly or to a queue)
* @return 0 if receiver is not waiting or has a full message queue and block == false
* @return -1 on error (invalid PID)
* @return 1, if sending was successful (message delivered directly or to a
* queue)
* @return 0, if receiver is not waiting or has a full message queue and
* ``block == 0``
* @return -1, on error (invalid PID)
*/
int msg_send(msg_t *m, unsigned int target_pid, bool block);
@ -95,13 +96,15 @@ int msg_send_to_self(msg_t *m);
/**
* @brief Send message from interrupt.
*
* Will be automatically chosen instead of msg_send if inISR() == true
* Will be automatically chosen instead of ``msg_sennd()`` if called from an
* interrupt/ISR.
*
* @param m pointer to message structure
* @param target_pid PID of target thread
* @param[in] m Pointer to preallocated ``msg_t`` structure, must
* not be NULL.
* @param[in] target_pid PID of target thread.
*
* @return 1 if sending was successful
* @return 0 if receiver is not waiting and block == false
* @return 1, if sending was successful
* @return 0, if receiver is not waiting and ``block == 0``
*/
int msg_send_int(msg_t *m, unsigned int target_pid);
@ -110,9 +113,11 @@ int msg_send_int(msg_t *m, unsigned int target_pid);
* @brief Receive a message.
*
* This function blocks until a message was received.
* @param m pointer to preallocated msg
*
* @return 1 Function always succeeds or blocks forever.
* @param[out] m Pointer to preallocated ``msg_t`` structure, must not be
* NULL.
*
* @return 1, Function always succeeds or blocks forever.
*/
int msg_receive(msg_t *m);
@ -120,21 +125,30 @@ int msg_receive(msg_t *m);
* @brief Try to receive a message.
*
* This function does not block if no message can be received.
* @param m pointer to preallocated msg
*
* @return 1 if a message was received, -1 otherwise.
* @param[out] m Pointer to preallocated ``msg_t`` structure, must not be
* NULL.
*
* @return 1, if a message was received
* @return -1, otherwise.
*/
int msg_try_receive(msg_t *m);
/**
* @brief Send a message, block until reply received.
*
* This function sends a message to target_pid and then blocks until target has sent a reply.
* @note CAUTION!Use this function only when receiver is already waiting. If not use simple msg_send()
* @param m pointer to preallocated msg
* @param reply pointer to preallocated msg. Reply will be written here.
* @param target pid the pid of the target process
* @return 1 if successful
* This function sends a message to *target_pid* and then blocks until target
* has sent a reply which is then stored in *reply*.
*
* @note CAUTION! Use this function only when receiver is already waiting.
* If not use simple msg_send()
* @param[in] m Pointer to preallocated ``msg_t`` structure with
* the message to send, must not be NULL.
* @param[out] reply Pointer to preallocated msg. Reply will be written
* here, must not be NULL.
* @param[in] target_pid The PID of the target process
*
* @return 1, if successful.
*/
int msg_send_receive(msg_t *m, msg_t *reply, unsigned int target_pid);
@ -143,24 +157,27 @@ int msg_send_receive(msg_t *m, msg_t *reply, unsigned int target_pid);
*
* Sender must have sent the message with msg_send_receive().
*
* @param m msg to reply to.
* @param reply message that target will get as reply
* @param[in] m message to reply to, must not be NULL.
* @param[out] reply message that target will get as reply, must not be
* NULL.
*
* @return 1 if successful
* @return 0 on error
* @return 1, if successful
* @return 0, on error
*/
int msg_reply(msg_t *m, msg_t *reply);
/**
* @brief Initialize the current thread's message queue.
*
* @param array Pointer to preallocated array of msg objects
* @param num Number of msg objects in array. MUST BE POWER OF TWO!
* @param[in] array Pointer to preallocated array of ``msg_t`` structures, must
* not be NULL.
* @param[in] num Number of ``msg_t`` structurs in array.
* **MUST BE POWER OF TWO!**
*
* @return 0 if successful
* @return -1 on error
* @return 0, if successful
* @return -1, on error
*/
int msg_init_queue(msg_t *array, int num);
#endif /* __MSG_H_ */
/** @} */
#endif /* __MSG_H */