std::call_once
From cppreference.com
| ヘッダ <mutex> で定義 |
||
| template< class Callable, class... Args > void call_once( std::once_flag& flag, Callable&& f, Args&&... args ); |
(C++11以降) | |
指定されたCallableオブジェクト f を、複数のスレッドから同時に呼び出された場合でも、正確に1回だけ実行します。
詳細
std::call_onceが呼び出された時点で、flagがfが既に呼び出されたことを示している場合、std::call_onceはすぐに返ります（このようなstd::call_onceの呼び出しはパッシブと呼ばれます）。
- それ以外の場合、
std::call_onceはINVOKE(std::forward<Callable>(f), std::forward<Args>(args)...)を呼び出します。std::threadコンストラクタやstd::asyncとは異なり、引数は別の実行スレッドに転送する必要がないため、移動またはコピーされません（このようなstd::call_onceの呼び出しはアクティブと呼ばれます）。
- その呼び出しで例外がスローされた場合、それは
std::call_onceの呼び出し元に伝播され、flagはフリップされないため、別の呼び出しが試行されます（このようなstd::call_onceの呼び出しは例外的と呼ばれます）。 - その呼び出しが正常に返った場合（このような
std::call_onceの呼び出しは正常終了と呼ばれます）、flagはフリップされ、同じflagを持つ他のすべてのstd::call_onceの呼び出しはパッシブであることが保証されます。
- その呼び出しで例外がスローされた場合、それは
同じflagに対するすべてのアクティブな呼び出しは、0個以上の例外的な呼び出し、それに続く1個の正常終了する呼び出しで構成される単一の全順序を形成します。各アクティブな呼び出しの終了は、その順序の次のアクティブな呼び出しと同期します。
正常終了する呼び出しの返りは、同じflagに対するすべてのパッシブな呼び出しの返りと同期します。これは、`std::call_once`へのすべての同時呼び出しが、アクティブな呼び出しによって行われた副作用を、追加の同期なしに確実に観測することを意味します。
目次 |
[編集] パラメータ
| flag | - | 関数が正確に1回だけ実行されるオブジェクト |
| f | - | Callableオブジェクト。呼び出されます。 |
| args... | - | 関数に渡す引数 |
[編集] 戻り値
(なし)
[編集] 例外
-
std::call_onceの呼び出しが指定どおりに実行されるのを妨げる条件がある場合、std::system_error。 - fによってスローされた例外。
[編集] 注記
std::call_onceの並行呼び出しが異なる関数fを渡した場合、どのfが呼び出されるかは未規定です。選択された関数は、それが渡されたstd::call_onceの呼び出しと同じスレッドで実行されます。
関数ローカル静的変数の初期化は、複数のスレッドから呼び出された場合でも1回だけ行われることが保証されており、`std::call_once`を使用した同等のコードよりも効率的な場合があります。
この関数のPOSIX同等関数は、pthread_onceです。
[編集] 例
このコードを実行
#include <iostream> #include <mutex> #include <thread> std::once_flag flag1, flag2; void simple_do_once() { std::call_once(flag1, [](){ std::cout << "Simple example: called once\n"; }); } void may_throw_function(bool do_throw) { if (do_throw) { std::cout << "Throw: call_once will retry\n"; // this may appear more than once throw std::exception(); } std::cout << "Did not throw, call_once will not attempt again\n"; // guaranteed once } void do_once(bool do_throw) { try { std::call_once(flag2, may_throw_function, do_throw); } catch (...) {} } int main() { std::thread st1(simple_do_once); std::thread st2(simple_do_once); std::thread st3(simple_do_once); std::thread st4(simple_do_once); st1.join(); st2.join(); st3.join(); st4.join(); std::thread t1(do_once, true); std::thread t2(do_once, true); std::thread t3(do_once, false); std::thread t4(do_once, true); t1.join(); t2.join(); t3.join(); t4.join(); }
実行結果の例
Simple example: called once Throw: call_once will retry Throw: call_once will retry Throw: call_once will retry Did not throw, call_once will not attempt again
[編集] 不具合報告
以下の動作変更を伴う欠陥報告が、以前に公開されたC++標準に遡って適用されました。
| DR | 適用対象 | 公開された動作 | 正しい動作 |
|---|---|---|---|
| LWG 2080 | C++11 | fが無効な場合、std::invalid_argumentがスローされるはずだった、 しかしfが無効になるシナリオは指定されていませんでした。 |
このエラー条件は削除されました。 |
| LWG 2442 | C++11 | 引数は呼び出し前にコピーまたは移動されていました。 | コピー/移動は行われません。 |
[編集] 関連項目
| (C++11) |
call_once が関数を一度だけ呼び出すことを保証するためのヘルパーオブジェクト。 (クラス) |
| C言語ドキュメント call_once
| |
