[exec.run.loop] - C++23 → Trunk

Files changed (1) hide show

tmp/tmp7htfzw8x/{from.md → to.md} +217 -0

tmp/tmp7htfzw8x/{from.md → to.md} RENAMED Viewed

	@@ -0,0 +1,217 @@

+### `execution::run_loop` <a id="exec.run.loop">[[exec.run.loop]]</a>
+#### General <a id="exec.run.loop.general">[[exec.run.loop.general]]</a>
+A `run_loop` is an execution resource on which work can be scheduled. It
+maintains a thread-safe first-in-first-out queue of work. Its `run`
+member function removes elements from the queue and executes them in a
+loop on the thread of execution that calls `run`.
+A `run_loop` instance has an associated *count* that corresponds to the
+number of work items that are in its queue. Additionally, a `run_loop`
+instance has an associated state that can be one of *starting*,
+*running*, *finishing*, or *finished*.
+Concurrent invocations of the member functions of `run_loop` other than
+`run` and its destructor do not introduce data races. The member
+functions *`pop-front`*, *`push-back`*, and `finish` execute atomically.
+*Recommended practice:* Implementations should use an intrusive queue of
+operation states to hold the work units to make scheduling
+allocation-free.
+``` cpp
+namespace std::execution {
+  class run_loop {
+    // [exec.run.loop.types], associated types
+    class run-loop-scheduler;                                   // exposition only
+    class run-loop-sender;                                      // exposition only
+    struct run-loop-opstate-base {                              // exposition only
+      virtual void execute() = 0;                               // exposition only
+      run_loop* loop;                                           // exposition only
+      run-loop-opstate-base* next;                              // exposition only
+    };
+    template<class Rcvr>
+      using run-loop-opstate = unspecified;                     // exposition only
+    // [exec.run.loop.members], member functions
+    run-loop-opstate-base* pop-front();                         // exposition only
+    void push-back(run-loop-opstate-base*);                     // exposition only
+  public:
+    // [exec.run.loop.ctor], constructor and destructor
+    run_loop() noexcept;
+    run_loop(run_loop&&) = delete;
+    ~run_loop();
+    // [exec.run.loop.members], member functions
+    run-loop-scheduler get_scheduler();
+    void run();
+    void finish();
+  };
+}
+```
+#### Associated types <a id="exec.run.loop.types">[[exec.run.loop.types]]</a>
+``` cpp
+class run-loop-scheduler;
+```
+*`run-loop-scheduler`* is an unspecified type that models `scheduler`.
+Instances of *`run-loop-scheduler`* remain valid until the end of the
+lifetime of the `run_loop` instance from which they were obtained.
+Two instances of *`run-loop-scheduler`* compare equal if and only if
+they were obtained from the same `run_loop` instance.
+Let *`sch`* be an expression of type *`run-loop-scheduler`*. The
+expression `schedule(sch)` has type *`run-loop- sender`* and is not
+potentially-throwing if *`sch`* is not potentially-throwing.
+``` cpp
+class run-loop-sender;
+```
+*`run-loop-sender`* is an exposition-only type that satisfies `sender`.
+`completion_signatures_of_t<run-{loop-sender}>` is
+``` cpp
+completion_signatures<set_value_t(), set_error_t(exception_ptr), set_stopped_t()>
+```
+An instance of *`run-loop-sender`* remains valid until the end of the
+lifetime of its associated `run_loop` instance.
+Let *`sndr`* be an expression of type *`run-loop-sender`*, let *`rcvr`*
+be an expression such that `receiver_of<decltype((rcvr)), CS>` is `true`
+where `CS` is the `completion_signatures` specialization above. Let `C`
+be either `set_value_t` or `set_stopped_t`. Then:
+- The expression `connect(sndr, rcvr)` has type
+  `run-loop-opstate<decay_t<decltype((rcvr))>>` and is
+  potentially-throwing if and only if `(void(sndr), auto(rcvr))` is
+  potentially-throwing.
+- The expression `get_completion_scheduler<C>(get_env(sndr))` is
+  potentially-throwing if and only if *`sndr`* is potentially-throwing,
+  has type *`run-loop-scheduler`*, and compares equal to the
+  *`run-loop- scheduler`* instance from which *`sndr`* was obtained.
+``` cpp
+template<class Rcvr>
+  struct run-loop-opstate;
+```
+`\exposid{run-loop-opstate}<Rcvr>`
+inherits privately and unambiguously from *`run-loop-opstate-base`*.
+Let o be a non-const lvalue of type `run-loop-opstate<Rcvr>`, and let
+`REC(o)` be a non-const lvalue reference to an instance of type `Rcvr`
+that was initialized with the expression *`rcvr`* passed to the
+invocation of connect that returned o. Then:
+- The object to which `REC(o)` refers remains valid for the lifetime of
+  the object to which o refers.
+- The type `run-loop-opstate<Rcvr>` overrides
+  `run-loop-opstate-base::execute()` such that `o.execute()` is
+  equivalent to:
+  ``` cpp
+  if (get_stop_token(REC(o)).stop_requested()) {
+    set_stopped(std::move(REC(o)));
+  } else {
+    set_value(std::move(REC(o)));
+  }
+  ```
+- The expression `start(o)` is equivalent to:
+  ``` cpp
+  try {
+    o.loop->push-back(addressof(o));
+  } catch(...) {
+    set_error(std::move(REC(o)), current_exception());
+  }
+  ```
+#### Constructor and destructor <a id="exec.run.loop.ctor">[[exec.run.loop.ctor]]</a>
+``` cpp
+run_loop() noexcept;
+```
+*Ensures:* The `run_loop` instance’s count is 0 and its state is
+starting.
+``` cpp
+~run_loop();
+```
+*Effects:* If the `run_loop` instance’s count is not 0 or if its state
+is running, invokes `terminate` [[except.terminate]]. Otherwise, has no
+effects.
+#### Member functions <a id="exec.run.loop.members">[[exec.run.loop.members]]</a>
+``` cpp
+run-loop-opstate-base* pop-front();
+```
+*Effects:* Blocks [[defns.block]] until one of the following conditions
+is `true`:
+- The `run_loop` instance’s count is 0 and its state is finishing, in
+  which case *pop-front* sets the state to finished and returns
+  `nullptr`; or
+- the `run_loop` instance’s count is greater than 0, in which case an
+  item is removed from the front of the queue, the count is decremented
+  by `1`, and the removed item is returned.
+``` cpp
+void push-back(run-loop-opstate-base* item);
+```
+*Effects:* Adds `item` to the back of the queue and increments the
+`run_loop` instance’s count by 1.
+*Synchronization:* This operation synchronizes with the *pop-front*
+operation that obtains `item`.
+``` cpp
+run-loop-scheduler get_scheduler();
+```
+*Returns:* An instance of *run-loop-scheduler* that can be used to
+schedule work onto this `run_loop` instance.
+``` cpp
+void run();
+```
+*Preconditions:* The `run_loop` instance’s state is either starting or
+finishing.
+*Effects:* If the `run_loop` instance’s state is starting, sets the
+state to running, otherwise leaves the state unchanged. Then, equivalent
+to:
+``` cpp
+while (auto* op = pop-front()) {
+  op->execute();
+}
+```
+*Remarks:* When the `run_loop` instance’s state changes, it does so
+without introducing data races.
+``` cpp
+void finish();
+```
+*Preconditions:* The `run_loop` instance’s state is either starting or
+running.
+*Effects:* Changes the `run_loop` instance’s state to finishing.
+*Synchronization:* `finish` synchronizes with the *pop-front* operation
+that returns `nullptr`.

Diff to HTML by rtfpessoa