std::call_once

定义在头文件 `<mutex>` 中
template< class Callable, class... Args > void call_once( std::once_flag& flag, Callable&& f, Args&&... args );		(自 C++11 起)

精确执行一次 Callable 对象 f，即使从多个线程并发调用也是如此。

详细说明

如果在调用 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 的所有主动调用会形成一个单一的总顺序，该顺序包含零个或多个异常调用，然后是一个返回调用。每个主动调用的结束与该顺序中的下一个主动调用同步。

返回调用的返回与对相同 flag 的所有被动调用的返回同步：这意味着对 std::call_once 的所有并发调用都保证会观察到主动调用所做的任何副作用，而无需额外的同步。

[编辑] 参数

flag	-	一个对象，为此精确执行一个函数
f	-	Callable 要调用的对象
args...	-	要传递给函数的参数

[编辑] 返回值

(无)

[编辑] 异常

如果任何条件阻止对 std::call_once 的调用按指定执行，则会抛出 std::system_error。
f 抛出的任何异常。

[编辑] 注释

如果对 std::call_once 的并发调用传递了不同的函数 f，则哪个 f 会被调用是不确定的。所选函数将在与传递给它的 std::call_once 调用的同一线程中运行。

对函数局部静态变量的初始化保证只发生一次，即使从多个线程调用也是如此，并且可能比使用 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	std::invalid_argument 如果 f 无效，则会抛出。但是，没有指定 f 无效的情况。	已移除此错误条件。
LWG 2442	C++11	参数在调用之前被复制和/或移动。	不执行任何复制/移动操作。

[编辑] 另请参阅

once_flag (C++11)	辅助对象，确保 `call_once` 只调用函数一次。 (类) [编辑]
C 文档 for call_once

编译器支持
独立和宿主
语言
标准库
标准库头文件
命名要求
功能测试宏 (C++20)
语言支持库
概念库 (C++20)
元编程库 (C++11)
诊断库
通用实用程序库
字符串库
容器库
迭代器库
范围库 (C++20)
算法库
数值库
本地化库
输入/输出库
文件系统库 (C++17)
正则表达式库 (C++11)
并发支持库 (C++11)
执行支持库 (C++26)
技术规范
符号索引
外部库

cppreference.com

命名空间

变体

视图

操作