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

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

== Synopsis

Declared in `<bslstl_stoptoken.h>`

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

== Member Functions

[cols="1,4"]
|===
| Name| Description
| xref:bsl/stop_source/2constructor-053.adoc[`stop_source`]         [.small]#[constructor]#
| Constructors
| xref:bsl/stop_source/2destructor.adoc[`~stop_source`] [.small]#[destructor]#
| Destroy this object.
| xref:bsl/stop_source/operator_assign-00.adoc[`operator=`] 
| Assignment operators
| xref:bsl/stop_source/get_token.adoc[`get_token`] 
| Return a `stop_token` that refers to the stop state (or lack thereof) that `*this` refers to.
| xref:bsl/stop_source/request_stop.adoc[`request_stop`] 
| If `*this` refers to a stop state and that stop state has not had a stop requested yet, atomically request a stop on that stop state, invoke all registered callbacks in an unspecified order, and finally return `true`. Otherwise, return `false`. If this function returns `true`, the call synchronizes with any call to `stop_requested` that returns `true`. A call to `request_stop` that is potentially concurrent with a call to `stop_requested`, `stop_possible`, or `request_stop` does not cause a data race.
| xref:bsl/stop_source/stop_possible.adoc[`stop_possible`] 
| Return `true` if `*this` refers to a stop state, and `false` otherwise. A call to `stop_possible` that is potentially concurrent with a call to `stop_requested`, `stop_possible`, or `request_stop` does not cause a data race.
| xref:bsl/stop_source/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`, `stop_possible`, or `request_stop` does not cause a data race.
| xref:bsl/stop_source/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-03fc.adoc[bsl::swap]`
| Set `lhs` to refer to the stop state (or lack thereof) that `rhs` referred to before the call, and vice versa. Implementation note: this function is required by the standard to be a hidden friend ([hidden.friends], [stopsource.general]).
| `xref:bsl/operator_eq-067.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], [stopsource.general]).
|===


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