Inter-thread communication

The previous chapter discussed synchronization between threads, and mentioned concepts such as semaphores, mutexes, and event sets; this chapter continues the content of the previous chapter and explains inter-thread communication. In bare metal programming, global variables are often used for communication between functions. For example, some functions may change the value of a global variable due to some operations, and another function reads this global variable and performs corresponding actions based on the read global variable value to achieve the purpose of communication and collaboration. RT-Thread provides more tools to help pass information between different threads, and this chapter will introduce these tools in detail. After studying this chapter, you will learn how to use mailboxes, message queues, and signals for communication between threads.

Mail

Mailbox service is a typical inter-thread communication method in real-time operating systems. For example, there are two threads. Thread 1 detects the key status and sends it, while Thread 2 reads the key status and changes the LED on and off accordingly. Here, the mailbox method can be used for communication. Thread 1 sends the key status as an email to the mailbox, and Thread 2 reads the email in the mailbox to obtain the key status and turns the LED on and off.

Thread 1 here can also be expanded into multiple threads. For example, there are three threads in total, thread 1 detects and sends the key status, thread 2 detects and sends ADC sampling information, and thread 3 performs different operations according to the type of information received.

How Mailbox works

The mailbox of the RT-Thread operating system is used for inter-thread communication, which is characterized by low overhead and high efficiency. Each email in the mailbox can only hold a fixed 4-byte content (for a 32-bit processing system, the size of a pointer is 4 bytes, so one email can hold just one pointer). A typical mailbox is also called an exchange message. As shown in the figure below, a thread or interrupt service routine sends a 4-byte email to the mailbox, and one or more threads can receive and process these emails from the mailbox.

The non-blocking mail sending process can be safely applied to interrupt services. It is an effective means for threads, interrupt services, and timers to send messages to threads. Generally speaking, the mail receiving process may be blocking, depending on whether there are mails in the mailbox and the timeout set when receiving mails. When there are no mails in the mailbox and the timeout is not 0, the mail receiving process will become blocking. In this case, only threads can receive mails.

When a thread sends mail to a mailbox, if the mailbox is not full, the mail will be copied to the mailbox. If the mailbox is full, the sending thread can set a timeout, choose to wait and suspend, or directly return - RT_EFULL. If the sending thread chooses to suspend and wait, then when the mail in the mailbox is collected and space is freed up, the waiting and suspended sending thread will be awakened to continue sending.

When a thread receives mail from a mailbox, if the mailbox is empty, the receiving thread can choose whether to wait and suspend until a new mail is received and wake up, or set a timeout. When the set timeout is reached and the mailbox still does not receive mail, the thread that chooses to timeout will be woken up and return - RT_ETIMEOUT. If there is mail in the mailbox, the receiving thread will copy the 4-byte mail in the mailbox to the receiving buffer.

Mailbox Control Block

In RT-Thread, the mailbox control block is a data structure used by the operating system to manage mailboxes, represented by the structure struct rt_mailbox. Another C expression, rt_mailbox_t, represents the handle of the mailbox, which is implemented in C language as a pointer to the mailbox control block. For the detailed definition of the mailbox control block structure, please see the following code:

struct rt_mailbox
{
    struct rt_ipc_object parent;

    rt_uint32_t* msg_pool;                /* 邮箱缓冲区的开始地址 */
    rt_uint16_t size;                     /* 邮箱缓冲区的大小     */

    rt_uint16_t entry;                    /* 邮箱中邮件的数目     */
    rt_uint16_t in_offset, out_offset;    /* 邮箱缓冲的进出指针   */
    rt_list_t suspend_sender_thread;      /* 发送线程的挂起等待队列 */
};
typedef struct rt_mailbox* rt_mailbox_t;copymistakeCopy Success

The rt_mailbox object is derived from rt_ipc_object and is managed by the IPC container.

How to manage mailboxes

The mailbox control block is a structure that contains important parameters related to events and plays an important role in the implementation of mailbox functions. The mailbox-related interface is shown in the figure below. The operations on a mailbox include: creating/initializing a mailbox, sending mail, receiving mail, and deleting/leaving a mailbox.

Creating and Deleting Mailboxes

To dynamically create a mailbox object, you can call the following function interface:

rt_mailbox_t rt_mb_create (const char* name, rt_size_t size, rt_uint8_t flag);copymistakeCopy Success

When creating a mailbox object, a mailbox object will be allocated from the object manager first, and then a memory space will be dynamically allocated to the mailbox to store mails. The size of this memory is equal to the product of the mail size (4 bytes) and the capacity of the mailbox. Then the number of received mails and the offset of the sent mails in the mailbox are initialized. The following table describes the input parameters and return values ​​of this function:

Note

Note: RT_IPC_FLAG_FIFO is a non-real-time scheduling method. Unless the application is very concerned about first-come-first-served, and you clearly understand that all threads involving the mailbox will become non-real-time threads, you can use RT_IPC_FLAG_FIFO. Otherwise, it is recommended to use RT_IPC_FLAG_PRIO, that is, to ensure the real-time nature of the thread.

When a mailbox created with rt_mb_create() is no longer in use, it should be deleted to free up the corresponding system resources. Once the operation is completed, the mailbox will be permanently deleted. The function interface for deleting a mailbox is as follows:

rt_err_t rt_mb_delete (rt_mailbox_t mb);copymistakeCopy Success

When deleting a mailbox, if a thread is suspended on the mailbox object, the kernel first wakes up all threads suspended on the mailbox (the thread return value is -RT_ERROR), then releases the memory used by the mailbox, and finally deletes the mailbox object. The following table describes the input parameters and return values ​​of this function:

Initializing and uninitializing a mailbox

Initializing a mailbox is similar to creating a mailbox, except that it is used to initialize static mailbox objects. Unlike creating a mailbox, the memory of a static mailbox object is allocated by the compiler when the system is compiled, and is generally placed in the read-write data segment or the uninitialized data segment. The rest of the initialization work is the same as when creating a mailbox. The function interface is as follows:

  rt_err_t rt_mb_init(rt_mailbox_t mb,
                    const char* name,
                    void* msgpool,
                    rt_size_t size,
                    rt_uint8_t flag)copymistakeCopy Success

When initializing a mailbox, the function interface needs to obtain the mailbox object control block that the user has applied for, the pointer to the buffer, the mailbox name, and the mailbox capacity (the number of emails that can be stored). The following table describes the input parameters and return values ​​of the function:

The size parameter here specifies the capacity of the mailbox, that is, if the number of bytes of the buffer pointed to by msgpool is N, then the capacity of the mailbox should be N/4.

Detaching a mailbox will detach the statically initialized mailbox object from the kernel object manager. Detaching a mailbox uses the following interface:

rt_err_t rt_mb_detach(rt_mailbox_t mb);copymistakeCopy Success

After using this function interface, the kernel first wakes up all threads hanging on the mailbox (the thread gets the return value - RT_ERROR), and then detaches the mailbox object from the kernel object manager. The following table describes the input parameters and return values ​​of this function:

Send Email

A thread or interrupt service program can send emails to other threads through the mailbox. The email sending function interface is as follows:

rt_err_t rt_mb_send (rt_mailbox_t mb, rt_uint32_t value);copymistakeCopy Success

The mail sent can be 32-bit data in any format, an integer value or a pointer to a buffer. When the mailbox is full, the thread or interrupt program that sends the mail will receive a return value of -RT_EFULL. The following table describes the input parameters and return values ​​of this function:

Waiting mode to send mail

Users can also send emails to the specified mailbox through the following function interface:

rt_err_t rt_mb_send_wait (rt_mailbox_t mb,
                      rt_uint32_t value,
                      rt_int32_t timeout);copymistakeCopy Success

The difference between rt_mb_send_wait() and rt_mb_send() is that there is a waiting time. If the mailbox is full, the sending thread will wait for the mailbox to be freed up due to receiving mail according to the set timeout parameter. If the set timeout period is reached and there is still no free space, the sending thread will be awakened and return an error code. The following table describes the input parameters and return values ​​of this function:

Send urgent email

The process of sending an urgent email is almost the same as sending an email. The only difference is that when sending an urgent email, the email is directly inserted into the queue and placed at the head of the email queue. In this way, the recipient can receive the urgent email first and process it in time. The function interface for sending an urgent email is as follows:

rt_err_t rt_mb_urgent (rt_mailbox_t mb, rt_ubase_t value);copymistakeCopy Success

The following table describes the input parameters and return values ​​of this function:

incoming mail

Only when there is mail in the mailbox, the receiver can get the mail immediately and return the return value of RT_EOK. Otherwise, the receiving thread will be suspended in the waiting thread queue of the mailbox or return directly according to the timeout setting. The receiving mail function interface is as follows:

rt_err_t rt_mb_recv (rt_mailbox_t mb, rt_uint32_t* value, rt_int32_t timeout);copymistakeCopy Success

When receiving mail, the recipient needs to specify the mailbox handle for receiving mail, the storage location of the received mail, and the maximum waiting time. If the timeout is set when receiving, if the mail is still not received within the specified time, - RT_ETIMEOUT will be returned. The following table describes the input parameters and return values ​​of this function:

Mailbox usage examples

This is a mailbox application routine, which initializes two static threads and a static mailbox object. One thread sends mail to the mailbox, and the other thread receives mail from the mailbox. The code is as follows:

Mailbox usage routine

Note: RT-Thread 5.0 and later versions have ALIGNchanged the keyword to rt_align, so please pay attention to the modification when using it.

#include <rtthread.h>

#define THREAD_PRIORITY      10
#define THREAD_TIMESLICE     5

/* 邮箱控制块 */
static struct rt_mailbox mb;
/* 用于放邮件的内存池 */
static char mb_pool[128];

static char mb_str1[] = "I'm a mail!";
static char mb_str2[] = "this is another mail!";
static char mb_str3[] = "over";

ALIGN(RT_ALIGN_SIZE)
static char thread1_stack[1024];
static struct rt_thread thread1;

/* 线程 1 入口 */
static void thread1_entry(void *parameter)
{
    char *str;

    while (1)
    {
        rt_kprintf("thread1: try to recv a mail\n");

        /* 从邮箱中收取邮件 */
        if (rt_mb_recv(&mb, (rt_uint32_t *)&str, RT_WAITING_FOREVER) == RT_EOK)
        {
            rt_kprintf("thread1: get a mail from mailbox, the content:%s\n", str);
            if (str == mb_str3)
                break;

            /* 延时 100ms */
            rt_thread_mdelay(100);
        }
    }
    /* 执行邮箱对象脱离 */
    rt_mb_detach(&mb);
}

ALIGN(RT_ALIGN_SIZE)
static char thread2_stack[1024];
static struct rt_thread thread2;

/* 线程 2 入口 */
static void thread2_entry(void *parameter)
{
    rt_uint8_t count;

    count = 0;
    while (count < 10)
    {
        count ++;
        if (count & 0x1)
        {
            /* 发送 mb_str1 地址到邮箱中 */
            rt_mb_send(&mb, (rt_uint32_t)&mb_str1);
        }
        else
        {
            /* 发送 mb_str2 地址到邮箱中 */
            rt_mb_send(&mb, (rt_uint32_t)&mb_str2);
        }

        /* 延时 200ms */
        rt_thread_mdelay(200);
    }

    /* 发送邮件告诉线程 1，线程 2 已经运行结束 */
    rt_mb_send(&mb, (rt_uint32_t)&mb_str3);
}

int mailbox_sample(void)
{
    rt_err_t result;

    /* 初始化一个 mailbox */
    result = rt_mb_init(&mb,
                        "mbt",                      /* 名称是 mbt */
                        &mb_pool[0],                /* 邮箱用到的内存池是 mb_pool */
                        sizeof(mb_pool) / 4,        /* 邮箱中的邮件数目，因为一封邮件占 4 字节 */
                        RT_IPC_FLAG_FIFO);          /* 采用 FIFO 方式进行线程等待 */
    if (result != RT_EOK)
    {
        rt_kprintf("init mailbox failed.\n");
        return -1;
    }

    rt_thread_init(&thread1,
                   "thread1",
                   thread1_entry,
                   RT_NULL,
                   &thread1_stack[0],
                   sizeof(thread1_stack),
                   THREAD_PRIORITY, THREAD_TIMESLICE);
    rt_thread_startup(&thread1);

    rt_thread_init(&thread2,
                   "thread2",
                   thread2_entry,
                   RT_NULL,
                   &thread2_stack[0],
                   sizeof(thread2_stack),
                   THREAD_PRIORITY, THREAD_TIMESLICE);
    rt_thread_startup(&thread2);
    return 0;
}

/* 导出到 msh 命令列表中 */
MSH_CMD_EXPORT(mailbox_sample, mailbox sample);copymistakeCopy Success

The simulation results are as follows:

 \ | /
- RT -     Thread Operating System
 / | \     3.1.0 build Aug 27 2018
 2006 - 2018 Copyright by rt-thread team
msh >mailbox_sample
thread1: try to recv a mail
thread1: get a mail from mailbox, the content:I'm a mail!
msh >thread1: try to recv a mail
thread1: get a mail from mailbox, the content:this is another mail!
…
thread1: try to recv a mail
thread1: get a mail from mailbox, the content:this is another mail!
thread1: try to recv a mail
thread1: get a mail from mailbox, the content:overcopymistakeCopy Success

The example demonstrates how to use the mailbox. Thread 2 sends mails, a total of 11 times; Thread 1 receives mails, a total of 11 mails are received, the mail content is printed out, and the process is judged to be finished.

Mailbox usage scenarios

Mailbox is a simple way to pass messages between threads, which is characterized by low overhead and high efficiency. In the implementation of RT-Thread operating system, one 4-byte email can be delivered at a time, and the mailbox has certain storage functions and can cache a certain number of emails (the number of emails is determined by the capacity specified when the mailbox is created and initialized). The maximum length of an email in the mailbox is 4 bytes, so the mailbox can be used to pass messages of no more than 4 bytes. Since 4 bytes of content on a 32-bit system can just hold a pointer, when a larger message needs to be passed between threads, a pointer to a buffer can be sent to the mailbox as an email, that is, the mailbox can also pass pointers, for example:

struct msg
{
    rt_uint8_t *data_ptr;
    rt_uint32_t data_size;
};copymistakeCopy Success

For such a message structure, which contains the pointer data_ptr pointing to the data and the variable data_size of the data block length, when a thread needs to send this message to another thread, it can use the following operations:

struct msg* msg_ptr;

msg_ptr = (struct msg*)rt_malloc(sizeof(struct msg));
msg_ptr->data_ptr = ...; /* 指向相应的数据块地址 */
msg_ptr->data_size = len; /* 数据块的长度 */
/* 发送这个消息指针给 mb 邮箱 */
rt_mb_send(mb, (rt_uint32_t)msg_ptr);copymistakeCopy Success

In the receiving thread, because what is received is a pointer, and msg_ptr is a newly allocated memory block, the corresponding memory block needs to be released after the receiving thread completes the processing:

struct msg* msg_ptr;
if (rt_mb_recv(mb, (rt_uint32_t*)&msg_ptr) == RT_EOK)
{
    /* 在接收线程处理完毕后，需要释放相应的内存块 */
    rt_free(msg_ptr);
}copymistakeCopy Success

Message Queues

Message queue is another common way of communication between threads, which is an extension of mailbox. It can be applied in many occasions: message exchange between threads, receiving variable-length data through serial port, etc.

How message queues work

The message queue can receive messages of unfixed length from threads or interrupt service routines and cache the messages in its own memory space. Other threads can also read corresponding messages from the message queue, and when the message queue is empty, the reading thread can be suspended. When a new message arrives, the suspended thread will be awakened to receive and process the message. The message queue is an asynchronous communication method.

As shown in the figure below, a thread or an interrupt service routine can put one or more messages into a message queue. Similarly, one or more threads can get messages from a message queue. When there are multiple messages sent to a message queue, the message that enters the message queue first is usually passed to the thread first. In other words, the thread gets the message that enters the message queue first, which is the first-in-first-out principle (FIFO).

The message queue object of the RT-Thread operating system consists of multiple elements. When a message queue is created, it is assigned a message queue control block: message queue name, memory buffer, message size, and queue length, etc. At the same time, each message queue object contains multiple message boxes, each of which can store a message; the first and last message boxes in the message queue are called the message list head and message list tail, respectively, corresponding to msg_queue_head and msg_queue_tail in the message queue control block; some message boxes may be empty, and they form a free message box list through msg_queue_free. The total number of message boxes in all message queues is the length of the message queue, which can be specified when the message queue is created.

Message Queue Control Block

In RT-Thread, the message queue control block is a data structure used by the operating system to manage the message queue, represented by the structure struct rt_messagequeue. Another C expression rt_mq_t represents the handle of the message queue, which is implemented in C language as a pointer to the message queue control block. For the detailed definition of the message queue control block structure, please see the following code:

struct rt_messagequeue
{
    struct rt_ipc_object parent;

    void* msg_pool;                     /* 指向存放消息的缓冲区的指针 */

    rt_uint16_t msg_size;               /* 每个消息的长度 */
    rt_uint16_t max_msgs;               /* 最大能够容纳的消息数 */

    rt_uint16_t entry;                  /* 队列中已有的消息数 */

    void* msg_queue_head;               /* 消息链表头 */
    void* msg_queue_tail;               /* 消息链表尾 */
    void* msg_queue_free;               /* 空闲消息链表 */

    rt_list_t suspend_sender_thread;    /* 发送线程的挂起等待队列 */
};
typedef struct rt_messagequeue* rt_mq_t;copymistakeCopy Success

The rt_messagequeue object is derived from rt_ipc_object and is managed by the IPC container.