|
| 1 | +# starts_on |
| 2 | +* execution[meta header] |
| 3 | +* cpo[meta id-type] |
| 4 | +* std::execution[meta namespace] |
| 5 | +* cpp26[meta cpp] |
| 6 | + |
| 7 | +```cpp |
| 8 | +namespace std::execution { |
| 9 | + struct starts_on_t { unspecified }; |
| 10 | + inline constexpr starts_on_t starts_on{}; |
| 11 | +} |
| 12 | +``` |
| 13 | +* unspecified[italic] |
| 14 | +
|
| 15 | +## 概要 |
| 16 | +`starts_on`は、入力[Sender](sender.md)を指定[Scheduler](scheduler.md)に関連付けられた実行リソースに属する実行エージェント上で開始するSenderアダプタである。 |
| 17 | +
|
| 18 | +
|
| 19 | +## 効果 |
| 20 | +説明用の式`sch`と`sndr`に対して、`decltype((sch))`が[`scheduler`](scheduler.md)を満たさない、もしくは`decltype((sndr))`が[`sender`](sender.md)を満たさないとき、呼び出し式`starts_on(sch, sndr)`は不適格となる。 |
| 21 | +
|
| 22 | +そうでなければ、呼び出し式`starts_on(sch, sndr)`は`sch`が1回だけ評価されることを除いて、下記と等価。 |
| 23 | +
|
| 24 | +```cpp |
| 25 | +transform_sender( |
| 26 | + query-or-default(get_domain, sch, default_domain()), |
| 27 | + make-sender(starts_on, sch, sndr)) |
| 28 | +``` |
| 29 | +* transform_sender[link transform_sender.md] |
| 30 | +* query-or-default[link query-or-default.md.nolink] |
| 31 | +* get_domain[link get_domain.md] |
| 32 | +* default_domain()[link default_domain.md] |
| 33 | +* make-sender[link make-sender.md] |
| 34 | + |
| 35 | + |
| 36 | +### Senderアルゴリズムタグ `starts_on` |
| 37 | +説明用の式`out_sndr`と`env`に対して、型`OutSndr`を`decltype((out_sndr))`とする。[`sender-for`](sender-for.md)`<OutSndr, starts_on_t> == false`のとき、式`starts_on.transform_env(out_sndr, env)`および式`starts_on.transform_sender(out_sndr, env)`はいずれも不適格となる。 |
| 38 | + |
| 39 | +そうでなければ、下記の通り。 |
| 40 | + |
| 41 | +- 式`starts_on.transform_env(out_sndr, env)`は下記と等価。 |
| 42 | + |
| 43 | + ```cpp |
| 44 | + auto&& [_, sch, _] = out_sndr; |
| 45 | + return JOIN-ENV(SCHED-ENV(sch), FWD-ENV(env)); |
| 46 | + ``` |
| 47 | + * JOIN-ENV[link JOIN-ENV.md.nolink] |
| 48 | + * SCHED-ENV[link SCHED-ENV.md.nolink] |
| 49 | + * FWD-ENV[link ../forwarding_query.md] |
| 50 | + |
| 51 | +- 式`starts_on.transform_sender(out_sndr, env)`は下記と等価。 |
| 52 | + |
| 53 | + ```cpp |
| 54 | + auto&& [_, sch, sndr] = out_sndr; |
| 55 | + return let_value( |
| 56 | + schedule(sch), |
| 57 | + [sndr = std::forward_like<OutSndr>(sndr)]() mutable |
| 58 | + noexcept(is_nothrow_move_constructible_v<decay_t<OutSndr>>) { |
| 59 | + return std::move(sndr); |
| 60 | + }); |
| 61 | + ``` |
| 62 | + * let_value[link let_value.md.nolink] |
| 63 | + * schedule[link schedule.md] |
| 64 | + * is_nothrow_move_constructible_v[link /reference/type_traits/is_nothrow_move_constructible.md] |
| 65 | + * decay_t[link /reference/type_traits/decay.md] |
| 66 | + * std::move[link /reference/utility/move.md] |
| 67 | + |
| 68 | + |
| 69 | +## カスタマイゼーションポイント |
| 70 | +Senderアルゴリズム構築時に、[Scheduler](scheduler.md)`sch`に[関連付けられた実行ドメイン](query-or-default.md.nolink)に対して[`execution::transform_sender`](transform_sender.md)経由でSender変換が行われる。 |
| 71 | +[デフォルト実行ドメイン](../execution/default_domain.md)では無変換。 |
| 72 | + |
| 73 | +[Receiver](receiver.md)との[接続(connect)](connect.md)時に、[関連付けられた実行ドメイン](get-domain-late.md)に対して[`execution::transform_sender`](transform_sender.md)経由でSender変換が行われる。 |
| 74 | +[デフォルト実行ドメイン](../execution/default_domain.md)では`starts_on.transform_sender(out_sndr, env)`が呼ばれ、前述仕様通りのSenderへと変換される。 |
| 75 | + |
| 76 | +説明用の式`out_sndr`を`starts_on(sch, sndr)`の戻り値[Sender](sender.md)とし、型`OutSndr`を`decltype((out_sndr))`とする。式`out_rcvr`を[`sender_in`](sender_in.md)`<OutSndr, Env> == true`となる[環境](../queryable.md)`Env`に関連付けられた[Receiver](receiver.md)とする。`out_sndr`と`out_rcvr`との[接続(connect)](connect.md)結果[Operation State](operation_state.md)への左辺値参照を`op`としたとき、 |
| 77 | + |
| 78 | +- 呼び出し[`start`](start.md)`(op)`は、[Scheduler](scheduler.md)`sch`に関連づけられた実行リソースに属する実行エージェント上で入力[Sender](sender.md)`sndr`を開始すべき。 |
| 79 | +- `sch`上でのスケジューリングが失敗した場合、未規定の実行エージェント上で`out_rcvr`の[エラー完了](set_error.md)が行われるべき。 |
| 80 | + |
| 81 | + |
| 82 | +## 例 |
| 83 | +```cpp example |
| 84 | +#include <thread> |
| 85 | +#include <print> |
| 86 | +#include <execution> |
| 87 | +namespace ex = std::execution; |
| 88 | + |
| 89 | +int main() |
| 90 | +{ |
| 91 | + ex::run_loop loop; |
| 92 | + std::jthread worker{[&]{ |
| 93 | + std::println("start worker#{}", std::this_thread::get_id()); |
| 94 | + loop.run(); |
| 95 | + }}; |
| 96 | + |
| 97 | + ex::scheduler auto sch = loop.get_scheduler(); |
| 98 | + ex::sender auto sndr = |
| 99 | + ex::starts_on(sch, ex::just(21)) |
| 100 | + | ex::then([](int n) { |
| 101 | + std::println("on worker#{}", std::this_thread::get_id()); |
| 102 | + return n * 2; |
| 103 | + }); |
| 104 | + |
| 105 | + std::println("main#{}", std::this_thread::get_id()); |
| 106 | + |
| 107 | + auto [val] = std::this_thread::sync_wait(std::move(sndr)).value(); |
| 108 | + std::println("val={}", val); |
| 109 | + |
| 110 | + loop.finish(); |
| 111 | +} |
| 112 | +``` |
| 113 | +* ex::starts_on[color ff0000] |
| 114 | +* ex::run_loop[link run_loop.md] |
| 115 | +* ex::sender[link sender.md] |
| 116 | +* ex::scheduler[link scheduler.md] |
| 117 | +* ex::then[link then.md] |
| 118 | +* get_scheduler()[link run_loop/get_scheduler.md] |
| 119 | +* run()[link run_loop/run.md] |
| 120 | +* finish()[link run_loop/finish.md] |
| 121 | +* std::this_thread::sync_wait[link ../this_thread/sync_wait.md] |
| 122 | +* value()[link /reference/optional/optional/value.md] |
| 123 | +* std::move[link /reference/utility/move.md] |
| 124 | +* std::this_thread::get_id()[link /reference/thread/this_thread/get_id.md] |
| 125 | +
|
| 126 | +
|
| 127 | +### 出力例 |
| 128 | +``` |
| 129 | +main#126057012819776 |
| 130 | +start worker#126057007023680 |
| 131 | +on worker#126057007023680 |
| 132 | +val=42 |
| 133 | +``` |
| 134 | +
|
| 135 | +
|
| 136 | +## バージョン |
| 137 | +### 言語 |
| 138 | +- C++26 |
| 139 | +
|
| 140 | +### 処理系 |
| 141 | +- [Clang](/implementation.md#clang): ?? |
| 142 | +- [GCC](/implementation.md#gcc): ?? |
| 143 | +- [ICC](/implementation.md#icc): ?? |
| 144 | +- [Visual C++](/implementation.md#visual_cpp): ?? |
| 145 | +
|
| 146 | +
|
| 147 | +## 関連項目 |
| 148 | +- [`execution::schedule`](schedule.md) |
| 149 | +- [`execution::continues_on`](continues_on.md.nolink) |
| 150 | +- [`execution::on`](on.md.nolink) |
| 151 | +
|
| 152 | +
|
| 153 | +## 参照 |
| 154 | +- [P2999R3 Sender Algorithm Customization](https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2023/p2999r3.html) |
| 155 | +- [P2300R10 `std::execution`](https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2024/p2300r10.html) |
0 commit comments