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_CFG_USE_MESSAGES_PRIORITY option in chconf.h.

Precondition: In order to use the message APIs the CH_CFG_USE_MESSAGES option must be enabled in chconf.h.

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

Functions
msg_t	chMsgSend (thread_t *tp, msg_t msg)
	Sends a message to the specified thread. More...

thread_t *	chMsgWait (void)
	Suspends the thread and waits for an incoming message. More...

void	chMsgRelease (thread_t *tp, msg_t msg)
	Releases a sender thread specifying a response message. More...

static bool	chMsgIsPendingI (thread_t *tp)
	Evaluates to `true` if the thread has pending messages. More...

static msg_t	chMsgGet (thread_t *tp)
	Returns the message carried by the specified thread. More...

static void	chMsgReleaseS (thread_t *tp, msg_t msg)
	Releases the thread waiting on top of the messages queue. More...

Function Documentation

msg_t chMsgSend	(	thread_t *	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 87 of file chmsg.c.

References CH_STATE_SNDMSGQ, CH_STATE_WTMSG, chDbgCheck, chSchGoSleepS(), chSchReadyI(), chSysLock(), chSysUnlock(), currp, ch_thread::msgqueue, ch_thread::rdymsg, ch_thread::sentmsg, ch_thread::state, and ch_thread::u.

Here is the call graph for this function:

thread_t * 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.; The reference counter of the sender thread is not increased, the returned pointer is a temporary reference.

Returns: A pointer 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 121 of file chmsg.c.

References CH_STATE_SNDMSG, CH_STATE_WTMSG, chMsgIsPendingI(), chSchGoSleepS(), chSysLock(), chSysUnlock(), currp, queue_fifo_remove(), and ch_thread::state.

Here is the call graph for this function:

void chMsgRelease	(	thread_t *	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 145 of file chmsg.c.

References CH_STATE_SNDMSG, chDbgAssert, chMsgReleaseS(), chSysLock(), chSysUnlock(), and ch_thread::state.

Here is the call graph for this function:

static bool chMsgIsPendingI ( thread_t * tp )

inlinestatic

Evaluates to true if the thread has pending messages.

Parameters

[in] tp pointer to the thread

Returns: The pending messages status.

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 79 of file chmsg.h.

References chDbgCheckClassI(), ch_thread::msgqueue, and ch_threads_queue::next.

Referenced by chMsgWait().

Here is the call graph for this function:

static msg_t chMsgGet ( thread_t * tp )

inlinestatic

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 96 of file chmsg.h.

References CH_STATE_SNDMSG, chDbgAssert, ch_thread::sentmsg, ch_thread::state, and ch_thread::u.

static void chMsgReleaseS	(	thread_t *	tp,
		msg_t	msg
	)

inlinestatic

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 113 of file chmsg.h.

References chDbgCheckClassS(), and chSchWakeupS().

Referenced by chMsgRelease().

Here is the call graph for this function:

Detailed Description

Operation Mode

Functions

Function Documentation