# OS_WaitEvent*

## 構文

      #include <nitro/os.h>

      u32 OS_WaitEvent( OSEvent* event,
                            u32 pattern,
                            OSEventMode mode );

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

      (インライン関数)
      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 );

## 引数

event | イベント構造体へのポインタ
pattern | イベントフラグビットパターン。イベント待ちから動作可能状態へ移るパターンを表す。
mode | マッチングモード。イベントフラグビットパターンの合致条件を表す。
clearBit | 条件を満たした後にイベントフラグからクリアするビット

## 返り値

条件を満たして待ちを終了したときのイベントフラグの値です。
clearBit が指定されている場合は、クリアする前の値となります。

## 説明

イベントを待ちます。
待つときには `OS_SleepThread()` で自らのスレッドを待機状態へと遷移させます。

event はイベント構造体へのポインタで、予め `OS_InitEvent()` で初期化されている必要があります。

event 内には u32型 のイベントフラグがあり、それがあるビットパターンになったときにイベント待ちを終了しますが、そのビットパターンを pattern と mode で指定します。フラグが pattern で示したビットの mode で示したような条件になったときに終了します。mode の意味は次の通りです。(pattern が、1であるビットが1つである値の場合はどちらでも違いはありません。)

OSEvent 構造体の mode の値 | 終了条件
--- | ---
`OS_EVENT_MODE_AND` | すべてのビットが 1 となったときに待ちを終了
`OS_EVENT_MODE_OR` | いずれかのビットが 1 となったときに待ちを終了

なおすでに条件を満たしているときはスレッドの切り替えをせずにすぐに関数から抜けます。

event のメンバであるイベントフラグが条件を満たして関数から抜けるときに、`OS_WaitEventEx()` では clearBit で示されたビットをクリアします。関数を呼んだ時点で条件を満たしているときでも clearBit は有効なのでビットをクリアします。`OS_WaitEvent()` ではクリアしません。

関数の返り値は条件を満たしたときのイベントフラグの値となります。ただし、`OS_WaitEventEx()` の場合、ビットをクリアする前の値を返します。

`OS_WaitEvent_And( event, pattern )` は `OS_WaitEvent( event, pattern, OS_EVENT_MODE_AND )` と同じです。

`OS_WaitEvent_Or( event, pattern )` は `OS_WaitEvent( event, pattern, OS_EVENT_MODE_OR )` と同じです。

`OS_WaitEventEx_And( event, pattern, clearBit )` は `OS_WaitEventEx( event, pattern, OS_EVENT_MODE_AND, clearBit )` と同じです。

`OS_WaitEventEx_Or( event, pattern, clearBit )` は `OS_WaitEventEx( event, pattern, OS_EVENT_MODE_OR, clearBit )` と同じです。

## 参照

`OS_InitEvent, OS_SignalEvent, OS_Clear*Event, OS_PollEvent*, OS概要(イベント)`

## 履歴

2007/12/04 初版