cppdraft_translate/cppdraft/exec/scope.md

[exec.scope]

33 Execution control library [exec]

33.14 Execution scope utilities [exec.scope]

33.14.1 Execution scope concepts [exec.scope.concepts]

1

#

The scope_token concept defines the requirements on a type Token that can be used to create associations between senders and an async scope.

2

#

Let test-sender and test-env be unspecified types such thatsender_in<test-sender, test-env> is modeled.

namespace std::execution {templateconcept scope_token =copyable &&requires(const Token token) {{ token.try_associate() } -> same_as; { token.disassociate() } noexcept -> same_as; { token.wrap(declval<test-sender>()) } -> sender_in<test-env>; };}

3

#

A type Token models scope_token only if:

• (3.1)

no exceptions are thrown from copy construction, move construction, copy assignment, or move assignment of objects of type Token; and

• (3.2)

given an lvalue token of type (possibly const) Token, for all expressions sndr such thatdecltype((
sndr)) models sender:

• (3.2.1)

token.wrap(sndr) is a valid expression,

• (3.2.2)

decltype(token.wrap(sndr)) models sender, and

• (3.2.3)

completion_signatures_of_t<decltype(token.wrap(sndr)), E> contains the same completion signatures as completion_signatures_of_t<decltype((sndr)), E> for all types E such that sender_in<decltype((sndr)), E> is modeled.

33.14.2 Counting Scopes [exec.counting.scopes]

33.14.2.1 General [exec.counting.scopes.general]

1

#

Scopes of type simple_counting_scope and counting_scope maintain counts of associations.

Let:

• (1.1)

Scope be either simple_counting_scope or counting_scope,

• (1.2)

scope be an object of type Scope,

• (1.3)

tkn be an object of type Scope​::​token obtained from scope.get_token(),

• (1.4)

jsndr be a sender obtained from scope.join(), and

• (1.5)

op be an operation state obtained from connecting jsndr to a receiver.

During its lifetime scope goes through different states which govern what operations are allowed and the result of these operations:

• (1.6)

  unused: a newly constructed object starts in the unused state.

• (1.7)

  open: when tkn.try_associate() is called while scope is in the unused state,scope moves to the open state.

• (1.8)

  open-and-joining: when the operation state op is started while scope is in the unused or open state,scope moves to the open-and-joining state.

• (1.9)

  closed: when scope.close() is called while scope is in the open state,scope moves to the closed state.

• (1.10)

  unused-and-closed: when scope.close() is called while scope is in the unused state,scope moves to the unused-and-closed state.

• (1.11)

  closed-and-joining: when scope.close() is called while scope is in the open-and-joining state or the operation state op is started while scope is in the closed or unused-and-closed state,scope moves to the closed-and-joining state.

• (1.12)

  joined: when the count of associations drops to zero while scope is in the open-and-joining or closed-and-joining state,scope moves to the joined state.

2

#

Recommended practice: For simple_counting_scope and counting_scope, implementations should store the state and the count of associations in a single member of type size_t.

3

#

Subclause [exec.counting.scopes] makes use of the following exposition-only entities:

struct scope-join-t {}; // exposition onlyenum scope-state-type { // exposition only**unused, // exposition only**open, // exposition only**closed, // exposition only**open-and-joining, // exposition only**closed-and-joining, // exposition only**unused-and-closed, // exposition only**joined, // exposition only};

4

#

The exposition-only class template impls-for ([exec.snd.expos]) is specialized for scope-join-t as follows:

namespace std::execution {template<>struct impls-for<scope-join-t> : default-impls {template<class Scope, class Rcvr>struct state { // exposition onlystruct rcvr-t { // exposition onlyusing receiver_concept = receiver_t;

Rcvr& rcvr; // exposition onlyvoid set_value() && noexcept { execution::set_value(std::move(rcvr)); }templatevoid set_error(E&& e) && noexcept { execution::set_error(std::move(rcvr), std::forward(e)); }void set_stopped() && noexcept { execution::set_stopped(std::move(rcvr)); }decltype(auto) get_env() const noexcept {return execution::get_env(rcvr); }}; using sched-sender = // exposition onlydecltype(schedule(get_scheduler(get_env(declval<Rcvr&>())))); using op-t = // exposition only connect_result_t<sched-sender, rcvr-t>;

Scope* scope; // exposition only Rcvr& receiver; // exposition only**op-t op; // exposition only**state(Scope* scope, Rcvr& rcvr) // exposition onlynoexcept(nothrow-callable<connect_t, sched-sender, rcvr-t>): scope(scope), receiver(rcvr), op(connect(schedule(get_scheduler(get_env(rcvr))), rcvr-t(rcvr))) {}void complete() noexcept { // exposition only start(op); }void complete-inline() noexcept { // exposition only set_value(std::move(receiver)); }}; static constexpr auto get-state = // exposition only[](auto&& sender, Rcvr& receiver)noexcept(is_nothrow_constructible_v<state, data-type<decltype(sender)>, Rcvr&>) {auto[_, self] = sender; return state(self, receiver); }; static constexpr auto start = // exposition only[](auto& s, auto&) noexcept {if (s.scope->start-join-sender(s)) s.complete-inline(); }; };}

33.14.2.2 Simple Counting Scope [exec.scope.simple.counting]

33.14.2.2.1 General [exec.scope.simple.counting.general]

🔗

namespace std::execution {class simple_counting_scope {public:// [exec.simple.counting.token], tokenstruct token; static constexpr size_t max_associations = implementation-defined; // [exec.simple.counting.ctor], constructor and destructor simple_counting_scope() noexcept; simple_counting_scope(simple_counting_scope&&) = delete; ~simple_counting_scope(); // [exec.simple.counting.mem], members token get_token() noexcept; void close() noexcept; sender auto join() noexcept; private: size_t count; // exposition only**scope-state-type state; // exposition onlybool try-associate() noexcept; // exposition onlyvoid disassociate() noexcept; // exposition onlytemplatebool start-join-sender(State& state) noexcept; // exposition only};}

1

#

For purposes of determining the existence of a data race,get_token,close,join,try-associate,disassociate, andstart-join-sender behave as atomic operations ([intro.multithread]).

These operations on a single object of type simple_counting_scope appear to occur in a single total order.

33.14.2.2.2 Constructor and Destructor [exec.simple.counting.ctor]

🔗

simple_counting_scope() noexcept;

1

#

Postconditions: count is 0 and state is unused.

🔗

~simple_counting_scope();

2

#

Effects: If state is not one ofjoined, unused, or unused-and-closed, invokes terminate ([except.terminate]).

Otherwise, has no effects.

33.14.2.2.3 Members [exec.simple.counting.mem]

🔗

token get_token() noexcept;

1

#

Returns: An object t of type simple_counting_scope​::​token such thatt.scope == this is true.

🔗

void close() noexcept;

2

#

Effects: If state is

• (2.1)

unused, then changes state to unused-and-closed;

• (2.2)

open, then changes state to closed;

• (2.3)

open-and-joining, then changes state to closed-and-joining;

• (2.4)

otherwise, no effects.

3

#

Postconditions: Any subsequent call to try-associate() on *this returns false.

🔗

[sender](exec.snd.concepts#concept:sender "33.9.3 Sender concepts [exec.snd.concepts]") auto join() noexcept;

4

#

Returns: make-sender(scope-join-t(), this).

🔗

bool try-associate() noexcept;

5

#

Effects: If count is equal to max_associations, then no effects.

Otherwise, if state is

• (5.1)

unused, then increments count and changes state to open;

• (5.2)

open or open-and-joining, then increments count;

• (5.3)

otherwise, no effects.

6

#

Returns: true if count was incremented, false otherwise.

🔗

void disassociate() noexcept;

7

#

Preconditions: count is greater than zero.

8

#

Effects: Decrements count.

If count is zero after decrementing andstate is open-and-joining or closed-and-joining, changes state to joined and calls complete() on all objects registered with *this.

[Note 1:

Calling complete() on any registered object can cause *this to be destroyed.

— end note]

🔗

template<class State> bool start-join-sender(State& st) noexcept;

9

#

Effects: If state is

• (9.1)

unused, unused-and-closed, or joined, then changes state to joined and returns true;

• (9.2)

open or open-and-joining, then changes state to open-and-joining, registers st with *this and returns false;

• (9.3)

closed or closed-and-joining, then changes state to closed-and-joining, registers st with *this and returns false.

33.14.2.2.4 Token [exec.simple.counting.token]

🔗

namespace std::execution {struct simple_counting_scope::token {template<sender Sender> Sender&& wrap(Sender&& snd) const noexcept; bool try_associate() const noexcept; void disassociate() const noexcept; private: simple_counting_scope* scope; // exposition only};}

🔗

template<[sender](exec.snd.concepts#concept:sender "33.9.3 Sender concepts [exec.snd.concepts]") Sender> Sender&& wrap(Sender&& snd) const noexcept;

1

#

Returns: std​::​forward(snd).

🔗

bool try_associate() const noexcept;

2

#

Effects: Equivalent to: return scope->try-associate();

🔗

void disassociate() const noexcept;

3

#

Effects: Equivalent to scope->disassociate().

33.14.2.3 Counting Scope [exec.scope.counting]

🔗

namespace std::execution {class counting_scope {public:struct token {template<sender Sender>sender auto wrap(Sender&& snd) const noexcept(see below); bool try_associate() const noexcept; void disassociate() const noexcept; private: counting_scope* scope; // exposition only}; static constexpr size_t max_associations = implementation-defined;

counting_scope() noexcept; counting_scope(counting_scope&&) = delete; ~counting_scope();

token get_token() noexcept; void close() noexcept; sender auto join() noexcept; void request_stop() noexcept; private: size_t count; // exposition only**scope-state-type state; // exposition only inplace_stop_source s_source; // exposition onlybool try-associate() noexcept; // exposition onlyvoid disassociate() noexcept; // exposition onlytemplatebool start-join-sender(State& state) noexcept; // exposition only};}

1

#

counting_scope differs from simple_counting_scope by adding support for cancellation.

Unless specified below, the semantics of members of counting_scope are the same as the corresponding members of simple_counting_scope.

🔗

token get_token() noexcept;

2

#

Returns: An object t of type counting_scope​::​token such thatt.scope == this is true.

🔗

void request_stop() noexcept;

3

#

Effects: Equivalent to s_source.request_stop().

4

#

Remarks: Calls to request_stop do not introduce data races.

🔗

template<[sender](exec.snd.concepts#concept:sender "33.9.3 Sender concepts [exec.snd.concepts]") Sender> [sender](exec.snd.concepts#concept:sender "33.9.3 Sender concepts [exec.snd.concepts]") auto counting_scope::token::wrap(Sender&& snd) const noexcept(is_nothrow_constructible_v<remove_cvref_t<Sender>, Sender>);

5

#

Effects: Equivalent to:return stop-when(std::forward(snd), scope->s_source.get_token());