Synchronous Messages

Collaboration diagram for Synchronous Messages:

---

Detailed 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 scalar data types of type msg_t that are guaranteed to be size compatible with data pointers. Note that on some architectures function pointers can be larger that msg_t.
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.

Precondition:

In order to use the message APIs the CH_USE_MESSAGES option must be enabled in chconf.h.

Postcondition:

Enabling messages requires 6-12 (depending on the architecture) extra bytes in the Thread structure.

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

---

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().

Function Class:

Normal API, this function can be invoked by regular system threads but not from within a lock zone.

Definition at line 68 of file chmsg.c.

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

Here is the call graph for this function:

Thread * chMsgWait

(

void

)

Suspends the thread and waits for an incoming message.

Postcondition:

After receiving a message the function chMsgGet() must be called in order to retrieve the message and then 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 chMsgRelease() because the sending thread is suspended until then.

Returns:

A reference to the thread carrying the message.

Function Class:

Normal API, this function can be invoked by regular system threads but not from within a lock zone.

Definition at line 99 of file chmsg.c.

References chMsgIsPendingI, chSchGoSleepS(), chSysLock, chSysUnlock, currp, fifo_remove(), Thread::p_state, THD_STATE_SNDMSG, and THD_STATE_WTMSG.

Here is the call graph for this function:

void chMsgRelease	(	Thread *	tp,
		msg_t	msg
	)

Releases a sender thread specifying a response message.

Precondition:

Invoke this function only after a message has been received using chMsgWait().

Parameters:

[in]	tp	pointer to the thread
[in]	msg	message to be returned to the sender

Function Class:

Normal API, this function can be invoked by regular system threads but not from within a lock zone.

Definition at line 121 of file chmsg.c.

References chDbgAssert, chMsgReleaseS, chSysLock, chSysUnlock, Thread::p_state, and THD_STATE_SNDMSG.

---

Define Documentation

#define chMsgIsPendingI

(

tp

)

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

Evaluates to TRUE if the thread has pending messages.

Function Class:

This is an I-Class API, this function can be invoked from within a system lock zone by both threads and interrupt handlers.

Definition at line 43 of file chmsg.h.

Referenced by chMsgWait().

#define chMsgGet

(

tp

)

((tp)->p_msg)

Returns the message carried by the specified thread.

Precondition:

This function must be invoked immediately after exiting a call to chMsgWait().

Parameters:

[in]

tp

pointer to the thread

Returns:

The message carried by the sender.

Function Class:

Normal API, this function can be invoked by regular system threads but not from within a lock zone.

Definition at line 56 of file chmsg.h.

#define chMsgReleaseS	(		tp,
			msg
	)		chSchWakeupS(tp, msg)

Releases the thread waiting on top of the messages queue.

Precondition:

Invoke this function only after a message has been received using chMsgWait().

Parameters:

[in]	tp	pointer to the thread
[in]	msg	message to be returned to the sender

Function Class:

This is an S-Class API, this function can be invoked from within a system lock zone by threads only.

Definition at line 68 of file chmsg.h.

Referenced by chMsgRelease().