Difference between revisions of "cpp/thread/notify all at thread exit"

Latest revision as of 23:39, 13 March 2024

Defined in header `<condition_variable>`
void notify_all_at_thread_exit( std::condition_variable& cond, std::unique_lock<std::mutex> lk );		(since C++11)

notify_all_at_thread_exit provides a mechanism to notify other threads that a given thread has completely finished, including destroying all thread_local objects. It operates as follows:

Ownership of the previously acquired lock lk is transferred to internal storage.

The execution environment is modified such that when the current thread exits, the condition variable cond is notified as if by lk.unlock();
cond.notify_all();.

The implied lk.unlock() is sequenced after the destruction of all objects with thread local storage duration associated with the current thread.

If any of the following conditions is satisfied, the behavior is undefined:

lk is not locked by the calling thread.
If some other threads are also waiting on cond, lk.mutex() is different from the mutex unlocked by the waiting functions (wait, wait_for and wait_until) called on cond by those threads.

The supplied lock lk is held until the thread exits. Once this function has been called, no more threads may acquire the same lock in order to wait on cond. If some threads are waiting on this condition variable, ensure that the condition being waited for is satisfied while holding the lock on lk, and that this lock is not released and reacquired prior to calling notify_all_at_thread_exit to avoid confusion from spurious wakeups in other threads.

In typical use cases, this function is the last thing called by a detached thread.

[edit] Parameters

cond	-	the condition variable to notify at thread exit
lk	-	the lock associated with the condition variable cond

[edit] Return value

(none)

[edit] Example

This partial code fragment illustrates how notify_all_at_thread_exit can be used to avoid accessing data that depends on thread locals while those thread locals are in the process of being destructed:

Run this code

#include <cassert>
#include <condition_variable>
#include <mutex>
#include <string>
#include <thread>
 
std::mutex m;
std::condition_variable cv;
 
bool ready = false;
std::string result; // some arbitrary type
 
void thread_func()
{
    thread_local std::string thread_local_data = "42";
 
    std::unique_lock<std::mutex> lk(m);
 
    // assign a value to result using thread_local data
    result = thread_local_data;
    ready = true;
 
    std::notify_all_at_thread_exit(cv, std::move(lk));
 
}   // 1. destroy thread_locals;
    // 2. unlock mutex;
    // 3. notify cv.
 
int main()
{
    std::thread t(thread_func);
    t.detach();
 
    // do other work
    // ...
 
    // wait for the detached thread
    std::unique_lock<std::mutex> lk(m);
    cv.wait(lk, []{ return ready; });
 
    // result is ready and thread_local destructors have finished, no UB
    assert(result == "42");
}

[edit] Defect reports

The following behavior-changing defect reports were applied retroactively to previously published C++ standards.

DR	Applied to	Behavior as published	Correct behavior
LWG 2140	C++11	the call to `notify_all_at_thread_exit` synchronized with calls to functions waiting on cond	updated the synchronization requirement

[edit] See also

set_value_at_thread_exit	sets the result to specific value while delivering the notification only at thread exit (public member function of `std::promise<R>`) [edit]
make_ready_at_thread_exit	executes the function ensuring that the result is ready only once the current thread exits (public member function of `std::packaged_task<R(Args...)>`) [edit]

@@ Line 1: / Line 1: @@
 {{cpp/title|notify_all_at_thread_exit}}
 {{cpp/thread/navbar}}
-{{ddcl | header=condition_variable | since=c++11 |
+{{ddcl|header=condition_variable|since=c++11|
 void notify_all_at_thread_exit( std::condition_variable& cond,
                                  std::unique_lock<std::mutex> lk );
 }}
-{{tt|notify_all_at_thread_exit}} provides a mechanism to notify other threads that a given thread has completely finished, including destroying all [[cpp/keyword/thread_local|thread_local]] objects.  It operates as follows:
+{{tt|notify_all_at_thread_exit}} provides a mechanism to notify other threads that a given thread has completely finished, including destroying all {{ltt|cpp/keyword/thread_local}} objects. It operates as follows:
-* Ownership of the previously acquired lock {{tt|lk}} is transferred to internal storage.
+* Ownership of the previously acquired lock {{c|lk}} is transferred to internal storage.
-* The execution environment is modified such that when the current thread exits, the condition variable {{tt|cond}} is notified as if by:
+* The execution environment is modified such that when the current thread exits, the condition variable {{c|cond}} is notified as if by {{c multi|lk.unlock();|cond.notify_all();}}.
-{{c|
+The implied {{c|lk.unlock()}} is [[cpp/atomic/memory_order|sequenced after]] the destruction of all objects with [[cpp/keyword/thread_local|thread local storage duration]] associated with the current thread.
-lk.unlock();
-cond.notify_all();
-}}
-The implied {{tt|lk.unlock}} is ''sequenced after'' (as defined in {{lc|std::memory_order}})  the destruction of all objects with [[cpp/keyword/thread_local|thread local storage duration]] associated with the current thread.
+If any of the following conditions is satisfied, the behavior is undefined:
+* {{c|lk}} is not locked by the calling thread.
+* If some other threads are also waiting on {{c|cond}}, {{c|lk.mutex()}} is different from the mutex unlocked by the waiting functions ({{tt|wait}}, {{lc|wait_for}} and {{lc|wait_until}}) called on {{c|cond}} by those threads.
+===Notes===
 An equivalent effect may be achieved with the facilities provided by {{lc|std::promise}} or {{lc|std::packaged_task}}.
-===Notes===
+The supplied lock {{c|lk}} is held until the thread exits. Once this function has been called, no more threads may acquire the same lock in order to wait on {{c|cond}}. If some threads are waiting on this condition variable, ensure that the condition being waited for is satisfied while holding the lock on {{c|lk}}, and that this lock is not released and reacquired prior to calling {{tt|notify_all_at_thread_exit}} to avoid confusion from spurious wakeups in other threads.
-Calling this function if {{tt|lock.mutex()}} is not locked by the current thread is undefined behavior.
-Calling this function if {{tt|lock.mutex()}} is not the same mutex as the one used by all other threads that are currently waiting on the same condition variable is undefined behavior.
-The supplied lock {{tt|lk}} is held until the thread exits. Once this function has been called, no more threads may acquire the same lock in order to wait on {{tt|cond}}. If some thread is waiting on this condition variable, it should not attempt to release and reacquire the lock when it wakes up spuriously.
 In typical use cases, this function is the last thing called by a detached thread.
@@ Line 32: / Line 27: @@
 ===Parameters===
 {{par begin}}
-{{par | cond | the condition variable to notify at thread exit}}
+{{par|cond|the condition variable to notify at thread exit}}
-{{par | lk | the lock associated with the condition variable {{tt|cond}} }}
+{{par|lk|the lock associated with the condition variable {{c|cond}}}}
 {{par end}}
@@ Line 41: / Line 36: @@
 ===Example===
 {{example
- | This partial code fragment illustrates how {{tt|notify_all_at_thread_exit}} can be used to avoid accessing data that depends on thread locals while those thread locals are in the process of being destructed:
+|This partial code fragment illustrates how {{tt|notify_all_at_thread_exit}} can be used to avoid accessing data that depends on thread locals while those thread locals are in the process of being destructed:
- | code=
+|code=
+#include <cassert>
+#include <condition_variable>
 #include <mutex>
+#include <string>
 #include <thread>
-#include <condtion_variable>
 std::mutex m;
 std::condition_variable cv;
 bool ready = false;
-ComplexType result;  // some arbitrary type
+std::string result; // some arbitrary type
 void thread_func()
 {
+    thread_local std::string thread_local_data = "42";
      std::unique_lock<std::mutex> lk(m);
      // assign a value to result using thread_local data
-     result = function_that_uses_thread_locals();
+     result = thread_local_data;
      ready = true;
      std::notify_all_at_thread_exit(cv, std::move(lk));
-} // 1. destroy thread_locals, 2. unlock mutex, 3. notify cv
+}   // 1. destroy thread_locals;
+    // 2. unlock mutex;
+    // 3. notify cv.
 int main()
 {
      std::thread t(thread_func);
      t.detach();
      // do other work
      // ...
      // wait for the detached thread
      std::unique_lock<std::mutex> lk(m);
-     while(!ready) {
+     cv.wait(lk, []{ return ready; });
-        cv.wait(lk);
-     }
+     // result is ready and thread_local destructors have finished, no UB
-     process(result); // result is ready and thread_local destructors have finished
+    assert(result == "42");
 }
- | output=
+|output=
 }}
+===Defect reports===
+{{dr list begin}}
+{{dr list item|wg=lwg|dr=2140|std=C++11|before=the call to {{tt|notify_all_at_thread_exit}}<br>synchronized with calls to functions waiting on {{c|cond}}|after=updated the synchronization<br>requirement}}
+{{dr list end}}
 ===See also===
 {{dsc begin}}
-{{dsc inc | cpp/thread/promise/dsc set_value_at_thread_exit}}
+{{dsc inc|cpp/thread/promise/dsc set_value_at_thread_exit}}
-{{dsc inc | cpp/thread/packaged_task/dsc make_ready_at_thread_exit}}
+{{dsc inc|cpp/thread/packaged_task/dsc make_ready_at_thread_exit}}
 {{dsc end}}
-[[de:cpp/thread/notify all at thread exit]]
+{{langlinks|de|es|fr|it|ja|pt|ru|zh}}
-[[es:cpp/thread/notify all at thread exit]]
-[[fr:cpp/thread/notify all at thread exit]]
-[[it:cpp/thread/notify all at thread exit]]
-[[ja:cpp/thread/notify all at thread exit]]
-[[pt:cpp/thread/notify all at thread exit]]
-[[ru:cpp/thread/notify all at thread exit]]
-[[zh:cpp/thread/notify all at thread exit]]

Compiler support
Freestanding and hosted
Language
Standard library
Standard library headers
Named requirements
Feature test macros (C++20)
Language support library
Concepts library (C++20)
Metaprogramming library (C++11)
Diagnostics library
General utilities library
Strings library
Containers library
Iterators library
Ranges library (C++20)
Algorithms library
Numerics library
Localizations library
Input/output library
Filesystem library (C++17)
Regular expressions library (C++11)
Concurrency support library (C++11)
Execution support library (C++26)
Technical specifications
Symbols index
External libraries

cppreference.com

Namespaces

Variants

Views

Actions

Difference between revisions of "cpp/thread/notify all at thread exit"

Latest revision as of 23:39, 13 March 2024

Contents

[edit] Notes

[edit] Parameters

[edit] Return value

[edit] Example

[edit] Defect reports

[edit] See also

Navigation

Toolbox