eventInit(2K)

NAME | SYNOPSIS | API RESTRICTIONS | FEATURES | DESCRIPTION | RESTRICTIONS | RETURN VALUE | ERRORS | ATTRIBUTES

NAME

eventInit, eventClear, eventPost, eventWait- initialize an event flag set; Clear events in an event flag set; Post events in an event flag set; Wait for events in an event flag set

SYNOPSIS

#include <sync/chEvent.h>

int eventInit(KnEventSet * eventSet);
int eventClear(KnEventSet * eventSet, unsigned int mask);
int eventPost(KnEventSet * eventSet, unsigned int mask);
int eventWait(KnEventSet * eventSet, unsigned int inMask, unsigned int option, unsigned int * outMask, KnTimeVal * waitLimit);

API RESTRICTIONS

The function or functions documented here may not be used safely in all application contexts with all APIs provided in the ChorusOS 5.0 product.

See API(5FEA) for details.

FEATURES

EVENT

DESCRIPTION

Event flag sets are KnEventSet structures allocated in user memory. An event flag set is a set of bits in memory associated with a thread wait queue. Each bit is associated with one event. The set is implemented as an unsigned integer; the maximum number of flags in a set is 8*sizeof(int) . Within a set, each event flag is designated by an integer number ([0 .. 8*sizeof(int)-1]) .

When a flag is set, it is said to be POSTED, and the associated event is considered to have occurred. Otherwise, the flag is said to be UNPOSTED, and the associated event has not yet occurred. Both threads and interrupt handlers can use event flag sets for signaling purposes.

The eventInit call initializes the event flag set whose address is eventSet. All events are initialized in the UNPOSTED state.

The eventPost call posts (sets to POSTED) one or more event flags within eventSet. Any thread waiting for posted events will be awakened, and subsequently eventWait calls referring to the events posted will return immediately. The event flags remain in the posted state until explicitly cleared using eventClear. The mask field specifies the mask of posted events (event number i is posted if bit i of mask is set). You can call eventPost within an interrupt handler, or with preemption disabled.

The eventWait call makes the current thread wait conditionally for one or more events on the event flag set eventSet.

The inMask field specifies the mask of awaited events (event number { i } is awaited if the bit i of inMask is set). If inMask is zero (no awaited flag), eventWait returns immediately, regardless the value of waitLimit . This can be used to obtain the current state of the event flag set.

The option field can be:

K_EVENT_OR

The thread waits for an OR condition to be satisfied by the events indicated in inMask; it is sufficient that one of the events be posted for the thread to be awakened.

K_EVENT_AND

The thread waits for an AND condition to be satified by the events indicated in inMask ; all the events in the mask must be posted for the thread to be awakened.

The eventWait call returns K_EINVAL if the option is incorrect, and returns K_EFAULT if it is blocked with an invalid outMask pointer, or is going to be blocked with an invalid waitLimit .

If eventWait is not blocked (i.e. if the event flag condition is satisfied immediately), K_EFAULT is never returned if outMask is an invalid pointer, and the thread is killed.

Posted events remain posted after eventWait returns, until cleared explicitly using eventClear. If a subsequent eventWait with the same inMask is launched before clearing, it will return immediately with the same status as the previous call.

The outMask field shows the state of the event flag set when the thread was awakened.

If the thread event-set state does not satisfy the conditions described in inMask and option, the thread is blocked according to the options described in waitLimit in intro(K). The waitLimit pointer indicates a KnTimeVal structure which contains a timeout interval as described in sysTime(K).

The eventClear call clears one or more event flags within the event flag set eventSet. The mask field shows the mask of cleared events (event number i is cleared if the bit i of mask is set).

RESTRICTIONS

A user application and a supervisor application may not share an event.

However, two user applications may share an event by mapping it in both user address spaces.

RETURN VALUE

Upon successful completion a value of 0 is returned. Otherwise, a negative error code is returned.

ERRORS

[K_EABORT]

eventWait has been aborted.

[K_EFAULT]

eventSet or outMask points outside the current actor's address space.

[K_EINVAL]

The eventSet structure has not been correctly initialized, or the waitLimit is an invalid KnTimeVal.

[K_ETIMEOUT]

The time-out occurred.

ATTRIBUTES

See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE	ATTRIBUTE VALUE
Interface Stability	Evolving

ChorusOS 5.0  Last Revised December 2001

NAME | SYNOPSIS | API RESTRICTIONS | FEATURES | DESCRIPTION | RESTRICTIONS | RETURN VALUE | ERRORS | ATTRIBUTES