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 prevent
       execution.
	    {
		std::stop_callback scoped_callback(worker.get_stop_token(), []
		{
		    // 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_token(), []
	    {
		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		  2024.06.10		 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.1.quarterly>

home | help