Event

Event 的协作图:

结构体
struct	rt_event

宏定义
#define	RT_EVENT_FLAG_AND   0x01
#define	RT_EVENT_FLAG_OR   0x02
#define	RT_EVENT_FLAG_CLEAR   0x04

类型定义
typedef struct rt_event *	rt_event_t

函数
rt_err_t	rt_event_init (rt_event_t event, const char *name, rt_uint8_t flag)
	RTM_EXPORT (rt_event_init)
rt_err_t	rt_event_detach (rt_event_t event)
	RTM_EXPORT (rt_event_detach)
rt_event_t	rt_event_create (const char *name, rt_uint8_t flag)
	RTM_EXPORT (rt_event_create)
rt_err_t	rt_event_delete (rt_event_t event)
	RTM_EXPORT (rt_event_delete)
rt_err_t	rt_event_send (rt_event_t event, rt_uint32_t set)
	RTM_EXPORT (rt_event_send)
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)
	RTM_EXPORT (rt_event_recv)
rt_err_t	rt_event_recv_interruptible (rt_event_t event, rt_uint32_t set, rt_uint8_t option, rt_int32_t timeout, rt_uint32_t *recved)
	RTM_EXPORT (rt_event_recv_interruptible)
rt_err_t	rt_event_recv_killable (rt_event_t event, rt_uint32_t set, rt_uint8_t option, rt_int32_t timeout, rt_uint32_t *recved)
	RTM_EXPORT (rt_event_recv_killable)
rt_err_t	rt_event_control (rt_event_t event, int cmd, void *arg)
	RTM_EXPORT (rt_event_control)

详细描述

宏定义说明

RT_EVENT_FLAG_AND

#define RT_EVENT_FLAG_AND   0x01

flag definitions in event logic and

在文件 rtdef.h 第 1051 行定义.

RT_EVENT_FLAG_OR

#define RT_EVENT_FLAG_OR   0x02

logic or

在文件 rtdef.h 第 1052 行定义.

RT_EVENT_FLAG_CLEAR

#define RT_EVENT_FLAG_CLEAR   0x04

clear flag

在文件 rtdef.h 第 1053 行定义.

类型定义说明

rt_event_t

typedef struct rt_event* rt_event_t

在文件 rtdef.h 第 1065 行定义.

函数说明

rt_event_init()

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

The function will initialize a static event object.

注解

For the static event object, its memory space is allocated by the compiler during compiling, and shall placed on the read-write data segment or on the uninitialized data segment. By contrast, the rt_event_create() function will allocate memory space automatically and initialize the event.

参见

rt_event_create()

参数

event	is a pointer to the event to initialize. It is assumed that storage for the event will be allocated in your application.
name	is a pointer to the name that given to the event.
flag	is the event flag, which determines the queuing way of how multiple threads wait when the event is not available. The event flag can be ONE of the following values: RT_IPC_FLAG_PRIO The pending threads will queue in order of priority. RT_IPC_FLAG_FIFO The pending threads will queue in the first-in-first-out method (also known as first-come-first-served (FCFS) scheduling strategy). NOTE: RT_IPC_FLAG_FIFO is a non-real-time scheduling mode. It is strongly recommended to use RT_IPC_FLAG_PRIO to ensure the thread is real-time UNLESS your applications concern about the first-in-first-out principle, and you clearly understand that all threads involved in this event will become non-real-time threads.

返回

Return the operation status. When the return value is RT_EOK, the initialization is successful. If the return value is any other values, it represents the initialization failed.

警告

This function can ONLY be called from threads.

在文件 ipc.c 第 1786 行定义.

{
    /* parameter check */
    RT_ASSERT(event != RT_NULL);
    RT_ASSERT((flag == RT_IPC_FLAG_FIFO) || (flag == RT_IPC_FLAG_PRIO));
 
    /* initialize object */
    rt_object_init(&(event->parent.parent), RT_Object_Class_Event, name);
 
    /* set parent flag */
    event->parent.parent.flag = flag;
 
    /* initialize ipc object */
    _ipc_object_init(&(event->parent));
 
    /* initialize event */
    event->set = 0;
    rt_spin_lock_init(&(event->spinlock));
 
    return RT_EOK;
}

引用了 _ipc_object_init(), rt_event::parent, rt_ipc_object::parent, RT_ASSERT, RT_IPC_FLAG_FIFO, RT_IPC_FLAG_PRIO, RT_NULL, RT_Object_Class_Event, rt_object_init(), rt_spin_lock_init() , 以及 rt_event::spinlock.

函数调用图:

这是这个函数的调用关系图:

RTM_EXPORT() [1/9]

RTM_EXPORT

(

rt_event_init

)

引用了 rt_event_init().

函数调用图:

rt_event_detach()

rt_err_t rt_event_detach

(

rt_event_t

event

)

This function will detach a static event object.

注解

This function is used to detach a static event object which is initialized by rt_event_init() function. By contrast, the rt_event_delete() function will delete an event object. When the event is successfully detached, it will resume all suspended threads in the event list.

参见

rt_event_delete()

参数

event

is a pointer to an event object to be detached.

返回

Return the operation status. When the return value is RT_EOK, the initialization is successful. If the return value is any other values, it means that the event detach failed.

警告

This function can ONLY detach a static event initialized by the rt_event_init() function. If the event is created by the rt_event_create() function, you MUST NOT USE this function to detach it, ONLY USE the rt_event_delete() function to complete the deletion.

在文件 ipc.c 第 1828 行定义.

{
    rt_base_t level;
 
    /* parameter check */
    RT_ASSERT(event != RT_NULL);
    RT_ASSERT(rt_object_get_type(&event->parent.parent) == RT_Object_Class_Event);
    RT_ASSERT(rt_object_is_systemobject(&event->parent.parent));
 
    level = rt_spin_lock_irqsave(&(event->spinlock));
    /* resume all suspended thread */
    rt_susp_list_resume_all(&(event->parent.suspend_thread), RT_ERROR);
    rt_spin_unlock_irqrestore(&(event->spinlock), level);
 
    /* detach event object */
    rt_object_detach(&(event->parent.parent));
 
    return RT_EOK;
}

引用了 rt_event::parent, rt_ipc_object::parent, RT_ASSERT, RT_NULL, RT_Object_Class_Event, rt_object_detach(), rt_object_get_type(), rt_object_is_systemobject(), rt_spin_lock_irqsave(), rt_spin_unlock_irqrestore(), rt_susp_list_resume_all(), rt_event::spinlock , 以及 rt_ipc_object::suspend_thread.

函数调用图:

这是这个函数的调用关系图:

RTM_EXPORT() [2/9]

RTM_EXPORT

(

rt_event_detach

)

引用了 rt_event_detach().

函数调用图:

rt_event_create()

rt_event_t rt_event_create	(	const char *	name,
		rt_uint8_t	flag )

Creating an event object.

注解

For the event object, its memory space is allocated automatically. By contrast, the rt_event_init() function will initialize a static event object.

参见

rt_event_init()

参数

name

is a pointer to the name that given to the event.

flag

is the event flag, which determines the queuing way of how multiple threads wait when the event is not available. The event flag can be ONE of the following values: RT_IPC_FLAG_PRIO The pending threads will queue in order of priority. RT_IPC_FLAG_FIFO The pending threads will queue in the first-in-first-out method (also known as first-come-first-served (FCFS) scheduling strategy). NOTE: RT_IPC_FLAG_FIFO is a non-real-time scheduling mode. It is strongly recommended to use RT_IPC_FLAG_PRIO to ensure the thread is real-time UNLESS your applications concern about the first-in-first-out principle, and you clearly understand that all threads involved in this event will become non-real-time threads.

返回

Return a pointer to the event object. When the return value is RT_NULL, it means the creation failed.

警告

This function can ONLY be called from threads.

在文件 ipc.c 第 1878 行定义.

{
    rt_event_t event;
 
    RT_ASSERT((flag == RT_IPC_FLAG_FIFO) || (flag == RT_IPC_FLAG_PRIO));
 
    RT_DEBUG_NOT_IN_INTERRUPT;
 
    /* allocate object */
    event = (rt_event_t)rt_object_allocate(RT_Object_Class_Event, name);
    if (event == RT_NULL)
        return event;
 
    /* set parent */
    event->parent.parent.flag = flag;
 
    /* initialize ipc object */
    _ipc_object_init(&(event->parent));
 
    /* initialize event */
    event->set = 0;
    rt_spin_lock_init(&(event->spinlock));
 
    return event;
}

引用了 _ipc_object_init(), rt_object::flag, rt_event::parent, rt_ipc_object::parent, RT_ASSERT, RT_DEBUG_NOT_IN_INTERRUPT, RT_IPC_FLAG_FIFO, RT_IPC_FLAG_PRIO, RT_NULL, rt_object_allocate(), RT_Object_Class_Event, rt_spin_lock_init() , 以及 rt_event::spinlock.

函数调用图:

这是这个函数的调用关系图:

RTM_EXPORT() [3/9]

RTM_EXPORT

(

rt_event_create

)

引用了 rt_event_create().

函数调用图:

rt_event_delete()

rt_err_t rt_event_delete

(

rt_event_t

event

)

This function will delete an event object and release the memory space.

注解

This function is used to delete an event object which is created by the rt_event_create() function. By contrast, the rt_event_detach() function will detach a static event object. When the event is successfully deleted, it will resume all suspended threads in the event list.

参见

rt_event_detach()

参数

event

is a pointer to an event object to be deleted.

返回

Return the operation status. When the return value is RT_EOK, the operation is successful. If the return value is any other values, it means that the event detach failed.

警告

This function can ONLY delete an event initialized by the rt_event_create() function. If the event is initialized by the rt_event_init() function, you MUST NOT USE this function to delete it, ONLY USE the rt_event_detach() function to complete the detachment.

在文件 ipc.c 第 1924 行定义.

{
    /* parameter check */
    RT_ASSERT(event != RT_NULL);
    RT_ASSERT(rt_object_get_type(&event->parent.parent) == RT_Object_Class_Event);
    RT_ASSERT(rt_object_is_systemobject(&event->parent.parent) == RT_FALSE);
 
    RT_DEBUG_NOT_IN_INTERRUPT;
 
    rt_spin_lock(&(event->spinlock));
    /* resume all suspended thread */
    rt_susp_list_resume_all(&(event->parent.suspend_thread), RT_ERROR);
    rt_spin_unlock(&(event->spinlock));
 
    /* delete event object */
    rt_object_delete(&(event->parent.parent));
 
    return RT_EOK;
}

引用了 rt_event::parent, rt_ipc_object::parent, RT_ASSERT, RT_DEBUG_NOT_IN_INTERRUPT, RT_FALSE, RT_NULL, RT_Object_Class_Event, rt_object_delete(), rt_object_get_type(), rt_object_is_systemobject(), rt_spin_lock(), rt_spin_unlock(), rt_susp_list_resume_all(), rt_event::spinlock , 以及 rt_ipc_object::suspend_thread.

函数调用图:

这是这个函数的调用关系图:

RTM_EXPORT() [4/9]

RTM_EXPORT

(

rt_event_delete

)

引用了 rt_event_delete().

函数调用图:

rt_event_send()

rt_err_t rt_event_send	(	rt_event_t	event,
		rt_uint32_t	set )

This function will send an event to the event object. If there is a thread suspended on the event, the thread will be resumed.

注解

When using this function, you need to use the parameter (set) to specify the event flag of the event object, then the function will traverse the list of suspended threads waiting on the event object. If there is a thread suspended on the event, and the thread's event_info and the event flag of the current event object matches, the thread will be resumed.

参数

event	is a pointer to the event object to be sent.
set	is a flag that you will set for this event's flag. You can set an event flag, or you can set multiple flags through OR logic operation.

返回

Return the operation status. When the return value is RT_EOK, the operation is successful. If the return value is any other values, it means that the event detach failed.

在文件 ipc.c 第 1964 行定义.

{
    struct rt_list_node *n;
    struct rt_thread *thread;
    rt_sched_lock_level_t slvl;
    rt_base_t level;
    rt_base_t status;
    rt_bool_t need_schedule;
    rt_uint32_t need_clear_set = 0;
 
    /* parameter check */
    RT_ASSERT(event != RT_NULL);
    RT_ASSERT(rt_object_get_type(&event->parent.parent) == RT_Object_Class_Event);
 
    if (set == 0)
        return -RT_ERROR;
 
    need_schedule = RT_FALSE;
 
    level = rt_spin_lock_irqsave(&(event->spinlock));
 
    /* set event */
    event->set |= set;
 
    RT_OBJECT_HOOK_CALL(rt_object_put_hook, (&(event->parent.parent)));
 
    rt_sched_lock(&slvl);
    if (!rt_list_isempty(&event->parent.suspend_thread))
    {
        /* search thread list to resume thread */
        n = event->parent.suspend_thread.next;
        while (n != &(event->parent.suspend_thread))
        {
            /* get thread */
            thread = RT_THREAD_LIST_NODE_ENTRY(n);
 
            status = -RT_ERROR;
            if (thread->event_info & RT_EVENT_FLAG_AND)
            {
                if ((thread->event_set & event->set) == thread->event_set)
                {
                    /* received an AND event */
                    status = RT_EOK;
                }
            }
            else if (thread->event_info & RT_EVENT_FLAG_OR)
            {
                if (thread->event_set & event->set)
                {
                    /* save the received event set */
                    thread->event_set = thread->event_set & event->set;
 
                    /* received an OR event */
                    status = RT_EOK;
                }
            }
            else
            {
                rt_sched_unlock(slvl);
                rt_spin_unlock_irqrestore(&(event->spinlock), level);
 
                return -RT_EINVAL;
            }
 
            /* move node to the next */
            n = n->next;
 
            /* condition is satisfied, resume thread */
            if (status == RT_EOK)
            {
                /* clear event */
                if (thread->event_info & RT_EVENT_FLAG_CLEAR)
                    need_clear_set |= thread->event_set;
 
                /* resume thread, and thread list breaks out */
                rt_sched_thread_ready(thread);
                thread->error = RT_EOK;
 
                /* need do a scheduling */
                need_schedule = RT_TRUE;
            }
        }
        if (need_clear_set)
        {
            event->set &= ~need_clear_set;
        }
    }
 
    rt_sched_unlock(slvl);
    rt_spin_unlock_irqrestore(&(event->spinlock), level);
 
    /* do a schedule */
    if (need_schedule == RT_TRUE)
        rt_schedule();
 
    return RT_EOK;
}

引用了 rt_thread::error, rt_thread::event_info, rt_thread::event_set, rt_list_node::next, rt_event::parent, rt_ipc_object::parent, RT_ASSERT, RT_EVENT_FLAG_AND, RT_EVENT_FLAG_CLEAR, RT_EVENT_FLAG_OR, RT_FALSE, rt_list_isempty(), RT_NULL, RT_Object_Class_Event, rt_object_get_type(), RT_OBJECT_HOOK_CALL, rt_sched_lock(), rt_sched_thread_ready(), rt_sched_unlock(), rt_schedule(), rt_spin_lock_irqsave(), rt_spin_unlock_irqrestore(), RT_THREAD_LIST_NODE_ENTRY, RT_TRUE, rt_event::set, rt_event::spinlock , 以及 rt_ipc_object::suspend_thread.

函数调用图:

这是这个函数的调用关系图:

RTM_EXPORT() [5/9]

RTM_EXPORT

(

rt_event_send

)

引用了 RT_EVENT_FLAG_AND, rt_event_send(), RT_NULL, RT_Object_Class_Event , 以及 RT_TRUE.

函数调用图:

rt_event_recv()

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 )

在文件 ipc.c 第 2222 行定义.

{
    return _rt_event_recv(event, set, option, timeout, recved, RT_UNINTERRUPTIBLE);
}

引用了 RT_UNINTERRUPTIBLE.

这是这个函数的调用关系图:

RTM_EXPORT() [6/9]

RTM_EXPORT

(

rt_event_recv

)

引用了 rt_event_recv().

函数调用图:

rt_event_recv_interruptible()

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

在文件 ipc.c 第 2232 行定义.

{
    return _rt_event_recv(event, set, option, timeout, recved, RT_INTERRUPTIBLE);
}

引用了 RT_INTERRUPTIBLE.

这是这个函数的调用关系图:

RTM_EXPORT() [7/9]

RTM_EXPORT

(

rt_event_recv_interruptible

)

引用了 rt_event_recv_interruptible().

函数调用图:

rt_event_recv_killable()

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

在文件 ipc.c 第 2242 行定义.

{
    return _rt_event_recv(event, set, option, timeout, recved, RT_KILLABLE);
}

引用了 RT_KILLABLE.

这是这个函数的调用关系图:

RTM_EXPORT() [8/9]

RTM_EXPORT

(

rt_event_recv_killable

)

引用了 rt_event_recv_killable().

函数调用图:

rt_event_control()

rt_err_t rt_event_control	(	rt_event_t	event,
		int	cmd,
		void *	arg )

This function will set some extra attributions of an event object.

注解

Currently this function only supports the RT_IPC_CMD_RESET command to reset the event.

参数

event	is a pointer to an event object.
cmd	is a command word used to configure some attributions of the event.
arg	is the argument of the function to execute the command.

返回

Return the operation status. When the return value is RT_EOK, the operation is successful. If the return value is any other values, it means that this function failed to execute.

在文件 ipc.c 第 2265 行定义.

{
    rt_base_t level;
 
    RT_UNUSED(arg);
 
    /* parameter check */
    RT_ASSERT(event != RT_NULL);
    RT_ASSERT(rt_object_get_type(&event->parent.parent) == RT_Object_Class_Event);
 
    if (cmd == RT_IPC_CMD_RESET)
    {
        level = rt_spin_lock_irqsave(&(event->spinlock));
 
        /* resume all waiting thread */
        rt_susp_list_resume_all(&event->parent.suspend_thread, RT_ERROR);
 
        /* initialize event set */
        event->set = 0;
 
        rt_spin_unlock_irqrestore(&(event->spinlock), level);
 
        rt_schedule();
 
        return RT_EOK;
    }
 
    return -RT_ERROR;
}

引用了 rt_event::parent, rt_ipc_object::parent, RT_ASSERT, RT_IPC_CMD_RESET, RT_NULL, RT_Object_Class_Event, rt_object_get_type(), rt_schedule(), rt_spin_lock_irqsave(), rt_spin_unlock_irqrestore(), rt_susp_list_resume_all(), RT_UNUSED, rt_event::spinlock , 以及 rt_ipc_object::suspend_thread.

函数调用图:

这是这个函数的调用关系图:

RTM_EXPORT() [9/9]

RTM_EXPORT

(

rt_event_control

)

引用了 rt_event_control().

函数调用图: