The abysmal diagnostic message problem and the lack of proper documentation making this library extremely unfriendly to newcomers

[SidneyCogdill]

If I were to write a new coroutine primitive type, I can start with the following prototype code:

struct A
{};

auto f() -> A
{
    co_return;
}

This won't work, but the compiler will happily point out the missing piece: This function cannot be a coroutine: 'std::coroutine_traits<A>' has no member named 'promise_type'. I add the promise_type and the error message changes to No member named 'return_void' in 'A::promise_type' and etc. I fix all the compile time errors and I already got a bare minimal working coroutine primitive type, without needing to resort to documentation once:

struct A
{
    struct promise_type
    {
        auto get_return_object() noexcept
        {
            return A{std::coroutine_handle<promise_type>::from_promise(*this)};
        }
        auto initial_suspend() noexcept { return std::suspend_never{}; }
        auto final_suspend() noexcept { return std::suspend_never{}; }
        auto return_void() noexcept {}
        auto unhandled_exception() noexcept {}
    };

    std::coroutine_handle<promise_type> ptr;
};

auto f() -> A
{
    std::puts("1");
    co_await std::suspend_always{};
    std::puts("3");
    co_return;
}

int main()
{
    auto handle = f();
    std::puts("2");
    handle.ptr.resume();
}

It's definitively still a long way from being actually useful, but the bootstrap parts can be mostly guided by the diagnostic messages.

This is not the case with stdexec. If I write prototype code in the same way:

struct A
{};

int main()
{
    auto a = A{};
    auto result = stdexec::sync_wait(a);
}

I get completely nonsense and useless diagnostic messages:

~/source/sender/src/main.cpp: In function 'int main()':
~/source/sender/src/main.cpp:18:37: error: no match for call to '(const stdexec::__sync_wait::sync_wait_t) (A&)'
   18 |     auto result = stdexec::sync_wait(a);
      |                   ~~~~~~~~~~~~~~~~~~^~~
In file included from ~/.cache/cpm/stdexec/568291d26902b7f877caaef97f4326958ea24212/include/stdexec/execution.hpp:56,
                 from ~/.cache/cpm/stdexec/568291d26902b7f877caaef97f4326958ea24212/include/exec/static_thread_pool.hpp:20,
                 from ~/source/sender/src/main.cpp:3:
~/.cache/cpm/stdexec/568291d26902b7f877caaef97f4326958ea24212/include/stdexec/__detail/__sync_wait.hpp:212:12: note: candidate: 'template<class _Sender>  requires (sender_in<_Sender, stdexec::__sync_wait::__env>) && ((__valid_sync_wait_argument<_Sender>) && (__has_implementation_for<stdexec::__sync_wait::sync_wait_t, decltype((stdexec::__declval())((__declval<_Sender>)(), stdexec::__declval())), _Sender>)) std::optional<typename stdexec::__sync_wait::__value_tuple_for<_Sender>::__t> stdexec::__sync_wait::sync_wait_t::operator()(_Sender&&) const'
  212 |       auto operator()(_Sender&& __sndr) const -> std::optional<__value_tuple_for_t<_Sender>> {
      |            ^~~~~~~~
~/.cache/cpm/stdexec/568291d26902b7f877caaef97f4326958ea24212/include/stdexec/__detail/__sync_wait.hpp:212:12: note:   template argument deduction/substitution failed:
~/.cache/cpm/stdexec/568291d26902b7f877caaef97f4326958ea24212/include/stdexec/__detail/__sync_wait.hpp:212:12: note: constraints not satisfied
In file included from ~/.cache/cpm/stdexec/568291d26902b7f877caaef97f4326958ea24212/include/stdexec/__detail/__debug.hpp:24,
                 from ~/.cache/cpm/stdexec/568291d26902b7f877caaef97f4326958ea24212/include/stdexec/__detail/__senders.hpp:25,
                 from ~/.cache/cpm/stdexec/568291d26902b7f877caaef97f4326958ea24212/include/stdexec/__detail/__as_awaitable.hpp:25,
                 from ~/.cache/cpm/stdexec/568291d26902b7f877caaef97f4326958ea24212/include/stdexec/execution.hpp:21:
~/.cache/cpm/stdexec/568291d26902b7f877caaef97f4326958ea24212/include/stdexec/__detail/__senders_core.hpp: In substitution of 'template<class _Sender>  requires (sender_in<_Sender, stdexec::__sync_wait::__env>) && ((__valid_sync_wait_argument<_Sender>) && (__has_implementation_for<stdexec::__sync_wait::sync_wait_t, decltype((stdexec::__declval())((__declval<_Sender>)(), stdexec::__declval())), _Sender>)) std::optional<typename stdexec::__sync_wait::__value_tuple_for<_Sender>::__t> stdexec::__sync_wait::sync_wait_t::operator()(_Sender&&) const [with _Sender = A&]':
~/source/sender/src/main.cpp:18:37:   required from here
   18 |     auto result = stdexec::sync_wait(a);
      |                   ~~~~~~~~~~~~~~~~~~^~~
~/.cache/cpm/stdexec/568291d26902b7f877caaef97f4326958ea24212/include/stdexec/__detail/__senders_core.hpp:48:11:   required for the satisfaction of 'sender<_Sender>' [with _Sender = A&]
~/.cache/cpm/stdexec/568291d26902b7f877caaef97f4326958ea24212/include/stdexec/__detail/__senders_core.hpp:56:11:   required for the satisfaction of 'sender_in<_Sender, stdexec::__sync_wait::__env>' [with _Sender = A&]
~/.cache/cpm/stdexec/568291d26902b7f877caaef97f4326958ea24212/include/stdexec/__detail/__senders_core.hpp:49:5: note: the expression 'enable_sender<typename'decltype_type' not supported by pp_cxx_unqualified_id::__f<_Ty> > [with _Sender = A&]' evaluated to 'false'
   49 |     enable_sender<__decay_t<_Sender>>                     //
      |     ^~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

It doesn't tell me what is missing at all. And I don't see a proper documentation properly specifying it either.

---

the proxy library by Mingxin recently got a new PR which greatly improved the diagnostic messages: microsoft/proxy#262. Perhaps stdexec could use a similar improvement?

[ericniebler]

thank you for raising this issue, you're absolutely right. this should have a better diagnostic that guides the user to toward writing a correct sender. I have converted this discussion into an issue to track it: #1480

[ericniebler]

i think #1504 improved the situation. can you give it a shot and let me know if there are additional diagnostic improvements you'd like to see?

[SidneyCogdill]

Hi, thanks for the quick implementation!

Using the commit f0998dd667f7cad390d152d320b668f642ae20cb with both GCC and Clang, I briefly played around with the diagnostic messages and found some issues:

1. When the sender is passed as lvalue reference (without std::move) the library incorrectly emits error The given type is not a sender because stdexec::enable_sender<Sender> is false even when using sender_concept = ex::sender_t; is present, and only goes away when completion_signatures is also declared.

Code	Diagnostic
struct my_sender { using sender_concept = ex::sender_t; }; int main() { auto a = my_sender{}; ex::sync_wait(a); }	The given type is not a sender because stdexec::enable_sender<Sender> is false
struct my_sender { using sender_concept = ex::sender_t; }; int main() { auto a = my_sender{}; ex::sync_wait(std::move(a)); }	The sender type was not able to report its completion signatures when asked
struct my_sender { using sender_concept = ex::sender_t; using completion_signatures = stdexec::completion_signatures<stdexec::set_value_t()>; }; int main() { auto a = my_sender{}; ex::sync_wait(std::move(a)); }	Deduced type 'invalid_op' does not satisfy 'operation_state' The sender passed to stdexec::sync_wait() does not have a .connect(<receiver>) member function that accepts sync_wait's receiver.

2. The library stops giving meaningful guide after the member function connect is declared. The diagnostic message seems to be affected by the return type constraint of the connect member function as well:

Code	Diagnostic
struct my_sender { using sender_concept = ex::sender_t; using completion_signatures = ex::completion_signatures<ex::set_value_t()>; auto connect(this my_sender &&self, ex::receiver auto snd) { return invalid_op{}; } }; int main() { auto a = my_sender{}; ex::sync_wait(std::move(a)); }	sender.connect(receiver) must return a type that satisfies the operation_state concept
struct my_sender { using sender_concept = ex::sender_t; using completion_signatures = ex::completion_signatures<ex::set_value_t()>; auto connect(this my_sender &&self, ex::receiver auto snd) -> ex::operation_state auto { return invalid_op{}; } }; int main() { auto a = my_sender{}; ex::sync_wait(std::move(a)); }	The sender passed to stdexec::sync_wait() does not have a .connect(<receiver>) member function that accepts sync_wait's receiver.

3. set_value type mismatch error does not have proper diagnostic message:

Code

Diagnostic

template<ex::receiver Rec> struct my_op { Rec rec; explicit my_op(Rec rec) : rec(std::move(rec)) {} my_op(my_op &&) = delete; auto start() noexcept { ex::set_value(std::move(rec), 1); } }; struct my_sender { using sender_concept = ex::sender_t; using completion_signatures = ex::completion_signatures<ex::set_value_t(std::string)>; auto connect(this my_sender &&self, ex::receiver auto snd) -> ex::operation_state auto { return my_op{std::move(snd)}; } };

error: No matching function for call to object of type 'const set_value_t'

4. I think the diagnostics can also provide an example code snippet which satisfies the requirements. For example, not all C++ users might know what does specialize mean.

struct some_user_supplied_type
{};

int main()
{
    ex::sync_wait(some_user_supplied_type{});
}

Current

Suggestion

The given type is not a sender because stdexec::enable_sender<Sender> is false. Either give the type a nested ::sender_concept typedef that is an alias for stdexec::sender_t, or else specialize the stdexec::enable_sender boolean trait for this type to true.

The given type is not a sender because stdexec::enable_sender<Sender> is false. Suggestion: Either give the type a nested public ::sender_concept typedef that is an alias for stdexec::sender_t: | struct YourType | { | ... | public: + using sender_concept = stdexec::sender_t; | ... | }; Or, specialize the stdexec::enable_sender boolean trait for this type to true if it isn't possible to directly modify the implementation of your type: | struct YourType { ... }; | + template<> constexpr auto stdexec::enable_sender<YourType> = true;

[SidneyCogdill]

Note: Although you probably knew it already, the multi-line diagnostic messages can be quoted in raw literal: https://godbolt.org/z/9GMMEb9Tq

    static_assert(false, R"(
Test
multi-line
message
nice
    )");

Therefore the suggestion to provide example code snippets is actually implementable (but most libraries don't do that).