Messaging / IPC

Messaging API for inter process communication. More...

Detailed Description

Messaging API for inter process communication.

Messages

IPC messages consist of a sender PID, a type, and some content. The sender PID will be set by the IPC internally and is not required to be set by the user. The type helps the receiver to multiplex different message types and should be set to a system-wide unique value. The content can either be provided as a 32-bit integer or a pointer.

Blocking vs non-blocking

Messages can be sent and received blocking and non-blocking. Both can be used combined: A message send while blocking the sender thread can be received with the non-blocking variant and vice-versa.

Blocking IPC

For the blocking variant use msg_send() or msg_receive() respectively.

Additionally, one can use msg_send_receive() to simultaneously block the sending thread and expect a response from the receiving thread. In this case, the receiving thread must use msg_reply() to reply to the message of the sender thread.

#include <inttypes.h>
#include <stdio.h>
#include "msg.h"
#include "thread.h"
static kernel_pid_t rcv_pid;
static char rcv_stack[THREAD_STACKSIZE_DEFAULT];
static void *rcv(void *arg)
{
msg_t msg_req, msg_resp;
(void)arg;
while (1) {
msg_receive(&msg_req);
msg_resp.content.value = msg_req.content.value + 1;
msg_reply(&msg_req, &msg_resp);
}
return NULL;
}
int main(void)
{
msg_t msg_req, msg_resp;
msg_resp.content.value = 0;
rcv_pid = thread_create(rcv_stack, sizeof(rcv_stack),
THREAD_PRIORITY_MAIN - 1, 0, rcv, NULL, "rcv");
while (1) {
msg_req.content.value = msg_resp.content.value;
msg_send_receive(&msg_req, &msg_resp, rcv_pid);
printf("Result: %" PRIu32 "\n", msg_resp.content.value);
}
return 0;
}

Non-blocking IPC

For the non-blocking variant use msg_try_send() or msg_try_receive() respectively. If a message is sent in synchronous mode or the message queue (see below) of the receiving thread is full messages sent this way will be dropped.

You can use the example on asynchronous IPC below - but without the queue - to get an impression of how to use non-blocking IPC.

Synchronous vs Asynchronous

RIOT's IPC supports both synchronous and asynchronous IPC.

Synchronous IPC

Synchronous IPC is the default mode i.e. is active when the receiving thread has no message queue initialized. Messages that can't be delivered when sending non-blocking (because the receiver already received a message) or which are sent when the receiver is not receive-blocked will be dropped.

Asynchronous IPC

To use asynchronous IPC one needs to initialize a message queue using msg_init_queue() (note that it must be of a size equal to a power of two). Messages sent to a thread with a message queue that isn't full are never dropped and the sending never blocks, even when using msg_send(). If the queue is full and the sending thread has a higher priority than the receiving thread the send-behavior is equivalent to synchronous mode.

#include <inttypes.h>
#include <stdio.h>
#include "msg.h"
#include "thread.h"
#define RCV_QUEUE_SIZE (8)
static kernel_pid_t rcv_pid;
static msg_t rcv_queue[RCV_QUEUE_SIZE];
static void *rcv(void *arg)
{
msg_t msg;
(void)arg;
msg_init_queue(rcv_queue, RCV_QUEUE_SIZE);
while (1) {
msg_receive(&msg);
printf("Received %" PRIu32 "\n", msg.content.value);
}
return NULL;
}
int main(void)
{
msg_t msg;
msg.content.value = 0;
rcv_pid = thread_create(rcv_stack, sizeof(rcv_stack),
THREAD_PRIORITY_MAIN - 1, 0, rcv, NULL, "rcv");
while (1) {
if (msg_try_send(&msg, rcv_pid) == 0) {
printf("Receiver queue full.\n");
}
msg.content.value++;
}
return 0;
}

Timing & messages

Timing out the reception of a message or sending messages at a certain time is out of scope for the basic IPC provided by the kernel. See the xtimer module on information for these functionalities.

Files

file  msg.h
 Messaging API for inter process communication.
 
file  msg_bus.h
 Messaging Bus API for inter process message broadcast.
 

Data Structures

struct  msg_t
 Describes a message object which can be sent between threads. More...
 

Macros

#define KERNEL_PID_ISR   (KERNEL_PID_LAST + 1)
 Value of msg_t::sender_pid if the sender was an interrupt service routine.
 

Functions

int msg_send (msg_t *m, kernel_pid_t target_pid)
 Send a message (blocking). More...
 
int msg_try_send (msg_t *m, kernel_pid_t target_pid)
 Send a message (non-blocking). More...
 
int msg_send_to_self (msg_t *m)
 Send a message to the current thread. More...
 
int msg_send_int (msg_t *m, kernel_pid_t target_pid)
 Send message from interrupt. More...
 
static int msg_sent_by_int (const msg_t *m)
 Test if the message was sent inside an ISR. More...
 
int msg_receive (msg_t *m)
 Receive a message. More...
 
int msg_try_receive (msg_t *m)
 Try to receive a message. More...
 
int msg_send_receive (msg_t *m, msg_t *reply, kernel_pid_t target_pid)
 Send a message, block until reply received. More...
 
int msg_reply (msg_t *m, msg_t *reply)
 Replies to a message. More...
 
int msg_reply_int (msg_t *m, msg_t *reply)
 Replies to a message from interrupt. More...
 
int msg_avail (void)
 Check how many messages are available in the message queue. More...
 
void msg_init_queue (msg_t *array, int num)
 Initialize the current thread's message queue. More...
 
void msg_queue_print (void)
 Prints the message queue of the current thread.
 

Function Documentation

◆ msg_avail()

int msg_avail ( void  )

Check how many messages are available in the message queue.

Returns
Number of messages available in our queue on success
-1, if no caller's message queue is initialized

◆ msg_init_queue()

void msg_init_queue ( msg_t array,
int  num 
)

Initialize the current thread's message queue.

Precondition
num MUST BE A POWER OF TWO!
Parameters
[in]arrayPointer to preallocated array of msg_t structures, must not be NULL.
[in]numNumber of msg_t structures in array. MUST BE POWER OF TWO!

◆ msg_receive()

int msg_receive ( msg_t m)

Receive a message.

This function blocks until a message was received.

Parameters
[out]mPointer to preallocated msg_t structure, must not be NULL.
Returns
1, Function always succeeds or blocks forever.

◆ msg_reply()

int msg_reply ( msg_t m,
msg_t reply 
)

Replies to a message.

Sender must have sent the message with msg_send_receive().

Parameters
[in]mmessage to reply to, must not be NULL.
[out]replymessage that target will get as reply, must not be NULL.
Returns
1, if successful
-1, on error

◆ msg_reply_int()

int msg_reply_int ( msg_t m,
msg_t reply 
)

Replies to a message from interrupt.

An ISR can obviously not receive messages, however a thread might delegate replying to a message to an ISR.

Parameters
[in]mmessage to reply to, must not be NULL.
[out]replymessage that target will get as reply, must not be NULL.
Returns
1, if successful
-1, on error

◆ msg_send()

int msg_send ( msg_t m,
kernel_pid_t  target_pid 
)

Send a message (blocking).

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.

Parameters
[in]mPointer to preallocated msg_t structure, must not be NULL.
[in]target_pidPID of target thread
Returns
1, if sending was successful (message delivered directly or to a queue)
0, if called from ISR and receiver cannot receive the message now (it is not waiting or it's message queue is full)
-1, on error (invalid PID)

◆ msg_send_int()

int msg_send_int ( msg_t m,
kernel_pid_t  target_pid 
)

Send message from interrupt.

Will be automatically chosen instead of msg_send() if called from an interrupt/ISR.

The value of m->sender_pid is set to KERNEL_PID_ISR.

See also
msg_sent_by_int()
Parameters
[in]mPointer to preallocated msg_t structure, must not be NULL.
[in]target_pidPID of target thread.
Returns
1, if sending was successful
0, if receiver is not waiting and block == 0
-1, on error (invalid PID)

◆ msg_send_receive()

int msg_send_receive ( msg_t m,
msg_t reply,
kernel_pid_t  target_pid 
)

Send a message, block until reply received.

This function sends a message to target_pid and then blocks until target has sent a reply which is then stored in reply.

Precondition
target_pid is not the PID of the current thread.
Parameters
[in]mPointer to preallocated msg_t structure with the message to send, must not be NULL.
[out]replyPointer to preallocated msg. Reply will be written here, must not be NULL. Can be identical to m.
[in]target_pidThe PID of the target process
Returns
1, if successful.

◆ msg_send_to_self()

int msg_send_to_self ( msg_t m)

Send a message to the current thread.

Will work only if the thread has a message queue.

Will be automatically chosen instead of msg_send if target_pid == thread_pid. This function never blocks.

Parameters
mpointer to message structure
Returns
1 if sending was successful
0 if the thread's message queue is full (or inexistent)

◆ msg_sent_by_int()

static int msg_sent_by_int ( const msg_t m)
inlinestatic

Test if the message was sent inside an ISR.

See also
msg_send_int()
Parameters
[in]mThe message in question.
Returns
== 0 if not sent by an ISR
!= 0 if sent by an ISR

Definition at line 283 of file msg.h.

◆ msg_try_receive()

int msg_try_receive ( msg_t m)

Try to receive a message.

This function does not block if no message can be received.

Parameters
[out]mPointer to preallocated msg_t structure, must not be NULL.
Returns
1, if a message was received
-1, otherwise.

◆ msg_try_send()

int msg_try_send ( msg_t m,
kernel_pid_t  target_pid 
)

Send a message (non-blocking).

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. This function will never block.

Parameters
[in]mPointer to preallocated msg_t structure, must not be NULL.
[in]target_pidPID of target thread
Returns
1, if sending was successful (message delivered directly or to a queue)
0, if receiver is not waiting or has a full message queue
-1, on error (invalid PID)
kernel_pid_t
int16_t kernel_pid_t
Unique process identifier.
Definition: sched.h:125
msg_send_receive
int msg_send_receive(msg_t *m, msg_t *reply, kernel_pid_t target_pid)
Send a message, block until reply received.
thread_create
kernel_pid_t thread_create(char *stack, int stacksize, uint8_t priority, int flags, thread_task_func_t task_func, void *arg, const char *name)
Creates a new thread.
msg_init_queue
void msg_init_queue(msg_t *array, int num)
Initialize the current thread's message queue.
THREAD_STACKSIZE_DEFAULT
#define THREAD_STACKSIZE_DEFAULT
A reasonable default stack size that will suffice most smaller tasks.
Definition: thread.h:211
msg.h
Messaging API for inter process communication.
THREAD_EXTRA_STACKSIZE_PRINTF
#define THREAD_EXTRA_STACKSIZE_PRINTF
Size of the task's printf stack in bytes.
Definition: thread.h:239
msg_reply
int msg_reply(msg_t *m, msg_t *reply)
Replies to a message.
msg_try_send
int msg_try_send(msg_t *m, kernel_pid_t target_pid)
Send a message (non-blocking).
msg_t::content
union msg_t::@2 content
Content of the message.
msg_receive
int msg_receive(msg_t *m)
Receive a message.
msg_t::value
uint32_t value
Value content field.
Definition: msg.h:191
msg_t
Describes a message object which can be sent between threads.
Definition: msg.h:185
inttypes.h
Adds include for missing inttype definitions.
THREAD_PRIORITY_MAIN
#define THREAD_PRIORITY_MAIN
Priority of the main thread.
Definition: thread.h:303