From 76e383d8a0a600da0b87a4e87f73a93336af1f1b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Dietmar=20K=C3=BChl?= Date: Sun, 4 May 2025 21:46:09 +0100 Subject: [PATCH 1/2] add overview for some of the queries --- docs/overview.md | 105 ++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 100 insertions(+), 5 deletions(-) diff --git a/docs/overview.md b/docs/overview.md index bed646fd..fbe50900 100644 --- a/docs/overview.md +++ b/docs/overview.md @@ -336,7 +336,7 @@ struct example_state
unstoppable_token<_Token_> -The concept unstoppable_token<Token> is modeled by a _Token_ if stoppable_token<_Token_> is true and it can statically be determined that both _token_.stop_requested() and _token_.stop_possible() are `constexpr` epxressions yielding `false`. This concept is primarily used to avoid extra work when using stop tokens which will never indicate that cancellations are requested. +The concept unstoppable_token<Token> is modeled by a _Token_ if stoppable_token<_Token_> is true and it can statically be determined that both _token_.stop_requested() and _token_.stop_possible() are `constexpr` epxressions yielding `false`. This concept is used to avoid extra work when using stop tokens which will never indicate that cancellations are requested.
Example @@ -352,22 +352,117 @@ static_assert(not std::execution::unstoppable_token ## Queries -The queries are used to obtain properties associated with and object. Except forwarding_query and get_env the queries work on environments. +The queries are used to obtain properties associated with and object. Except forwarding_query, get_env, and get_completion_signatures the queries work on environments. The +environment queries are defined by providing a member query(query_t, a...) const on the environment object. +
+Example defining a query on an environment +This example shows how to define an environment class which provides a get_allocator query. The objects stores a `std::pmr::memory_resource*` and returns a correspondingly initialized `std::pmr::polymorphic_allocator<>`. +``` +struct alloc_env { + std::pmr::memory_resource res{std::pmr::new_delete_resource()}; + + auto query(get_allocator_t const&) const noexcept { + return std::pmr::polymorphic_allocator<>(this->res); + } +}; +``` +
forwarding_query(query) -> bool +**Default**: `false` +
+forwarding_query(query) is a `constexpr` query used to determine if the query query should be forwarded when wrapping an environment. +
+
+Example +When defining a custom query custom it is desirable to allow the query getting forwarded. It is necessary to explicit define the result of forwarding_query(custom). The result can be defined by providing a corresponding `query` member function. When using this approach the function isn’t allowed to throw, needs to return `bool`, and needs to be a core constant expression: + +``` +struct custom_t { + // ... + constexpr bool query(forwarding_query_t const&) const noexcept { + return true; + } +}; +inline constexpr custom_t custom{}; +``` + +Alternatively, the query can be defined as forwarding by deriving publicly from `forwarding_query_t`: + +``` +struct custom_t: forwarding_query_t { + // ... +}; +```
+
+
+
+get_env(queryable) -> env +**Default**: `empty_env` +
+get_env(queryable) is used to get the environment env associated with queryable. To provide a non-default environment for a queryable a `get_env` member needs to be defined. If queryable doesn’t provide the get_env query an object of type empty_env is returned. +
-get_env(queryable) +Example +The example defines an environment class env which stores a pointer to the relevant data and is returned as the environment for the type `queryable`: + +```c++ +struct data { /*...*/ }; + +struct env { data* d; /* ... */ }; + +struct queryable { + data* d;\ + // ... + env get_env() const noexcept { return { this->d }; } +}; +``` + +Note that the `get_env` member is both `const` and `noexcept`.
+
+
+
+get_allocator(env) -> allocator +**Default**: none +
+get_allocator(env) returns an allocator for any memory allocations in the respective context. If env doesn’t support this query any attempt to access it will result in a compilation error. +
-get_allocator(env) +Example +This example shows how to define an environment class which provides a get_allocator query. The objects stores a `std::pmr::memory_resource*` and returns a correspondingly initialized `std::pmr::polymorphic_allocator<>`. + +``` +struct alloc_env { + std::pmr::memory_resource res{std::pmr::new_delete_resource()}; + + auto query(get_allocator_t const&) const noexcept { + return std::pmr::polymorphic_allocator<>(this->res); + } +}; +``` +
+
-get_completion_scheduler(env) +get_completion_scheduler<tag>(env) -> scheduler +**Default**: none +
+If the expression get_completion_scheduler<tag>(get_env(sender)) is well-formed and returns a scheduler it defines the scheduler on which the completion tag executes. In particular get_completion_scheduler<set_value_t>(schedule(sched)) returns sched.
get_completion_signatures(sender, env) +The expression get_completion_signatures(sender, env) returns an object whose type is a specialization of completion_signatures defining the possible completion signatures of sender when connected to a receiver whose environment get_env(receiver) is env. A sender can define the result of this query either by defining a member function get_completion_signatures or using a type alias completion_signatures. +
+
+Example +When a sender doesn’t need to compute the completion signatures based on an environment it is easiest to use a the type alias: + + +
+
get_delegation_scheduler(env) From 17ed9296230b113f1b29ca20d7b86864101c8387 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Dietmar=20K=C3=BChl?= Date: Sun, 4 May 2025 22:41:48 +0100 Subject: [PATCH 2/2] fix trailing space --- docs/overview.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/overview.md b/docs/overview.md index fbe50900..82efafde 100644 --- a/docs/overview.md +++ b/docs/overview.md @@ -352,7 +352,7 @@ static_assert(not std::execution::unstoppable_token ## Queries -The queries are used to obtain properties associated with and object. Except forwarding_query, get_env, and get_completion_signatures the queries work on environments. The +The queries are used to obtain properties associated with an object. Except forwarding_query, get_env, and get_completion_signatures the queries work on environments. The environment queries are defined by providing a member query(query_t, a...) const on the environment object.
Example defining a query on an environment @@ -361,12 +361,12 @@ This example shows how to define an environment class which provides a (this->res); } }; -``` +```
forwarding_query(query) -> bool @@ -437,12 +437,12 @@ This example shows how to define an environment class which provides a (this->res); } }; -``` +```