home | help 
std::stop_source(3)	       C++ Standard Libary	     std::stop_source(3)

NAME
     std::stop_source - std::stop_source

Synopsis
	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  ob-
     ject 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  re-
     quests have no
	effect.

Member functions
	constructor    constructs new stop_source object
		       (public member function)
	destructor     destructs the stop_source object
		       (public member function)
	operator=      assigns the stop_source object
		       (public member function)

Modifiers
	request_stop	makes  a  stop request for the associated stop-state, if
     any
		       (public member function)
	swap	       swaps two stop_source objects
		       (public member function)

Observers
	get_token      returns a stop_token for the associated stop-state
		       (public member function)
	stop_requested checks whether the associated  stop-state  has  been  re-
     quested to stop
		       (public member function)
	stop_possible	checks whether associated stop-state can be requested to
     stop
		       (public member function)

Non-member functions
	operator==	       compares two std::stop_source objects
			       (function)
	swap(std::stop_source) specializes the std::swap algorithm
	(C++20) 	       (function)

	Helper constants

	nostopstate a std::nostopstate_t instance for use  in  stop_source  con-
     structor
	(C++20)     (constant)

Helper classes
	nostopstate_t placeholder type for use in stop_source constructor
	(C++20)       (class)

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 us-
     ing 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

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_source stop_source)
      {
	  std::stop_token stoken = stop_source.get_token();
	  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);

	  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

http://cppreference.com 	   2024.06.10		     std::stop_source(3)
home | help