[#bsl-stop_token]
= xref:bsl.adoc[bsl]::stop_token
:relfileprefix: ../
:mrdocs:

This class is a mechanism for observing cancellation requests. An object of this class either has (possibly shared) ownership of a stop state and can be used to observe whether a cancellation request has been made on that stop state, or does not own a stop state. A `stop_token` cannot be used to make a cancellation request.

== Synopsis

Declared in `<bslstl_stoptoken.h>`

[source,cpp,subs="verbatim,replacements,macros,-callouts"]
----
class stop_token;
----

== Type Aliases

[cols="1,4"]
|===
| Name| Description
| xref:bsl/stop_token/callback_type.adoc[`callback_type`] 
| Alias for `stop_callback` parameterized by `t_CALLBACK`.
|===


== Member Functions

[cols="1,4"]
|===
| Name| Description
| xref:bsl/stop_token/2constructor-06.adoc[`stop_token`]         [.small]#[constructor]#
| Constructors
| xref:bsl/stop_token/2destructor.adoc[`~stop_token`] [.small]#[destructor]#
| Destroy this object.
| xref:bsl/stop_token/operator_assign-07.adoc[`operator=`] 
| Assignment operators
| xref:bsl/stop_token/stop_possible.adoc[`stop_possible`] 
| Return `true` if `*this` refers to a stop state, and either a stop was already requested on that stop state or there is at least one `stop_source` object that refers to that stop state (implying that a stop could still be requested using the `request_stop` function), and `false` otherwise. A call to `stop_possible` that is potentially concurrent with a call to `stop_requested` or `stop_possible` does not cause a data race.
| xref:bsl/stop_token/stop_requested.adoc[`stop_requested`] 
| Return `true` if `*this` refers to a stop state on which `request_stop` has been called, and `false` otherwise. If this function returns `true`, then the successful call to `request_stop` synchronizes with this call. A call to `stop_requested` that is potentially concurrent with a call to `stop_requested` or `stop_possible` does not cause a data race.
| xref:bsl/stop_token/swap.adoc[`swap`] 
| Set `*this` to refer to the stop state (or lack thereof) that the specified `other` referred to, and vice versa. Equivalent to `swap(*this, other)`.
|===


== Friends

[cols="1,4"]
|===
| Name| Description
| `xref:bsl/swap-06da.adoc[bsl::swap]`
| Set `lhs` to refer to the stop state (or lack thereof) that `rhs` referred to, and vice versa. Implementation note: this function is required by the standard to be a hidden friend ([hidden.friends], [stoptoken.general]).
| `xref:bsl/operator_eq-0c5.adoc[bsl::operator==]`
| Return `true` if the specified `lhs` and `rhs` refer to the same stop state, or if neither refers to a stop state; `false` otherwise. Implementation note: this function is required by the standard to be a hidden friend ([hidden.friends], [stoptoken.general]).
| `xref:bsl/stop_callback-06.adoc[bsl::stop_callback]`
| This class holds an object or reference of type `t_CALLBACK` and, when constructed using a `stop_token` that owns a stop state, schedules the held object or reference to be executed by the thread that requests cancellation on that stop state (if any). However, if cancellation was already requested before the `stop_callback` was constructed, the constructor invokes the callback immediately. If there is no stop state, or `request_stop` is never called for the stop state, then the callback is not invoked. `stop_callback` stores its callback within its own footprint, and thus never requires memory allocation; however, `stop_callback<t_CALLBACK>` is an allocator‐aware class, if `t_CALLBACK` is an allocator‐aware class, and any supplied allocator will then be passed to the constructor of `t_CALLBACK`.
| `xref:bsl/stop_source.adoc[bsl::stop_source]`
| This class is a mechanism for making and observing cancellation requests. An object of this class may have (possibly shared) ownership of a stop state, in which case it can be used to make a cancellation request or observe whether a cancellation request has been made on the owned stop state; it is also possible for a `stop_source` object to not own a stop state. Due to its shared ownership semantics, it is safe to pass a copy of a `stop_source` object to a callback that might outlive the original `stop_source` object; however, a callback that should only be able to observe a cancellation request, without being able to request cancellation itself, should instead be passed a `stop_token`, which can be created by calling `stop_source::get_token`.
|===


[.small]#Created with https://www.mrdocs.com[MrDocs]#