Event flag group services.
[Native RTAI API.]


Detailed Description

Event flag group services.


Files

file  event.c
 This file is part of the RTAI project.

Functions

int rt_event_create (RT_EVENT *event, const char *name, unsigned long ivalue, int mode)
 Create an event group.
int rt_event_delete (RT_EVENT *event)
 Delete an event group.
int rt_event_post (RT_EVENT *event, unsigned long mask)
 Post an event group.
int rt_event_pend (RT_EVENT *event, unsigned long mask, unsigned long *mask_r, int mode, RTIME timeout)
 Pend on an event group.
int rt_event_inquire (RT_EVENT *event, RT_EVENT_INFO *info)
 Inquire about an event group.


Function Documentation

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

Create an event 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; any set of bits from the event mask can be pended or posted in a single operation.

Tasks can wait for a conjunctive (AND) or disjunctive (OR) set of events to occur. A task pending on an event group in conjunctive mode is woken up as soon as all awaited events are set in the event mask. A task pending on an event group in disjunctive mode is woken up as soon as any awaited event is set in the event mask.

Parameters:
event The address of an event group descriptor RTAI will use to store the event-related data. This descriptor must always be valid while the group is active therefore it must be allocated in permanent memory.
name An ASCII string standing for the symbolic name of the group. When non-NULL and non-empty, this string is copied to a safe place into the descriptor, and passed to the registry package if enabled for indexing the created event group.
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, each of them affecting the new group:
  • EV_FIFO makes tasks pend in FIFO order on the event group.

  • EV_PRIO makes tasks pend in priority order on the event group.

Returns:
0 is returned upon success. Otherwise:
  • -EEXIST is returned if the name is already in use by some registered object.

Context: This routine can be called on behalf of a task or from the initialization code.

int rt_event_delete RT_EVENT *  event  ) 
 

Delete an event group.

Destroy an event group and release all the tasks currently pending on it. An event group exists in the system since rt_event_create() has been called to create it, so this service must be called in order to destroy it afterwards.

Parameters:
event The descriptor address of the affected event group.
Returns:
0 is returned upon success. Otherwise:
  • -EINVAL is returned if event is not a event group descriptor.

  • -EIDRM is returned if event is a deleted event group descriptor.

Side-effect: This routine calls the rescheduling procedure if tasks have been woken up as a result of the deletion.

Context: This routine can always be called on behalf of a task, or from the initialization code.

int rt_event_inquire RT_EVENT *  event,
RT_EVENT_INFO *  info
 

Inquire about an event group.

Return various information about the status of a specified event group.

Parameters:
event The descriptor address of the inquired event group.
info The address of a structure the event group information will be written to.
Returns:
0 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 event group descriptor.

  • -EIDRM is returned if event is a deleted event group descriptor.

Context: This routine can be called on behalf of a task, interrupt context or from the initialization code.

int rt_event_pend RT_EVENT *  event,
unsigned long  mask,
unsigned long *  mask_r,
int  mode,
RTIME  timeout
 

Pend on an event group.

Pends for one or more events on the specified event group, either in conjunctive or disjunctive mode.

If the specified set of bits is not set, the calling task is blocked. The task is not resumed until the request is fulfilled.

Parameters:
event The descriptor address of the affected event group.
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:
timeout The number of clock ticks to wait for fulfilling the request (see note). Passing RT_TIME_INFINITE causes the caller to block indefinitely until the request is fulfilled. Passing RT_TIME_NONBLOCK causes the service to return immediately without waiting if the request cannot be satisfied immediately.
Returns:
0 is returned upon success. Otherwise:
  • -EINVAL is returned if event is not a event group descriptor.

  • -EIDRM is returned if event is a deleted event group descriptor, including if the deletion occurred while the caller was sleeping on it before the request has been satisfied.

  • -EWOULDBLOCK is returned if timeout is equal to RT_TIME_NONBLOCK and the current event mask value does not satisfy the request.

  • -EINTR is returned if rt_task_unblock() has been called for the waiting task before the request has been satisfied.

  • -ETIMEDOUT is returned if the request has not been satisfied within the specified amount of time.

Side-effect: This routine calls the rescheduling procedure unless the request is immediately satisfied or timeout specifies a non-blocking operation.

Context: This routine can be called on behalf of a task. It can also be called on behalf of an interrupt context or from the initialization code provided timeout is equal to RT_TIME_NONBLOCK.

Note:
This service is sensitive to the current operation mode of the system timer, as defined by the rt_timer_start() service. In periodic mode, clock ticks are expressed as periodic jiffies. In oneshot mode, clock ticks are expressed in nanoseconds.

int rt_event_post RT_EVENT *  event,
unsigned long  mask
 

Post an event group.

Post a set of bits to the event mask. All tasks having their wait request fulfilled by the posted events are resumed. In the same move, the matched bits are automatically cleared from the event mask by this service.

Parameters:
event The descriptor address of the affected event.
mask The set of events to be posted.
Returns:
0 is returned upon success. Otherwise:
  • -EINVAL is returned if event is not an event group descriptor.

  • -EIDRM is returned if event is a deleted event group descriptor.

Side-effect: This routine calls the rescheduling procedure if a task is woken up as a result of the operation.

Context: This routine can be called on behalf of a task, interrupt context or from the initialization code.


Generated on Mon Aug 30 13:58:39 2004 for RTAI API by doxygen 1.3.8