86 lines
4.8 KiB
Markdown
86 lines
4.8 KiB
Markdown
[thread.stoptoken.intro]
|
||
|
||
# 32 Concurrency support library [[thread]](./#thread)
|
||
|
||
## 32.3 Stop tokens [[thread.stoptoken]](thread.stoptoken#intro)
|
||
|
||
### 32.3.1 Introduction [thread.stoptoken.intro]
|
||
|
||
[1](#1)
|
||
|
||
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/threads.tex#L449)
|
||
|
||
Subclause [[thread.stoptoken]](thread.stoptoken "32.3 Stop tokens") 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[.](#1.sentence-1)
|
||
|
||
Such a request is called a [*stop request*](#def:stop_request "32.3.1 Introduction [thread.stoptoken.intro]")[.](#1.sentence-2)
|
||
|
||
[2](#2)
|
||
|
||
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/threads.tex#L455)
|
||
|
||
The concepts[*stoppable-source*](stoptoken.concepts#concept:stoppable-source "32.3.3 Stop token concepts [stoptoken.concepts]"),[stoppable_token](stoptoken.concepts#concept:stoppable_token "32.3.3 Stop token concepts [stoptoken.concepts]"), and[*stoppable-callback-for*](stoptoken.concepts#concept:stoppable-callback-for "32.3.3 Stop token concepts [stoptoken.concepts]") specify the required syntax and semantics of
|
||
shared access to a [*stop state*](#def:stop_state "32.3.1 Introduction [thread.stoptoken.intro]")[.](#2.sentence-1)
|
||
|
||
Any object modeling [*stoppable-source*](stoptoken.concepts#concept:stoppable-source "32.3.3 Stop token concepts [stoptoken.concepts]"),[stoppable_token](stoptoken.concepts#concept:stoppable_token "32.3.3 Stop token concepts [stoptoken.concepts]"), or[*stoppable-callback-for*](stoptoken.concepts#concept:stoppable-callback-for "32.3.3 Stop token concepts [stoptoken.concepts]") that refers to the same stop state is
|
||
an [*associated*](#def:associated "32.3.1 Introduction [thread.stoptoken.intro]")[*stoppable-source*](stoptoken.concepts#concept:stoppable-source "32.3.3 Stop token concepts [stoptoken.concepts]"),[stoppable_token](stoptoken.concepts#concept:stoppable_token "32.3.3 Stop token concepts [stoptoken.concepts]"), or[*stoppable-callback-for*](stoptoken.concepts#concept:stoppable-callback-for "32.3.3 Stop token concepts [stoptoken.concepts]"),
|
||
respectively[.](#2.sentence-2)
|
||
|
||
[3](#3)
|
||
|
||
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/threads.tex#L472)
|
||
|
||
An object of a type that models [stoppable_token](stoptoken.concepts#concept:stoppable_token "32.3.3 Stop token concepts [stoptoken.concepts]") can be passed to an operation that can either
|
||
|
||
- [(3.1)](#3.1)
|
||
|
||
actively poll the token to check if there has been a stop request, or
|
||
|
||
- [(3.2)](#3.2)
|
||
|
||
register a callback that
|
||
will be called in the event that a stop request is made[.](#3.sentence-1)
|
||
|
||
A stop request made via an object
|
||
whose type models [*stoppable-source*](stoptoken.concepts#concept:stoppable-source "32.3.3 Stop token concepts [stoptoken.concepts]") will be visible to
|
||
all associated [stoppable_token](stoptoken.concepts#concept:stoppable_token "32.3.3 Stop token concepts [stoptoken.concepts]") and[*stoppable-source*](stoptoken.concepts#concept:stoppable-source "32.3.3 Stop token concepts [stoptoken.concepts]") objects[.](#3.sentence-2)
|
||
|
||
Once a stop request has been made it cannot be withdrawn
|
||
(a subsequent stop request has no effect)[.](#3.sentence-3)
|
||
|
||
[4](#4)
|
||
|
||
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/threads.tex#L488)
|
||
|
||
Callbacks registered via an object
|
||
whose type models [*stoppable-callback-for*](stoptoken.concepts#concept:stoppable-callback-for "32.3.3 Stop token concepts [stoptoken.concepts]") are called when a stop request is first made
|
||
by any associated [*stoppable-source*](stoptoken.concepts#concept:stoppable-source "32.3.3 Stop token concepts [stoptoken.concepts]") object[.](#4.sentence-1)
|
||
|
||
[5](#5)
|
||
|
||
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/threads.tex#L494)
|
||
|
||
The types stop_source and stop_token and
|
||
the class template stop_callback implement
|
||
the semantics of shared ownership of a stop state[.](#5.sentence-1)
|
||
|
||
The last remaining owner of the stop state automatically releases
|
||
the resources associated with the stop state[.](#5.sentence-2)
|
||
|
||
[6](#6)
|
||
|
||
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/threads.tex#L501)
|
||
|
||
An object of type inplace_stop_source is the sole owner of its stop state[.](#6.sentence-1)
|
||
|
||
An object of type inplace_stop_token or
|
||
of a specialization of the class template inplace_stop_callback does not participate in ownership of its associated stop state[.](#6.sentence-2)
|
||
|
||
[*Note [1](#note-1)*:
|
||
|
||
They are for use when all uses of the associated token and callback objects
|
||
are known to nest within the lifetime of the inplace_stop_source object[.](#6.sentence-3)
|
||
|
||
â *end note*]
|