Namespaces
Variants
Views
Actions

Difference between revisions of "cpp/thread/stop source"

From cppreference.com
< cpp‎ | thread
(add nostopstate_t)
(Better to pass stop_token instead of stop_source to wroker thread function)
 
(9 intermediate revisions by 7 users not shown)
Line 1: Line 1:
 
{{cpp/title|stop_source}}
 
{{cpp/title|stop_source}}
 
{{cpp/thread/stop_source/navbar}}
 
{{cpp/thread/stop_source/navbar}}
−
{{ddcl | header=stop_token | since=c++20 | 1=
+
{{ddcl|header=stop_token|since=c++20|
 
class stop_source;
 
class stop_source;
 
}}
 
}}
  
−
The {{tt|stop_source}} class provides the means to issue a stop request, such as for {{tt|std::jthread}} cancellation. A stop request made for one {{tt|stop_source}} object is visible to all {{tt|stop_source}}s and {{tt|std::stop_token}}s of the same associated stop-state; any {{tt|std::stop_callback}}(s) registered for associated {{tt|std::stop_token}}(s) will be invoked, and any {{lc|std::condition_variable_any}} objects waiting on associated {{tt|std::stop_token}}(s) will be awoken.
+
The {{tt|stop_source}} class provides the means to issue a stop request, such as for {{lc|std::jthread}} cancellation. A stop request made for one {{tt|stop_source}} object is visible to all {{tt|stop_source}}s and {{lc|std::stop_token}}s of the same associated stop-state; any {{lc|std::stop_callback}}(s) registered for associated {{lc|std::stop_token}}(s) will be invoked, and any {{lc|std::condition_variable_any}} objects waiting on associated {{lc|std::stop_token}}(s) will be awoken.
  
 
Once a stop is requested, it cannot be withdrawn. Additional stop requests have no effect.
 
Once a stop is requested, it cannot be withdrawn. Additional stop requests have no effect.
Line 11: Line 11:
 
===Member functions===
 
===Member functions===
 
{{dsc begin}}
 
{{dsc begin}}
−
{{dsc inc | cpp/thread/stop_source/dsc constructor}}
+
{{dsc inc|cpp/thread/stop_source/dsc constructor}}
−
{{dsc inc | cpp/thread/stop_source/dsc destructor}}
+
{{dsc inc|cpp/thread/stop_source/dsc destructor}}
−
{{dsc inc | cpp/thread/stop_source/dsc operator{{=}} | assigns the stop_source}}
+
{{dsc inc|1=cpp/thread/stop_source/dsc operator=}}
  
−
{{dsc h2 | Modifiers}}
+
{{dsc h2|Modifiers}}
−
{{dsc inc | cpp/thread/stop_source/dsc request_stop}}
+
{{dsc inc|cpp/thread/stop_source/dsc request_stop}}
−
{{dsc inc | cpp/thread/stop_source/dsc swap}}
+
{{dsc inc|cpp/thread/stop_source/dsc swap}}
  
−
{{dsc h2 | Observers}}
+
{{dsc h2|Observers}}
−
{{dsc inc | cpp/thread/stop_source/dsc get_token}}
+
{{dsc inc|cpp/thread/stop_source/dsc get_token}}
−
{{dsc inc | cpp/thread/stop_source/dsc stop_requested}}
+
{{dsc inc|cpp/thread/stop_source/dsc stop_requested}}
−
{{dsc inc | cpp/thread/stop_source/dsc stop_possible}}
+
{{dsc inc|cpp/thread/stop_source/dsc stop_possible}}
 
{{dsc end}}
 
{{dsc end}}
  
 
===Non-member functions===
 
===Non-member functions===
 
{{dsc begin}}
 
{{dsc begin}}
−
{{dsc inc | cpp/thread/stop_source/dsc operator_cmp}}
+
{{dsc inc|cpp/thread/stop_source/dsc operator_cmp}}
−
{{dsc inc | cpp/thread/stop_source/dsc swap2}}
+
{{dsc inc|cpp/thread/stop_source/dsc swap2}}
 
{{dsc end}}
 
{{dsc end}}
  
−
===Helper classes===
+
===Helper tags===
 
{{dsc begin}}
 
{{dsc begin}}
−
{{dsc inc | cpp/thread/stop_source/dsc nostopstate_t}}
+
{{dsc inc|cpp/thread/stop_source/dsc nostopstate}}
 
{{dsc end}}
 
{{dsc end}}
  
 
===Notes===
 
===Notes===
−
For the purposes of {{tt|std::jthread}} cancellation the {{tt|stop_source}} object should be retrieved from the {{tt|std::jthread}} object using {{c|1=get_stop_source()}}; or stop should be requested directly from the {{tt|std::jthread}} object using {{c|1=request_stop()}}. This will then use the same associated stop-state as that passed into the {{tt|std::jthread}}'s invoked function argument (i.e., the function being executed on its thread).
+
For the purposes of {{lc|std::jthread}} cancellation the {{tt|stop_source}} object should be retrieved from the {{lc|std::jthread}} object using {{ltf|cpp/thread/jthread/get_stop_source}}; or stop should be requested directly from the {{lc|std::jthread}} object using {{ltf|cpp/thread/jthread/request_stop}}. This will then use the same associated stop-state as that passed into the {{lc|std::jthread}}'s invoked function argument (i.e., the function being executed on its thread).
  
 
For other uses, however, a {{tt|stop_source}} can be constructed separately using the default constructor, which creates new stop-state.
 
For other uses, however, a {{tt|stop_source}} can be constructed separately using the default constructor, which creates new stop-state.
 +
 +
{{feature test macro|__cpp_lib_jthread|std=C++20|value=201911L|{{rlp|stop_token|Stop token}} and {{rlp|jthread|joining thread}}}}
  
 
===Example===
 
===Example===
−
{{todo}}
+
{{example
 +
|code=
 +
#include <chrono>
 +
#include <iostream>
 +
#include <stop_token>
 +
#include <thread>
 +
 
 +
using namespace std::chrono_literals;
 +
 
 +
void worker_fun(int id, std::stop_token stoken)
 +
{
 +
    for (int i = 10; i; --i)
 +
    {
 +
        std::this_thread::sleep_for(300ms);
 +
        if (stoken.stop_requested())
 +
        {
 +
            std::printf("  worker%d is requested to stop\n", id);
 +
            return;
 +
        }
 +
        std::printf("  worker%d goes back to sleep\n", id);
 +
    }
 +
}
 +
 
 +
int main()
 +
{
 +
    std::jthread threads[4];
 +
    std::cout << std::boolalpha;
 +
    auto print = [](const std::stop_source& source)
 +
    {
 +
        std::printf("stop_source stop_possible = %s, stop_requested = %s\n",
 +
                    source.stop_possible() ? "true" : "false",
 +
                    source.stop_requested() ? "true" : "false");
 +
    };
 +
 
 +
    // Common source
 +
    std::stop_source stop_source;
 +
 
 +
    print(stop_source);
 +
 
 +
    // Create worker threads
 +
    for (int i = 0; i < 4; ++i)
 +
        threads[i] = std::jthread(worker_fun, i + 1, stop_source.get_token());
 +
 
 +
    std::this_thread::sleep_for(500ms);
 +
 
 +
    std::puts("Request stop");
 +
    stop_source.request_stop();
 +
 
 +
    print(stop_source);
 +
 
 +
    // Note: destructor of jthreads will call join so no need for explicit calls
 +
}
 +
|p=true
 +
|output=
 +
stop_source stop_possible = true, stop_requested = false
 +
  worker2 goes back to sleep
 +
  worker3 goes back to sleep
 +
  worker1 goes back to sleep
 +
  worker4 goes back to sleep
 +
Request stop
 +
stop_source stop_possible = true, stop_requested = true
 +
  worker3 is requested to stop
 +
  worker1 is requested to stop
 +
  worker2 is requested to stop
 +
  worker4 is requested to stop
 +
}}
 +
 
 +
{{langlinks|es|ja|ru|zh}}

Latest revision as of 10:31, 16 July 2024

 
C++
 
Concurrency support library
Threads
(C++11)
(C++20)
(C++17)(C++17)
this_thread namespace
(C++11)
(C++11)
(C++11)
(C++11)
Cooperative cancellation
(C++20)
(C++26)
(C++26)
stop_source
(C++20)
(C++26)  
(C++20)
Mutual exclusion
(C++11)
(C++11)
(C++17)
Generic lock management
(C++11)
(C++11)
(C++17)
(C++11)
(C++14)
(C++11)
(C++11)
(C++11)
(C++11)(C++11)(C++11)(C++11)(C++11)(C++11)
Condition variables
(C++11)
(C++11)
(C++11)
(C++11)
Semaphores
(C++20)(C++20)
Latches and Barriers
(C++20)
(C++20)
Futures
(C++11)
(C++11)
(C++11)
(C++11)
(C++11)
(C++11)
(C++11)
(C++11)
(C++11)
(C++11)
Safe Reclamation
(C++26)
(C++26)
(C++26)
Hazard Pointers
(C++26)
(C++26)
(C++26)
Atomic types
(C++11)
(C++20)
(C++11)
Initialization of atomic types
(C++11)(deprecated in C++20)
(C++11)(deprecated in C++20)
(C++11)
Memory ordering
(C++11)
(C++11)
(C++11)
(C++11)
Free functions for atomic operations
(C++11)(C++11)
(C++11)(C++11)
(C++11)(C++11)
(C++11)(C++11)(C++11)(C++11)
(C++11)(C++11)
(C++11)(C++11)
(C++11)(C++11)
(C++11)(C++11)
(C++11)(C++11)
(C++26)(C++26)
(C++26)(C++26)
(C++11)
(C++20)(C++20)
(C++20)
(C++20)
Free functions for atomic flags
(C++11)(C++11)
(C++11)(C++11)
(C++20)(C++20)
(C++20)(C++20)
(C++20)
(C++20)
 
std::stop_source
 
Defined in header <stop_token>
class stop_source;
 (since C++20)

The stop_source class provides the means to issue a stop request, such as for std::jthread cancellation. A stop request made for one stop_source object is visible to all stop_sources and std::stop_tokens of the same associated stop-state; any std::stop_callback(s) registered for associated std::stop_token(s) will be invoked, and any std::condition_variable_any objects waiting on associated std::stop_token(s) will be awoken.

Once a stop is requested, it cannot be withdrawn. Additional stop requests have no effect.

Contents

[edit] Member functions

 constructs new stop_source object
(public member function) [edit]
destructs the stop_source object
(public member function) [edit]
assigns the stop_source object
(public member function) [edit]
Modifiers
makes a stop request for the associated stop-state, if any
(public member function) [edit]
swaps two stop_source objects
(public member function) [edit]
Observers
returns a stop_token for the associated stop-state
(public member function) [edit]
checks whether the associated stop-state has been requested to stop
(public member function) [edit]
checks whether associated stop-state can be requested to stop
(public member function) [edit]

[edit] Non-member functions

(C++20)
 compares two std::stop_source objects
(function) [edit]
(C++20)
 specializes the std::swap algorithm
(function) [edit]

[edit] Helper tags

(C++20)
 a tag used for stop_source to indicate no associated stop-state upon construction
(tag)[edit]

[edit] Notes

For the purposes of std::jthread cancellation the stop_source object should be retrieved from the std::jthread object using get_stop_source(); or stop should be requested directly from the std::jthread object using request_stop(). This will then use the same associated stop-state as that passed into the std::jthread's invoked function argument (i.e., the function being executed on its thread).

For other uses, however, a stop_source can be constructed separately using the default constructor, which creates new stop-state.

Feature-test macro Value Std Feature
__cpp_lib_jthread 201911L (C++20) Stop token and joining thread

[edit] Example

Run this code
#include <chrono>
#include <iostream>
#include <stop_token>
#include <thread>
 
using namespace std::chrono_literals;
 
void worker_fun(int id, std::stop_token stoken)
{ 
    for (int i = 10; i; --i)
    {
        std::this_thread::sleep_for(300ms);
        if (stoken.stop_requested())
        {
            std::printf("  worker%d is requested to stop\n", id);
            return;
        }
        std::printf("  worker%d goes back to sleep\n", id);
    }
}
 
int main()
{
    std::jthread threads[4];
    std::cout << std::boolalpha;
    auto print = [](const std::stop_source& source)
    {
        std::printf("stop_source stop_possible = %s, stop_requested = %s\n",
                    source.stop_possible() ? "true" : "false",
                    source.stop_requested() ? "true" : "false");
    };
 
    // Common source
    std::stop_source stop_source;
 
    print(stop_source);
 
    // Create worker threads
    for (int i = 0; i < 4; ++i)
        threads[i] = std::jthread(worker_fun, i + 1, stop_source.get_token());
 
    std::this_thread::sleep_for(500ms);
 
    std::puts("Request stop");
    stop_source.request_stop();
 
    print(stop_source);
 
    // Note: destructor of jthreads will call join so no need for explicit calls
}

Possible output: 

stop_source stop_possible = true, stop_requested = false
  worker2 goes back to sleep
  worker3 goes back to sleep
  worker1 goes back to sleep
  worker4 goes back to sleep
Request stop
stop_source stop_possible = true, stop_requested = true
  worker3 is requested to stop
  worker1 is requested to stop
  worker2 is requested to stop
  worker4 is requested to stop
Retrieved from "https://en.cppreference.com/mwiki/index.php?title=cpp/thread/stop_source&oldid=173680"