Xenomai  3.1
Event flag group services

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
eventThe address of an event flag group descriptor filled in by the operation. Contents of this memory is undefined upon failure.
nameA 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().
timeoutThe 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
eventThe event descriptor.
maskThe set of event flags to be cleared.
mask_rIf 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
eventThe address of an event descriptor which can be later used to identify uniquely the created object, upon success of this call.
nameAn 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.
ivalueThe initial value of the group's event mask.
modeThe 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
eventThe 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
eventThe event descriptor.
infoA 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
eventThe event descriptor.
maskThe 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
eventThe 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
eventThe event descriptor.
maskThe set of bits to wait for.
mask_rThe value of the event mask at the time the task was readied.
modeThe pend mode.
timeoutA 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
eventThe event descriptor.
maskThe 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_rThe value of the event mask at the time the task was readied.
modeThe 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_timeoutAn 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
eventThe event descriptor.
maskThe set of bits to wait for.
mask_rThe value of the event mask at the time the task was readied.
modeThe pend mode.
abs_timeoutAn 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