Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

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
       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.

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
       constructor
	  (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   re-
       quest_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

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 ex-
       plicit 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)

Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=std::stop_source&sektion=3&manpath=FreeBSD+Ports+15.1.quarterly>

home | help