std::call_once

 

C++

语言

标准库头文件

自立与有宿主实现

具名要求

语言支持库

概念库 (C++20)

诊断库

工具库

字符串库

容器库

迭代器库

范围库 (C++20)

算法库

数值库

本地化库

输入/输出库

文件系统库 (C++17)

正则表达式库 (C++11)

原子操作库 (C++11)

线程支持库 (C++11)

技术规范

 

线程支持库

线程
thread (C++11)
jthread (C++20)
stop_token (C++20)
stop_source (C++20)
stop_callback (C++20)
hardware_destructive_interference_sizehardware_constructive_interference_size (C++17)(C++17)
this_thread 命名空间
get_id (C++11) yield (C++11)	sleep_for (C++11) sleep_until (C++11)
互斥
mutex (C++11) recursive_mutex (C++11) shared_mutex (C++17)	timed_mutex (C++11) recursive_timed_mutex (C++11) shared_timed_mutex (C++14)
通用锁管理
lock_guard (C++11) scoped_lock (C++17) unique_lock (C++11) shared_lock (C++14) defer_lock_ttry_to_lock_tadopt_lock_t (C++11)(C++11)(C++11)	lock (C++11) try_lock (C++11) defer_locktry_to_lockadopt_lock (C++11)(C++11)(C++11) once_flag (C++11) call_once (C++11)
条件变量
condition_variable (C++11)
condition_variable_any (C++11)
notify_all_at_thread_exit (C++11)
cv_status (C++11)
信号量
counting_semaphorebinary_semaphore (C++20)(C++20)
闩与屏障
latch (C++20)
barrier (C++20)
future
promise (C++11) future (C++11) shared_future (C++11) packaged_task (C++11) async (C++11)	launch (C++11) future_status (C++11) future_error (C++11) future_category (C++11) future_errc (C++11)

 

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

准确执行一次可调用 (Callable) 对象 f ，即使同时从多个线程调用。

细节为：

• 若在调用 call_once 的时刻， flag 指示已经调用了 f ，则 call_once 立即返回（称这种对 call_once 的调用为消极）。

• 否则， call_once 以参数 std::forward<Args>(args)... 调用 std::forward<Callable>(f) （如同用 std::invoke ）。不同于 std::thread 构造函数或 std::async ，不移动或复制参数，因为不需要转移它们到另一执行线程（称这种对 call_once 的调用为积极）。

• 若该调用抛异常，则传播异常给 call_once 的调用方，并且不翻转 flag ，以令其他调用将得到尝试（称这种对 call_once 的调用为异常）。
• 若该调用正常返回（称这种对 call_once 的调用为返回），则翻转 flag ，并保证以同一 flag 对 call_once 的其他调用为消极。

同一 flag 上的所有积极调用组成单独全序，它们由零或多个异常调用后随一个返回调用组成。该顺序中，每个积极调用的结尾同步于下个积极调用。

从返回调用的返回同步于同一 flag 上的所有消极调用：这表示保证所有对 call_once 的同时调用都观察到积极调用所做的任何副效应，而无需额外同步。

参数

flag	-	对象，对于它只有一个函数得到执行
f	-	要调用的可调用 (Callable) 对象
args...	-	传递给函数的参数

返回值

（无）

异常

• 若任何条件阻止对 call_once 的调用按规定执行，则抛出 std::system_error
• 任何 f 所抛的异常

注解

若对 call_once 的同时调用传递不同的 f ，则调用哪个 f 是未指定的。被选择函数运行于与传递它的 call_once 的调用相同的线程。

即使在从多个线程调用时，也保证函数局域静态对象的初始化仅出现一次，这可能比使用 std::call_once 的等价代码更为高效。

此函数的 POSIX 类似物是 pthread_once 。

示例

运行此代码

#include <iostream>
#include <thread>
#include <mutex>
 
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"; // 这会出现多于一次
    throw std::exception();
  }
  std::cout << "Didn't throw, call_once will not attempt again\n"; // 保证一次
}
 
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
Didn't throw, call_once will not attempt again

缺陷报告

下列更改行为的缺陷报告追溯地应用于以前出版的 C++ 标准。

DR	应用于	出版时的行为	正确行为
LWG 2442	C++11	在调用前复制并/或移动参数	不进行复制/移动

参阅

once_flag (C++11)

确保 call_once 只调用函数一次的帮助对象 (类)