# 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