Inter-task notification mechanism based on discrete flags. More...

Collaboration diagram for Event flag group services:

Data Structures
struct	RT_EVENT_INFO
	Event status descriptor. More...

Macros
#define	EV_PRIO 0x1 /* Pend by task priority order. */
	Creation flags. More...

#define	EV_ANY 0x1 /* Disjunctive wait. */
	Operation flags. More...

Functions
int	rt_event_delete (RT_EVENT *event)
	Delete an event flag group. More...

int	rt_event_wait_timed (RT_EVENT event, unsigned int mask, unsigned int mask_r, int mode, const struct timespec *abs_timeout)
	Wait for an arbitrary set of events. More...

static int	rt_event_wait_until (RT_EVENT event, unsigned int mask, unsigned int mask_r, int mode, RTIME timeout)
	Wait for an arbitrary set of events (with absolute scalar timeout). More...

static int	rt_event_wait (RT_EVENT event, unsigned int mask, unsigned int mask_r, int mode, RTIME timeout)
	Wait for an arbitrary set of events (with relative scalar timeout). More...

int	rt_event_inquire (RT_EVENT event, RT_EVENT_INFO info)
	Query event flag group status. More...

int	rt_event_bind (RT_EVENT event, const char name, RTIME timeout)
	Bind to an event flag group. More...

int	rt_event_unbind (RT_EVENT *event)
	Unbind from an event flag group. More...

int	rt_event_create (RT_EVENT event, const char name, unsigned int ivalue, int mode)
	Create an event flag group. More...

int	rt_event_signal (RT_EVENT *event, unsigned int mask)
	Signal an event. More...

int	rt_event_clear (RT_EVENT event, unsigned int mask, unsigned int mask_r)
	Clear event flags. More...

Detailed Description

Inter-task notification mechanism based on discrete flags.

An event flag group is a synchronization object represented by a long-word structure; every available bit in this word represents a user-defined event flag.

When a bit is set, the associated event is said to have occurred. Xenomai tasks can use this mechanism to signal the occurrence of particular events to other tasks.

Tasks can either wait for events to occur in a conjunctive manner (all awaited events must have occurred to satisfy the wait request), or in a disjunctive way (at least one of the awaited events must have occurred to satisfy the wait request).

Macro Definition Documentation

◆ EV_ANY

#define EV_ANY 0x1 /* Disjunctive wait. */

Operation flags.

◆ EV_PRIO

#define EV_PRIO 0x1 /* Pend by task priority order. */

Creation flags.

Referenced by rt_event_create().

Function Documentation

◆ rt_event_bind()

int rt_event_bind	(	RT_EVENT *	event,
		const char *	name,
		RTIME	timeout
	)

Bind to an event flag group.

This routine creates a new descriptor to refer to an existing event flag group identified by its symbolic name. If the object does not exist on entry, the caller may block until an event flag group of the given name is created.

Parameters

event	The address of an event flag group descriptor filled in by the operation. Contents of this memory is undefined upon failure.
name	A valid NULL-terminated name which identifies the event flag group to bind to. This string should match the object name argument passed to rt_event_create().
timeout	The number of clock ticks to wait for the registration to occur (see note). Passing TM_INFINITE causes the caller to block indefinitely until the object is registered. Passing TM_NONBLOCK causes the service to return immediately without waiting if the object is not registered on entry.

Returns: Zero is returned upon success. Otherwise:

-EINTR is returned if rt_task_unblock() was called for the current task before the retrieval has completed.
-EWOULDBLOCK is returned if timeout is equal to TM_NONBLOCK and the searched object is not registered on entry.
-ETIMEDOUT is returned if the object cannot be retrieved within the specified amount of time.
-EPERM is returned if this service should block, but was not called from a Xenomai thread.

Tags: xthread-nowait, switch-primary

Note: The timeout value is interpreted as a multiple of the Alchemy clock resolution (see –alchemy-clock-resolution option, defaults to 1 nanosecond).

◆ rt_event_clear()

int rt_event_clear	(	RT_EVENT *	event,
		unsigned int	mask,
		unsigned int *	mask_r
	)

Clear event flags.

This routine clears a set of flags from event.

Parameters

event	The event descriptor.
mask	The set of event flags to be cleared.
mask_r	If non-NULL, mask_r is the address of a memory location which will receive the previous value of the event flag group before the flags are cleared.

Returns: Zero is returned upon success. Otherwise:

-EINVAL is returned if event is not a valid event flag group descriptor.

Tags: unrestricted, switch-primary

◆ rt_event_create()

int rt_event_create	(	RT_EVENT *	event,
		const char *	name,
		unsigned int	ivalue,
		int	mode
	)

Create an event flag group.

Event groups provide for task synchronization by allowing a set of flags (or "events") to be waited for and posted atomically. An event group contains a mask of received events; an arbitrary set of event flags can be pended or posted in a single operation.

Parameters

event	The address of an event descriptor which can be later used to identify uniquely the created object, upon success of this call.
name	An ASCII string standing for the symbolic name of the event. When non-NULL and non-empty, a copy of this string is used for indexing the created event into the object registry.
ivalue	The initial value of the group's event mask.
mode	The event group creation mode. The following flags can be OR'ed into this bitmask:

EV_FIFO makes tasks pend in FIFO order on the event flag group.
EV_PRIO makes tasks pend in priority order on the event flag group.

Returns: Zero is returned upon success. Otherwise:

-EINVAL is returned if mode is invalid.
-ENOMEM is returned if the system fails to get memory from the main heap in order to create the event flag group.
-EEXIST is returned if the name is conflicting with an already registered event flag group.
-EPERM is returned if this service was called from an invalid context, e.g. interrupt or non-Xenomai thread.

Tags: xthread-only, mode-unrestricted, switch-secondary

Note: Event flag groups can be shared by multiple processes which belong to the same Xenomai session.

References EV_PRIO.

◆ rt_event_delete()

int rt_event_delete ( RT_EVENT * event )

Delete an event flag group.

This routine deletes a event flag group previously created by a call to rt_event_create().

Parameters

event The event descriptor.

Returns: Zero is returned upon success. Otherwise:

-EINVAL is returned if event is not a valid event flag group descriptor.
-EPERM is returned if this service was called from an asynchronous context.

Tags: mode-unrestricted, switch-secondary

◆ rt_event_inquire()

int rt_event_inquire	(	RT_EVENT *	event,
		RT_EVENT_INFO *	info
	)

Query event flag group status.

This routine returns the status information about event.

Parameters

event	The event descriptor.
info	A pointer to the return buffer" to copy the information to.

Returns: Zero is returned and status information is written to the structure pointed at by info upon success. Otherwise:

-EINVAL is returned if event is not a valid event flag group descriptor.

Tags: unrestricted, switch-primary

◆ rt_event_signal()

int rt_event_signal	(	RT_EVENT *	event,
		unsigned int	mask
	)

Signal an event.

Post a set of flags to event. All tasks having their wait request satisfied as a result of this operation are immediately readied.

Parameters

event	The event descriptor.
mask	The set of events to be posted.

Returns: Zero is returned upon success. Otherwise:

-EINVAL is returned if event is not an event flag group descriptor.

Tags: unrestricted, switch-primary

◆ rt_event_unbind()

int rt_event_unbind ( RT_EVENT * event )

Unbind from an event flag group.

Parameters

event The event descriptor.

This routine releases a previous binding to an event flag group. After this call has returned, the descriptor is no more valid for referencing this object.

Tags: thread-unrestricted

◆ rt_event_wait()

int rt_event_wait	(	RT_EVENT *	event,
		unsigned int	mask,
		unsigned int *	mask_r,
		int	mode,
		RTIME	timeout
	)

inlinestatic

Wait for an arbitrary set of events (with relative scalar timeout).

This routine is a variant of rt_event_wait_timed() accepting a relative timeout specification expressed as a scalar value.

Parameters

event	The event descriptor.
mask	The set of bits to wait for.
mask_r	The value of the event mask at the time the task was readied.
mode	The pend mode.
timeout	A delay expressed in clock ticks. Passing TM_INFINITE causes the caller to block indefinitely until the request is satisfied. Passing TM_NONBLOCK causes the service to return without blocking in case the request cannot be satisfied immediately.

Tags: xthread-nowait, switch-primary

◆ rt_event_wait_timed()

int rt_event_wait_timed	(	RT_EVENT *	event,
		unsigned int	mask,
		unsigned int *	mask_r,
		int	mode,
		const struct timespec *	abs_timeout
	)

Wait for an arbitrary set of events.

Waits for one or more events to be signaled in event, or until a timeout elapses.

Parameters

event	The event descriptor.
mask	The set of bits to wait for. Passing zero causes this service to return immediately with a success value; the current value of the event mask is also copied to mask_r.
mask_r	The value of the event mask at the time the task was readied.
mode	The pend mode. The following flags can be OR'ed into this bitmask, each of them affecting the operation:

EV_ANY makes the task pend in disjunctive mode (i.e. OR); this means that the request is fulfilled when at least one bit set into mask is set in the current event mask.
EV_ALL makes the task pend in conjunctive mode (i.e. AND); this means that the request is fulfilled when at all bits set into mask are set in the current event mask.

Parameters

abs_timeout An absolute date expressed in clock ticks, specifying a time limit to wait for the request to be satisfied (see note). Passing NULL causes the caller to block indefinitely until the request is satisfied. Passing { .tv_sec = 0, .tv_nsec = 0 } causes the service to return without blocking in case the request cannot be satisfied immediately.

Returns: Zero is returned upon success. Otherwise:

-ETIMEDOUT is returned if abs_timeout is reached before the request is satisfied.
-EWOULDBLOCK is returned if abs_timeout is { .tv_sec = 0, .tv_nsec = 0 } and the requested flags are not set on entry to the call.
-EINTR is returned if rt_task_unblock() was called for the current task before the request is satisfied.
-EINVAL is returned if mode is invalid, or event is not a valid event flag group descriptor.
-EIDRM is returned if event is deleted while the caller was sleeping on it. In such a case, event is no more valid upon return of this service.
-EPERM is returned if this service should block, but was not called from a Xenomai thread.

Tags: xthread-nowait, switch-primary

Note: abs_timeout value is interpreted as a multiple of the Alchemy clock resolution (see –alchemy-clock-resolution option, defaults to 1 nanosecond).

◆ rt_event_wait_until()

int rt_event_wait_until	(	RT_EVENT *	event,
		unsigned int	mask,
		unsigned int *	mask_r,
		int	mode,
		RTIME	abs_timeout
	)

inlinestatic

Wait for an arbitrary set of events (with absolute scalar timeout).

This routine is a variant of rt_event_wait_timed() accepting an absolute timeout specification expressed as a scalar value.

Parameters

event	The event descriptor.
mask	The set of bits to wait for.
mask_r	The value of the event mask at the time the task was readied.
mode	The pend mode.
abs_timeout	An absolute date expressed in clock ticks. Passing TM_INFINITE causes the caller to block indefinitely until the request is satisfied. Passing TM_NONBLOCK causes the service to return without blocking in case the request cannot be satisfied immediately.

Tags: xthread-nowait, switch-primary

Data Structures

Macros

Functions

Detailed Description

Macro Definition Documentation

◆ EV_ANY

◆ EV_PRIO

Function Documentation

◆ rt_event_bind()

◆ rt_event_clear()

◆ rt_event_create()

◆ rt_event_delete()

◆ rt_event_inquire()

◆ rt_event_signal()

◆ rt_event_unbind()

◆ rt_event_wait()

◆ rt_event_wait_timed()

◆ rt_event_wait_until()