RT_thread 事件集的使用

一、事件集工作机制

信号量主要用于“一对一”的线程同步；当需要“一对多”、“多对一”、“多对多”的同步时，就需要事件集来处理了；

RT_thread 中的事件集用一个32位无符号整型变量来表示，变量中一个位为代表一个事件，线程通过**“逻辑与”或者“逻辑或”**与一个或多个事件建立关联形成一个事件组合。

事件的**“逻辑或”也称为是独立型同步**，指的是线程与任何事件之一发生同步，只要有一个事件发生，即满足条件；

事件的**“逻辑与”也称为是关联型的同步**，指的是线程或若干事件同步发生，只有这些事件全部发生，才满足条件；

二、事件集控制块

rt_event_init : 静态初始化一个事件集（rt_event），注意这个事件集是全局变量
rt_event_detach : 当rt_event_init初始化的事件集不再使用时，脱离掉（反初始化），事件集变量还在，只是不能直接使用。
rt_event_create : 动态创建一个事件集，需要首先开启RT_USING_HEAP
rt_event_delete : 删除 rt_event_create动态创建的事件集，内存资源释放。
rt_event_send : 发送事件，可以是单一事件或一组事件的集合。可以在线程、中断回调等环境发送
rt_event_recv ：等待接收事件，可以设置超时，或一直等待RT_WAITING_FOREVER，事件集可以与、或，只有接收条件的事件，才会接收。注意接收时，需要需要判断返回值为：== RT_EOK。

事件集API	解释
rt_event_init	静态初始化一个事件集（rt_event），注意这个事件集是全局变量
rt_event_detach	当rt_event_init初始化的事件集不再使用时，脱离掉（反初始化），事件集变量还在，只是不能直接使用。
rt_event_create	动态创建一个事件集，需要首先开启 RT_USING_HEAP
rt_event_delete	删除 rt_event_create动态创建的事件集，内存资源释放。
rt_event_send	发送事件，可以是单一事件或一组事件的集合。可以在线程、中断回调等环境发送
rt_event_recv	等待接收事件，可以设置超时，或一直等待RT_WAITING_FOREVER，事件集可以与、或，只有接收条件的事件，才会接收。注意接收时，需要需要判断返回值为：== RT_EOK

解释API函数

1. 创建和删除
   静态创建事件集

rt_err_t rt_event_init(rt_event_t event, const char* name, rt_uint8_t flag);

参数	描述
event	事件集对象的句柄
name	事件集的名称
flag	事件集的标志，它可以取如下数值： RT_IPC_FLAG_FIFO 或 RT_IPC_FLAG_PRIO，建议采用 RT_IPC_FLAG_PRIO，即确保线程的实时性
返回	——
RT_EOK	成功

脱离事件

rt_err_t rt_event_detach(rt_event_t event);

参数	描述
event	事件集对象的句柄
返回	——
RT_EOK	成功

动态创建事件集

rt_event_t rt_event_create(const char* name, rt_uint8_t flag);

参数	描述
event	事件集对象的句柄
name	事件集的名称
flag	事件集的标志，它可以取如下数值： RT_IPC_FLAG_FIFO 或 RT_IPC_FLAG_PRIO，建议采用 RT_IPC_FLAG_PRIO，即确保线程的实时性
返回	——
RT_NULL	创建失败
事件对象的句柄	创建成功

rt_err_t rt_event_delete(rt_event_t event);

参数	描述
event	事件集对象的句柄
返回	——
RT_EOK	成功

2. 发送事件
   通过参数 set 指定的事件标志来设定 event 事件集对象的事件标志值，然后遍历等待在 event 事件集对象上的等待线程链表，判断是否有线程的事件激活要求与当前 event 对象事件标志值匹配，如果有，则唤醒该线程。

rt_err_t rt_event_send(rt_event_t event, rt_uint32_t set);

参数	描述
event	事件集对象的句柄
set	发送的一个或多个事件的标志值
返回	——
RT_EOK	成功

3. 接收事件
   根据 set 和 option 来判断它要接收的事件是否发生。
   如果已经发生，则根据参数 option 上是否设置有 RT_EVENT_FLAG_CLEAR 来决定是否重置事件的相应标志位，然后返回（其中 recved 参数返回接收到的事件）；
   如果没有发生，则把等待的 set 和 option 参数填入线程本身的结构中，然后把线程挂起在此事件上，直到其等待的事件满足条件或等待时间超时。

rt_err_t rt_event_recv(rt_event_t event,
                           rt_uint32_t set,
                           rt_uint8_t option,
                           rt_int32_t timeout,
                           rt_uint32_t* recved);

参数	描述
event	事件集对象的句柄
set	接收感兴趣的事件
option	接收选项：RT_EVENT_FLAG_OR逻辑或；RT_EVENT_FLAG_AND逻辑与；RT_EVENT_FLAG_CLEAR清除事件标志；
timeout	指定超时时间
recved	指向接收到的事件
返回	——
RT_EOK	成功
-RT_ETIMEOUT	超时
-RT_ERROR	错误

三、事件集代码

/* 
 * Copyright (c) 2006-2018, RT-Thread Development Team 
 * 
 * SPDX-License-Identifier: Apache-2.0 
 * 
 * Change Logs: 
 * Date           Author       Notes 
 * 2018-08-24     yangjie      the first version 
 */ 

/*
 * 程序清单：事件例程
 *
 * 程序会初始化2个线程及初始化一个静态事件对象
 * 一个线程等待于事件对象上，以接收事件；
 * 一个线程发送事件 (事件3/事件5)
*/
#include <rtthread.h>

#define THREAD_PRIORITY      9
#define THREAD_TIMESLICE     5

#define EVENT_FLAG3 (1 << 3)
#define EVENT_FLAG5 (1 << 5)

/* 事件控制块 */
static struct rt_event event;

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

/* 线程1入口函数 */
static void thread1_recv_event(void *param)
{
    rt_uint32_t e;

    /* 第一次接收事件，事件3或事件5任意一个可以触发线程1，接收完后清除事件标志 */
    if (rt_event_recv(&event, (EVENT_FLAG3 | EVENT_FLAG5),
                      RT_EVENT_FLAG_OR | RT_EVENT_FLAG_CLEAR,
                      RT_WAITING_FOREVER, &e) == RT_EOK)
    {
        rt_kprintf("thread1: OR recv event 0x%x\n", e);
    }

    rt_kprintf("thread1: delay 1s to prepare the second event\n");
    rt_thread_mdelay(1000);

    /* 第二次接收事件，事件3和事件5均发生时才可以触发线程1，接收完后清除事件标志 */
    if (rt_event_recv(&event, (EVENT_FLAG3 | EVENT_FLAG5),
                      RT_EVENT_FLAG_AND | RT_EVENT_FLAG_CLEAR,
                      RT_WAITING_FOREVER, &e) == RT_EOK)
    {
        rt_kprintf("thread1: AND recv event 0x%x\n", e);
    }
    rt_kprintf("thread1 leave.\n");
}


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

/* 线程2入口 */
static void thread2_send_event(void *param)
{
    rt_kprintf("thread2: send event3\n");
    rt_event_send(&event, EVENT_FLAG3);
    rt_thread_mdelay(200);

    rt_kprintf("thread2: send event5\n");
    rt_event_send(&event, EVENT_FLAG5);
    rt_thread_mdelay(200);

    rt_kprintf("thread2: send event3\n");
    rt_event_send(&event, EVENT_FLAG3);
    rt_kprintf("thread2 leave.\n");
}

int event_sample(void)
{
    rt_err_t result;

    /* 初始化事件对象 */
    result = rt_event_init(&event, "event", RT_IPC_FLAG_FIFO);
    if (result != RT_EOK)
    {
        rt_kprintf("init event failed.\n");
        return -1;
    }

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

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

    return 0;
}

/* 导出到 msh 命令列表中 */
MSH_CMD_EXPORT(event_sample, event sample);