最終更新日時: 2025年07月12日 02時16分44秒 (JST)
Koichi Murase が更新

履歴 編集

function template
<condition_variable>

# std::condition_variable::wait_until(C++11)

    template <class Clock, class Duration>
    cv_status wait_until(unique_lock<mutex>& lock,
                         const chrono::time_point<Clock, Duration>& abs_time); // (1)

    template <class Clock, class Duration, class Predicate>
    bool wait_until(unique_lock<mutex>& lock,
                    const chrono::time_point<Clock, Duration>& abs_time,
                    Predicate pred);                                           // (2)

## 概要

絶対時間でタイムアウトを指定して、起床されるまで待機する。

この関数は、処理をするための準備ができたことを`notify_one()`/`notify_all()`によって通知されるまでスレッドを待機するために使用する。

述語を指定しない場合、`notify_one()`/`notify_all()`が呼び出された時点でこの関数のブロッキングが解除される。

述語を指定する場合、述語呼び出しが`true`になるまで待機を続行する。

## 要件

- `lock.owns_lock() == true`であること
- `lock`が参照しているミューテックスオブジェクトが、この関数を呼び出したスレッドでロック取得されていること
- `*this`の`condition_variable`オブジェクトが他スレッドで待機していないか、もしくは並行に待機している全てのスレッドで`lock`パラメータが同じミューテックスオブジェクトを参照していること

## テンプレートパラメータ制約

- `chrono::is_clock_v<Clock>`が`true`であること (C++20)

## 効果

- (1) :

  1. アトミックに`lock.unlock()`する
  2. `notify_one()`/`notify_all()`による通知、`abs_time`によって指定された時間に到達したことによる期限切れ、もしくはなんらかの理由によって失敗するまでブロッキングする
  3. この関数を抜ける際に`lock.lock()`する
  4. この関数が例外送出によって終了する場合、関数を抜ける前に`lock.lock()`する

- (2) : 以下と等価の処理を行う

    while (!pred()) {
      if (wait_until(lock, abs_time) == cv_status::timeout) {
        return pred();
      }
    }
    return true;

## 戻り値

- (1) : `abs_time`で指定された絶対時間内に起床されない場合、タイムアウトとなり`cv_status::timeout`が返る。そうでない場合は`cv_status::no_timeout`が返る。
- (2) : `pred()`の結果が返る

## 事後条件

- `lock.owns_lock() == true`であること
- `lock`が参照しているミューテックスオブジェクトが、この関数を呼び出したスレッドでロック取得されていること

## 例外

- C++11 : この関数は、`lock.lock()`および`lock.unlock()`によって送出されうる、あらゆる例外が送出される可能性がある。
- C++14 : 時計クラス、`time_point`クラス、`duration`クラスの構築が例外を送出する場合、この関数はそれらの例外を送出する。

## 備考

- C++14 : 事後条件を満たさない場合、`std::terminate()`関数を呼び出して、プログラムを異常終了させる。これは、ミューテックスの再ロック取得が例外を送出した場合に発生する。

## 例

    #include <iostream>
    #include <condition_variable>
    #include <mutex>
    #include <thread>
    #include <chrono>

    struct ProcessData {
      std::mutex mtx_;
      std::condition_variable cond_;

      bool data_ready_ = false;

    public:
      // 処理に必要なデータの準備をする
      void prepare_data_for_processing()
      {
        // ...準備処理...

        {
          std::lock_guard<std::mutex> lk(mtx_);
          data_ready_ = true;
        }

        // 準備完了したので待機スレッドを全て起床させる
        cond_.notify_all();
      }

      void wait_until_data_to_process1()
      {
        std::unique_lock<std::mutex> lk(mtx_);

        // データの準備ができるまで待機してから処理する
        while (!data_ready_) {
          // 述語を指定しないバージョン
          // 3秒でタイムアウト
          using namespace std::chrono;
          steady_clock::time_point tp = steady_clock::now() + seconds(3);
          std::cv_status result = cond_.wait_until(lk, tp);
          if (result == std::cv_status::timeout) {
            std::cout << "wait_until_data_to_process1 : timeout" << std::endl;
            return;
          }
        }
        process_data();
      }

      void wait_until_data_to_process2()
      {
        std::unique_lock<std::mutex> lk(mtx_);

        // データの準備ができるまで待機してから処理する

        // 述語を指定するバージョン
        // 3秒でタイムアウト
        using namespace std::chrono;
        steady_clock::time_point tp = steady_clock::now() + seconds(3);
        if (!cond_.wait_until(lk, tp, [this] { return data_ready_; })) {
          // data_ready == false
          std::cout << "data is not ready" << std::endl;
          return;
        }
        process_data();
      }

    private:
      void process_data()
      {
        // ...データを処理する...
        std::cout << "process data" << std::endl;
      }
    };

    int main()
    {
      ProcessData p;

      std::thread t1([&] { p.prepare_data_for_processing(); });
      std::thread t2([&] { p.wait_until_data_to_process1(); });
      std::thread t3([&] { p.wait_until_data_to_process2(); });

      t1.join();
      t2.join();
      t3.join();
    }

### 出力例

    process data
    process data

## バージョン

### 言語

- C++11

### 処理系

- Clang: ??
- GCC: 4.7.0 ✅
- ICC: ??
- Visual C++: 2012 ✅, 2013 ✅

## 参照

- LWG Issue 2093. Throws clause of `condition_variable::wait` with predicate
- LWG Issue 2135. Unclear requirement for exceptions thrown in `condition_variable::wait()`
- Bug 41861 (DR887) - [DR 887][C++0x] `<condition_variable>` does not use `monotonic_clock`
  - GCC 10から`steady_clock`がサポートされた