C++ 多线程 std::call_once() and std::once_flag

C++ 多线程 std::call_once{} and std::once_flag

• [1. `std::call_once()`](#1. std::call_once())
• • [1.1. `std::once_flag`](#1.1. std::once_flag)
• [2. Parameters](#2. Parameters)
• [3. Return value](#3. Return value)
• [4. Examples](#4. Examples)
• • [4.1. `std::call_once()`](#4.1. std::call_once())
• [5. Data races (数据竞争)](#5. Data races (数据竞争))
• [6. Exception safety (异常安全性)](#6. Exception safety (异常安全性))
• References

https://cplusplus.com/reference/mutex/call_once/

1. std::call_once()

public member function

template <class Fn, class... Args>
void call_once (once_flag& flag, Fn&& fn, Args&&... args);

std::call_once() 是 C++11 引入的一个线程同步原语，用于确保在多线程环境中，某个特定的函数或初始化代码块‌仅被执行一次‌，无论有多少个线程同时调用它。

多个线程同时调用 std::call_once() 时，只有一个线程会执行目标函数，其他线程会被阻塞，直到该函数执行完毕。

Calls fn passing args as arguments, unless another thread has already executed (or is currently executing) a call to std::call_once() with the same std::once_flag.

调用函数 fn 并传递 args 作为参数，除非另一个线程已经执行过 (或正在执行) 使用相同 std::once_flag 调用 std::call_once() 的操作。

If another thread is already actively executing a call to std::call_once() with the same std::once_flag, it causes a passive execution: Passive executions do not call fn but do not return until the active execution itself has returned, and all visible side effects are synchronized at that point among all concurrent calls to this function with the same std::once_flag.

std::call_once() 将检查关联的 std::once_flag 是否已被标记为执行过：

• 如果没有执行过，则 std::call_once() 会执行传入的函数，并将标记设置为已执行，保证此后的调用不会再次执行该函数。

• 如果已执行过，则 std::call_once() 不会执行传入的函数。

  passive ['pæsɪv]
  n. 被动语态；动词被动形式
  adj. 消极的；被动的；(动词形式) 被动语态的

If an active call to std::call_once() ends by throwing an exception (which is propagated to its calling thread) and passive executions exist, one is selected among these passive executions, and called to be the new active call instead.

如果对 std::call_once() 的活动调用因抛出异常而终止 (该异常会传播到调用线程)，并且存在被动执行，则会从这些被动执行中选择一个，并将其作为新的活动调用来执行。

Note that once an active execution has returned, all current passive executions and future calls to std::call_once() (with the same std::once_flag) also return without becoming active executions.

一旦某个活动执行完成并返回，所有当前的被动执行以及将来对 std::call_once() 的调用 (使用相同的 std::once_flag) 也会立即返回，而不会成为活动执行。

The active execution uses std::decay of the lvalue or rvalue references of fn and args, ignoring the value returned by fn.

1.1. std::once_flag

struct once_flag;

Object of this type are used as arguments for std::call_once().

Using the same object on different calls to std::call_once() in different threads causes a single execution if called concurrently.

It is a non-copyable, non-movable, default-constructible class, declared in <mutex> with the following prototype:

	// STRUCT once_flag
struct once_flag
	{	// opaque data structure for call_once()
	constexpr once_flag() _NOEXCEPT
		: _Opaque(0)
		{	// default construct
		}

	once_flag(const once_flag&) = delete;
	once_flag& operator=(const once_flag&) = delete;

	void *_Opaque;
	};

2. Parameters

• flag

Object used by the function to track the state of invocations.

Using the same object for calls in different threads, results in a single call if called concurrently.

C++11 : If flag has a state that is not valid, the function throws a std::system_error exception with an std::errc::invalid_argument error condition.

C++14 : If flag has a state that is not valid, the call causes undefined behavior.

std::call_once() is a specific type defined in header <mutex> to be used as argument to this function.

std::once_flag 应当与需要单次执行的函数或者代码块保持相同的生命周期，通常作为静态状态存在于全局或者作为某个对象的一部分。一旦被 std::call_once() 标记为已调用，它的状态就不会再变更，确保生命周期的管理不会影响其功能。

• fn

A pointer to function, pointer to member, or any kind of std::is_move_constructible function object (i.e., an object whose class defines operator(), including closures and std::function objects).

The return value (if any) is ignored.

• args...

Arguments passed to the call to fn. Their types shall be std::is_move_constructible.

If fn is a std::is_member_pointer, the first argument shall be an object for which that member is defined (or a reference, or a pointer to it).

3. Return value

none

4. Examples

4.1. std::call_once()

//============================================================================
// Name        : std::call_once()
// Author      : Yongqiang Cheng
// Version     : Version 1.0.0
// Copyright   : Copyright (c) 2019 Yongqiang Cheng
// Description : Hello World in C++, Ansi-style
//============================================================================

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

int winner;
void set_winner(const int x) { winner = x; }
std::once_flag winner_flag;

void wait_1000ms(const int id) {
    // count to 1000, waiting 1ms between increments:
    for (int i = 0; i < 1000; ++i) {
        std::this_thread::sleep_for(std::chrono::milliseconds(1));
    }
    // claim to be the winner (only the first such call is executed):
    std::call_once(winner_flag, set_winner, id);
}

int main() {
    std::thread threads[10];
    // spawn 10 threads:
    for (int i = 0; i < 10; ++i) {
        threads[i] = std::thread(wait_1000ms, i + 1);
    }

    std::cout << "waiting for the first among 10 threads to count 1000 ms...\n";

    for (auto& th : threads) { th.join(); }
    std::cout << "winner thread: " << winner << '\n';

    return 0;
}

Possible output (winner may vary):

waiting for the first among 10 threads to count 1000 ms...
winner thread: 9
请按任意键继续. . .

5. Data races (数据竞争)

The function modifies std::once_flag, and accesses fn and args to create std::decay of their lvalue or rvalue references.

6. Exception safety (异常安全性)

If the function itself fails, it throws a std::system_error exception, leaving all objects in a valid state (basic guarantee).

Otherwise, active executions provide the same level of guarantees as the operation performed on the arguments.

References

1\] Yongqiang Cheng, \[2\] `std::call_once()`, \[3\] `std::once_flag`,