32 Thread support library [thread]

32.3 Stop tokens [thread.stoptoken]

32.3.1 Introduction [thread.stoptoken.intro]

Subclause [thread.stoptoken] describes components that can be used to asynchronously request that an operation stops execution in a timely manner, typically because the result is no longer required.
Such a request is called a stop request.
stop_­source, stop_­token, and stop_­callback implement semantics of shared ownership of a stop state.
Any stop_­source, stop_­token, or stop_­callback that shares ownership of the same stop state is an associated stop_­source, stop_­token, or stop_­callback, respectively.
The last remaining owner of the stop state automatically releases the resources associated with the stop state.
A stop_­token can be passed to an operation which can either
  • actively poll the token to check if there has been a stop request, or
  • register a callback using the stop_­callback class template which will be called in the event that a stop request is made.
A stop request made via a stop_­source will be visible to all associated stop_­token and stop_­source objects.
Once a stop request has been made it cannot be withdrawn (a subsequent stop request has no effect).
Callbacks registered via a stop_­callback object are called when a stop request is first made by any associated stop_­source object.
Calls to the functions request_­stop, stop_­requested, and stop_­possible do not introduce data races.
A call to request_­stop that returns true synchronizes with a call to stop_­requested on an associated stop_­token or stop_­source object that returns true.
Registration of a callback synchronizes with the invocation of that callback.