Event

Collaboration diagram for Event:

Macros
#define	RT_EVENT_FLAG_AND   0x01
#define	RT_EVENT_FLAG_OR   0x02
#define	RT_EVENT_FLAG_CLEAR   0x04

Functions
rt_err_t	rt_event_init (rt_event_t event, const char *name, rt_uint8_t flag)
rt_err_t	rt_event_detach (rt_event_t event)
rt_event_t	rt_event_create (const char *name, rt_uint8_t flag)
rt_err_t	rt_event_delete (rt_event_t event)
rt_err_t	rt_event_send (rt_event_t event, rt_uint32_t set)
rt_err_t	rt_event_control (rt_event_t event, int cmd, void *arg)

Detailed Description

Macro Definition Documentation

RT_EVENT_FLAG_AND

#define RT_EVENT_FLAG_AND   0x01

flag definitions in event logic and

RT_EVENT_FLAG_OR

#define RT_EVENT_FLAG_OR   0x02

logic or

RT_EVENT_FLAG_CLEAR

#define RT_EVENT_FLAG_CLEAR   0x04

clear flag

Function Documentation

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.

Note

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.

See also

rt_event_create()

Parameters

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.

Returns

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.

Warning

This function can ONLY be called from threads.

rt_event_detach()

rt_err_t rt_event_detach

(

rt_event_t

event

)

This function will detach a static event object.

Note

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.

See also

rt_event_delete()

Parameters

event

is a pointer to an event object to be detached.

Returns

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.

Warning

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.

rt_event_create()

rt_event_t rt_event_create	(	const char *	name,
		rt_uint8_t	flag
	)

Creating an event object.

Note

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

See also

rt_event_init()

Parameters

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.

Returns

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

Warning

This function can ONLY be called from threads.

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.

Note

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.

See also

rt_event_detach()

Parameters

event

is a pointer to an event object to be deleted.

Returns

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.

Warning

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.

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.

Note

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.

Parameters

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.

Returns

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.

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.

Note

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

Parameters

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.

Returns

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.