diff --git a/docs/overview.md b/docs/overview.md index fe560f8e..363b831a 100644 --- a/docs/overview.md +++ b/docs/overview.md @@ -446,7 +446,6 @@ The expression get_allocator(env) returns an alloca
  • the result of the expression satisfies simple-allocator.
    • Otherwise the expression is ill-formed. -
    Example @@ -560,7 +559,8 @@ Otherwise the value is never_stop_token{}. ## Customization Point Objects
    -connect(sender, receiver) -> operation_state +connect(sender, receiver) -> operation_state +The expresion connect(sender, receiver) combines sender and receiver into an operation state state. When this state gets started using start(state) the operation represented by sender gets started and reports its completion to receiver or an object copied or moved from receiver. While the operation state state isn’t started it can be destroyed but once it got started it needs to stay valid until one of the completion signals is called on receiver.
    set_error(receiver, error) noexcept -> void @@ -583,31 +583,122 @@ The expression start(state) starts the execution of the just(value...) -> sender-of<set_value_t(Value...)> -- just_error(error) -> sender-of<set_error_t(Error)> -- just_stopped() -> sender-of<set_stopped_t()> -- read_env(query) -> sender-of<set_value_t(query-result)> -- schedule(scheduler) -> sender-of<set_value_t()> +Sender factories create a sender which forms the start of a graph of lazy work items. + +
    +just(value...) -> sender-of<set_value_t(Value...)> +The expression just(value...) creates a sender which sends value... on the `set_value` (success) channel when started (note that value... can be empty). + +Completions +
      +
    • set_value_t(decltype(value)...)
      • +
    +
    +
    +just_error(error) -> sender-of<set_error_t(Error)> +The expression just_error(error) creates a sender which sends error on the `set_error` (failure) channel when started. + +Completions +
      +
    • set_error_t(decltype(error))
      • +
    +
    +
    +just_stopped() -> sender-of<set_stopped_t()> +The expression just_stopped() creates a sender which sends a completion on the `set_stopped` (cancellation) channel when started. + +Completions +
      +
    • set_stopped_t()
      • +
    +
    +
    +read_env(query) -> sender-of<set_value_t(query-result)> +The expression read_env(query) creates a sender which sends the result of querying query the environment of the receiver it gets connected to on the `set_value` channel when started. Put differently, it calls set_value(move(receiver), query(get_env(receiver))). For example, in a coroutine it may be useful to extra the stop token associated with the coroutine which can be done using read_env: + +```c++\ +auto token = co_await read_env(get_stop_token); +``` + +Completions +
      +
    • set_value_t(decltype(query(get_env(receiver)))) +
    +
    +
    +schedule(scheduler) -> sender-of<set_value_t()> +The expression schedule(scheduler) creates a sender which upon success completes on the set_value channel without any arguments running on the execution context associated with scheduler. Depending on the scheduler it is possible that the sender can complete with an error if the scheduling fails or using `set_stopped()` if the operation gets cancelled before it is successful. + +Completions +
      +
    • set_value_t() upon success
      • +
    • set_error_t(Error) upon failure if scheduler may fail
      • +
    • set_stopped_t() upon cancellation if scheduler supports cancellation +
    +
    ### Sender Adaptors +The sender adaptors take one or more senders and adapt their respective behavior to complete with a corresponding result. The description uses the informal function completions-of(sender) to represent the completion signatures which sender produces. Also, completion signatures are combined using +: the result is the deduplicated set of the combined completion signatures. + +
    +`bulk` +
    +
    +continues_on(sender, scheduler) -> sender-of<completions-of(sender) + completions-of(schedule(scheduler))> +The expression continues_on(sender, scheduler) creates a sender cs which starts sender when started. The results from sender are stored. Once that is cs creates a sender using schedule(scheduler) and completes itself on the execution once that sender completes. -- `bulk` -- continues_on(sender, scheduler) -> sender -- into_variant(sender) -> sender-of<set_value_t(std::variant<T...>)>` -- let_error(upstream, fun) -> sender -- let_stopped(upstream, fun) -> sender -- let_value(upstream, fun) -> sender -- `on` -- schedule_from(scheduler, sender) -> sender -- `split` -- starts_on(scheduler, sender) -> sender -- `stopped_as_error` -- `stopped_as_optional` -- then(upstream, fun) -> sender -- upon_error(upstream, fun) -> sender -- upon_stopped(upstream, fun) -> sender -- when_all(sender...) -> sender -- when_all_with_variant(sender...) -> sender +Completions +
      +
    • completions-of(sender)
      • +
    • completions-of(schedule(scheduler))
      • +
    +
    +
    +into_variant(sender) -> sender-of<set_value_t(std::variant<Tuple...>)> +The expression into_variant(sender) creates a sender which transforms the results of possibly multiple set_value completions of sender into one set_value completion respresenting the different upstream results as different options of a variant<Tuple...> where each Tuple is a tuple of values initialized with the respective arguments passed to set_value. The order of options in the variant isn’t specified. +
    +
    +let_error(upstream, fun) -> sender +
    +
    +let_stopped(upstream, fun) -> sender +
    +
    +let_value(upstream, fun) -> sender +
    +
    +`on` +
    +
    +schedule_from(scheduler, sender) -> sender +
    +
    +`split` +
    +
    +starts_on(scheduler, sender) -> sender +
    +
    +`stopped_as_error` +
    +
    +`stopped_as_optional` +
    +
    +then(upstream, fun) -> sender +
    +
    +upon_error(upstream, fun) -> sender +
    +
    +upon_stopped(upstream, fun) -> sender +
    +
    +when_all(sender...) -> sender +
    +
    +when_all_with_variant(sender...) -> sender +
    ### Sender Consumers