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

FreeBSD Manual Pages

  
 
  

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

NAME
       std::stop_callback - std::stop_callback

Synopsis
	  Defined in header <stop_token>
	  template< class Callback >	  (since C++20)
	  class	stop_callback;

	  The  stop_callback  class template provides an RAII object type that
       registers a
	  callback function for	an  associated	std::stop_token	 object,  such
       that the	callback
	  function  will  be  invoked  when  the  std::stop_token's associated
       std::stop_source	is
	  requested to stop.

	  Callback functions registered	via  stop_callback's  constructor  are
       invoked either in
	  the  same  thread  that  successfully	 invokes  request_stop() for a
       std::stop_source	of
	  the stop_callback's associated std::stop_token; or if	stop  has  al-
       ready been
	  requested prior to the constructor's registration, then the callback
       is invoked in
	  the thread constructing the stop_callback.

	  More	 than	one   stop_callback   can  be  created	for  the  same
       std::stop_token,	from the
	  same or different threads concurrently. No guarantee is provided for
       the order in
	  which	they will be executed, but they	will be	invoked	synchronously;
       except for
	  stop_callback(s) constructed after stop has already  been  requested
       for the
	  std::stop_token, as described	previously.

	  If an	invocation of a	callback exits via an exception	then std::ter-
       minate is called.

	  std::stop_callback  is  not CopyConstructible, CopyAssignable, Move-
       Constructible, nor
	  MoveAssignable.

	  The template param Callback type must	be both	invocable and destruc-
       tible. Any return
	  value	is ignored.

Member types
	  Type		Definition
	  callback_type	Callback

Member functions
	  constructor	constructs new stop_callback object
			(public	member function)
	  destructor	destructs the stop_callback object
			(public	member function)
	  operator=	stop_callback is not assignable
	  [deleted]	(public	member function)

	 Deduction guides

Example
       // Run this code

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

	using namespace	std::chrono_literals;

	// Use a helper	class for atomic std::cout streaming
	class Writer
	{
		std::ostringstream buffer;
	public:
		~Writer() {
			std::cout << buffer.str();
		}
		Writer&	operator<<(auto	input) {
			buffer << input;
			return *this;
		}
	};

	int main()
	{
		// A worker thread
		// It will wait	until it is requested to stop.
		std::jthread worker([] (std::stop_token	stoken)	{
			Writer()   <<	 "Worker    thread's	id:    "    <<
       std::this_thread::get_id() << '\n';
			std::mutex mutex;
			std::unique_lock lock(mutex);
			std::condition_variable_any().wait(lock, stoken,
				[&stoken]  {  return  stoken.stop_requested();
       });
		});

		// Register a stop callback on the worker thread.
		std::stop_callback callback(worker.get_stop_token(), []	{
			Writer() << "Stop callback executed by thread: "
				<< std::this_thread::get_id() << '\n';
		});

		// stop_callback objects can be	destroyed prematurely to  pre-
       vent execution
		{
			std::stop_callback scoped_callback(worker.get_stop_to-
       ken(), [] {
				// This	will not be executed.
				Writer()  << "Scoped stop callback executed by
       thread: "
					<< std::this_thread::get_id() << '\n';
			});
		}

		// Demonstrate which thread  executes  the  stop_callback  and
       when.
		// Define a stopper function
		auto stopper_func = [&worker] {
			if(worker.request_stop())
				Writer()  << "Stop request executed by thread:
       "
					<< std::this_thread::get_id() << '\n';
			else
				Writer() <<  "Stop  request  not  executed  by
       thread: "
					<< std::this_thread::get_id() << '\n';
		};

		// Let multiple	threads	compete	for stopping the worker	thread
		std::jthread stopper1(stopper_func);
		std::jthread stopper2(stopper_func);
		stopper1.join();
		stopper2.join();

		// After a stop	has already been requested,
		// a new stop_callback executes	immediately.
		Writer()  <<  "Main thread: " << std::this_thread::get_id() <<
       '\n';
		std::stop_callback     callback_after_stop(worker.get_stop_to-
       ken(), [] {
			Writer() << "Stop callback executed by thread: "
				<< std::this_thread::get_id() << '\n';
		});
	}

Possible output:
	Worker thread's	id: 140460265039616
	Stop callback executed by thread: 140460256646912
	Stop request executed by thread: 140460256646912
	Stop request not executed by thread: 140460248254208
	Main thread: 140460265043776
	Stop callback executed by thread: 140460265043776

http://cppreference.com		  2022.07.31		 std::stop_callback(3)

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

home | help