Event flag group services

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

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

Macros
#define	EV_PRIO   0x1 /* Pend by task priority order. */
	Creation flags.
#define	EV_ANY   0x1 /* Disjunctive wait. */
	Operation flags.

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).

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.

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 returnbuffer" 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 seconds / nanoseconds, based on the Alchemy clock, specifying a time limit to wait for the request to be satisfied. 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

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