OS_WaitEvent*

Syntax

#include <nitro/os.h>
u32 OS_WaitEvent( OSEvent* event,
                      u32 pattern,
                      OSEventMode mode );

u32 OS_WaitEventEx( OSEvent* event,
                      u32 pattern,
                      OSEventMode mode,
                      u32 clearBit );

(Inline functions)
static inline
u32 OS_WaitEvent_And( OSEvent* event,
                         u32 pattern );

static inline
u32 OS_WaitEvent_Or( OSEvent* event,
                         u32 pattern );

static inline
u32 OS_WaitEventEx_And( OSEvent* event,
                         u32 pattern,
                         u32 clearBit );

static inline
u32 OS_WaitEventEx_Or( OSEvent* event,
                         u32 pattern,
                         u32 clearBit );

Arguments

event Pointer to an event structure.
pattern Event flag bit pattern. Pattern for moving from the waiting for event state to the runnable state.
mode Matching mode. Event flag bit pattern's conditions for conformance.
clearBit Bits to clear from the event flag after the conditions are fulfilled.

Return Values

Returns the value of the event flag when the conditions have been fulfilled and the waiting has finished.
If clearBit is specified, the function will return the value before the bits were cleared.

Description

Waits for an event.
To begin waiting, you can make a thread transition itself to the waiting state using the OS_SleepThread function.

The event argument is a pointer to an event structure and must have been initialized in advance using the OS_InitEvent function.

There is a u32-type event flag within event, and waiting for an event will end when that value is a certain bit pattern. That bit pattern is specified using pattern and mode. Waiting will end when the flag bits indicated by pattern match the conditions expressed in mode. The meaning of mode is shown in the following table. (If pattern contains only a single bit set to 1, there is no difference between them.)

Value of mode in the OSEvent Structure Completion Conditions
OS_EVENT_MODE_AND Stop waiting when all bits become 1
OS_EVENT_MODE_OR Stop waiting when any bits become 1


If the conditions have already been fulfilled, control will leave the function immediately without switching threads.

When the event flag member of event fulfills the conditions and control leaves the function, OS_WaitEventEx() will clear the bits indicated by clearBit. The bits will still be cleared even if the conditions are already fulfilled when the function is called, because clearBit is enabled. If the OS_WaitEvent function is used, they will not be cleared .

The function's return value will be the value of the event flag when the conditions are fulfilled. However, with the OS_WaitEventEx function, the function will return the value before the bits are cleared.

y

OS_WaitEvent_And( event, pattern ) is the same as OS_WaitEvent( event, pattern, OS_EVENT_MODE_AND ).

OS_WaitEvent_Or( event, pattern ) is the same as OS_WaitEvent( event, pattern, OS_EVENT_MODE_OR ).

OS_WaitEventEx_And( event, pattern, clearBit ) is the same as OS_WaitEventEx( event, pattern, OS_EVENT_MODE_AND, clearBit ).

OS_WaitEventEx_Or( event, pattern, clearBit ) is the same as OS_WaitEventEx( event, pattern, OS_EVENT_MODE_OR, clearBit ).

See Also

OS_InitEvent
OS_SignalEvent
OS_Clear*Event
OS_PollEvent*
OS Overview (Events)

Revision History

2007/12/04 Initial version.

CONFIDENTIAL