Synchronous Messages
[Synchronization]

Collaboration diagram for Synchronous Messages:

---

Description

Synchronous inter-thread messages APIs and services.

Operation Mode

Synchronous messages are an easy to use and fast IPC mechanism, threads can both act as message servers and/or message clients, the mechanism allows data to be carried in both directions. Note that messages are not copied between the client and server threads but just a pointer passed so the exchange is very time efficient.
Messages are usually processed in FIFO order but it is possible to process them in priority order by enabling the CH_USE_MESSAGES_PRIORITY option in chconf.h.
Applications do not need to allocate buffers for synchronous message queues, the mechanism just requires two extra pointers in the Thread structure (the message queue header).
In order to use the Messages APIs the CH_USE_MESSAGES option must be enabled in chconf.h.

Defines
#define	chMsgIsPendingI(tp)   ((tp)->p_msgqueue.p_next != (Thread *)&(tp)->p_msgqueue)
	Evaluates to TRUE if the thread has pending messages.
#define	chMsgGetI(tp)   ((tp)->p_msgqueue.p_next->p_msg)
	Returns the first message in the queue.
Functions
msg_t	chMsgSend (Thread *tp, msg_t msg)
	Sends a message to the specified thread.
msg_t	chMsgWait (void)
	Suspends the thread and waits for an incoming message.
msg_t	chMsgGet (void)
	Returns the next message in the queue.
void	chMsgRelease (msg_t msg)
	Releases the thread waiting on top of the messages queue.

---

Define Documentation

#define chMsgIsPendingI

(

tp

)

((tp)->p_msgqueue.p_next != (Thread *)&(tp)->p_msgqueue)

Evaluates to TRUE if the thread has pending messages.

Definition at line 43 of file chmsg.h.

Referenced by chMsgGet(), chMsgRelease(), chMsgWait(), and chibios_rt::BaseThread::IsPendingMessage().

#define chMsgGetI

(

tp

)

((tp)->p_msgqueue.p_next->p_msg)

Returns the first message in the queue.

Definition at line 49 of file chmsg.h.

Referenced by chMsgGet(), and chMsgWait().

---

Function Documentation

msg_t chMsgSend	(	Thread *	tp,
		msg_t	msg
	)

Sends a message to the specified thread.

The sender is stopped until the receiver executes a chMsgRelease()after receiving the message.

Parameters:

[in]	tp	the pointer to the thread
[in]	msg	the message

Returns:

The answer message from chMsgRelease().

Definition at line 70 of file chmsg.c.

References chDbgCheck, chSchGoSleepS(), chSchReadyI(), chSysLock, chSysUnlock, currp, Thread::p_msg, Thread::p_msgqueue, Thread::p_state, Thread::p_u, Thread::rdymsg, THD_STATE_SNDMSG, THD_STATE_WTMSG, and Thread::wtobjp.

Referenced by chibios_rt::BaseThread::SendMessage().

Here is the call graph for this function:

msg_t chMsgWait

(

void

)

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 chMsgRelease() because the sending thread is suspended until then.

Returns:

The pointer to the message structure. Note, it is always the message associated to the thread on the top of the messages queue.

Definition at line 97 of file chmsg.c.

References chMsgGetI, chMsgIsPendingI, chSchGoSleepS(), chSysLock, chSysUnlock, currp, and THD_STATE_WTMSG.

Referenced by chibios_rt::BaseThread::WaitMessage().

Here is the call graph for this function:

msg_t chMsgGet

(

void

)

Returns the next message in the queue.

Note:

You can assume that the data pointed by the message is stable until you invoke 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.

Returns:

The pointer to the message structure. Note, it is always the message associated to the thread on the top of the messages queue.

Return values:

NULL

if the queue is empty.

Definition at line 125 of file chmsg.c.

References chMsgGetI, chMsgIsPendingI, chSysLock, chSysUnlock, and currp.

Referenced by chibios_rt::BaseThread::GetMessage().

void chMsgRelease

(

msg_t

msg

)

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 chMsgWait() ensures you have at least one message in the queue so it is not a big deal.
The condition is only tested in debug mode in order to make this code as fast as possible.

Parameters:

[in]

msg

the message returned to the message sender

Definition at line 145 of file chmsg.c.

References chDbgAssert, chMsgIsPendingI, chSchWakeupS(), chSysLock, chSysUnlock, currp, and fifo_remove().

Referenced by chibios_rt::BaseThread::ReleaseMessage().

Here is the call graph for this function: