feat engine: return failure reason from WaitAnyContext::Wait

* Changed @ref engine::WaitAnyContext::Wait, `WaitUntil` and `WaitFor` to return `utils::expected<std::uint64_t, engine::WaitAnyError>` instead of `std::optional<std::uint64_t>`, distinguishing cancellation, timeout and empty-context cases.

  Migration: `result.has_value()` and `*result` keep working as before; replace comparisons with `std::nullopt` with `result.has_value()`, and use `result.error()` to inspect the specific @ref engine::WaitAnyError reason.

* Added @ref engine::SingleConsumerEvent::WaitUntil(Deadline), same as `WaitForEventUntil`, but returning the precise @ref engine::FutureStatus reason (`kReady`/`kTimeout`/`kCancelled`) instead of just a `bool`
commit_hash:143825523261cba67af573b743f92f7e8f62ddd5

Author: Anton3

core/include/userver/engine/single_consumer_event.hpp

@@ -7,6 +7,7 @@
 
 #include <userver/engine/awaitable.hpp>
 #include <userver/engine/deadline.hpp>
+#include <userver/engine/future_status.hpp>
 #include <userver/utils/fast_pimpl.hpp>
 
 USERVER_NAMESPACE_BEGIN
@@ -57,6 +58,16 @@ class SingleConsumerEvent final {
     /// @overload bool WaitForEvent()
     [[nodiscard]] bool WaitForEventUntil(Deadline);
 
+    /// @brief Waits until the event is in a signaled state, same as @ref WaitForEventUntil, but gives the precise
+    /// reason of a failure instead of just `false`.
+    ///
+    /// If the event is auto-resetting, clears the signal flag upon waking up. If already in a signaled state,
+    /// does the same without sleeping.
+    ///
+    /// @return `FutureStatus::kReady` if the event signaled, `FutureStatus::kCancelled` if the current task was
+    /// cancelled, `FutureStatus::kTimeout` if the deadline was reached.
+    [[nodiscard]] FutureStatus WaitUntil(Deadline deadline);
+
     /// @brief Works like `std::condition_variable::wait_until`. Waits until
     /// @a stop_waiting becomes `true`, and we are notified via `Send`.
     ///

core/include/userver/engine/wait_any.hpp

@@ -13,6 +13,7 @@
 
 #include <userver/engine/awaitable.hpp>
 #include <userver/engine/deadline.hpp>
+#include <userver/utils/expected.hpp>
 #include <userver/utils/fast_pimpl.hpp>
 #include <userver/utils/meta.hpp>
 #include <userver/utils/span.hpp>
@@ -113,6 +114,15 @@ std::optional<std::size_t> WaitAnyUntil(Deadline deadline, Tasks&... tasks) {
     }
 }
 
+/// @ingroup userver_concurrency
+///
+/// @brief The reason why @ref WaitAnyContext::Wait and friends did not return the index of a completed awaitable.
+enum class WaitAnyError : std::uint8_t {
+    kEmpty,      ///< there were no awaitables to wait for
+    kCancelled,  ///< the wait operation was interrupted by task cancellation
+    kTimeout,    ///< the wait operation timed out (see also @ref FutureStatus)
+};
+
 /// @ingroup userver_concurrency
 ///
 /// @brief Stores a set of awaitables and allows waiting for completion of any of the stored awaitables.
@@ -154,30 +164,32 @@ class WaitAnyContext final {
     /// @brief Waits either for the completion of any of the awaitables stored in the context
     /// or for the cancellation of the caller.
     ///
-    /// @returns the index of the completed awaitable, or `std::nullopt` if there are no
-    /// completed awaitables (possible if current task was cancelled).
-    std::optional<std::uint64_t> Wait();
+    /// @returns the index of the completed awaitable, or a @ref WaitAnyError if there are no
+    /// completed awaitables (possible if current task was cancelled or the context is empty).
+    utils::expected<std::uint64_t, WaitAnyError> Wait();
 
     /// @brief Waits for the completion of any of the awaitables stored in the context
     /// or cancellation of the caller or deadline expiration.
     ///
-    /// @returns the index of the completed awaitable, or `std::nullopt` if there are no
-    /// completed awaitables (possible if current task was cancelled or the deadline was reached).
-    std::optional<std::uint64_t> WaitUntil(Deadline deadline);
+    /// @returns the index of the completed awaitable, or a @ref WaitAnyError if there are no
+    /// completed awaitables (possible if current task was cancelled, the deadline was reached,
+    /// or the context is empty).
+    utils::expected<std::uint64_t, WaitAnyError> WaitUntil(Deadline deadline);
 
     /// @brief Waits for the completion of any of the awaitables stored in the context
     /// or cancellation of the caller or expiration of the given duration.
     ///
-    /// @returns the index of the completed awaitable, or `std::nullopt` if there are no
-    /// completed awaitables (possible if current task was cancelled or the given duration has passed).
+    /// @returns the index of the completed awaitable, or a @ref WaitAnyError if there are no
+    /// completed awaitables (possible if current task was cancelled, the given duration has passed,
+    /// or the context is empty).
     template <typename Rep, typename Period>
-    std::optional<std::uint64_t> WaitFor(const std::chrono::duration<Rep, Period>& duration) {
+    utils::expected<std::uint64_t, WaitAnyError> WaitFor(const std::chrono::duration<Rep, Period>& duration) {
         return WaitUntil(Deadline::FromDuration(duration));
     }
 
-    /// @overload std::optional<std::size_t> Wait()
+    /// @overload utils::expected<std::uint64_t, WaitAnyError> Wait()
     template <typename Clock, typename Duration>
-    std::optional<std::uint64_t> WaitUntil(const std::chrono::time_point<Clock, Duration>& until) {
+    utils::expected<std::uint64_t, WaitAnyError> WaitUntil(const std::chrono::time_point<Clock, Duration>& until) {
         return WaitUntil(Deadline::FromTimePoint(until));
     }
 

core/src/engine/single_consumer_event.cpp

@@ -1,5 +1,6 @@
 #include <userver/engine/single_consumer_event.hpp>
 
+#include <engine/impl/future_utils.hpp>
 #include <engine/impl/wait_list_light.hpp>
 #include <engine/task/task_context.hpp>
 #include <userver/engine/awaitable.hpp>
@@ -42,26 +43,29 @@ bool SingleConsumerEvent::IsAutoReset() const noexcept { return impl_->is_auto_r
 
 bool SingleConsumerEvent::WaitForEvent() { return WaitForEventUntil(Deadline{}); }
 
-bool SingleConsumerEvent::WaitForEventUntil(Deadline deadline) {
+bool SingleConsumerEvent::WaitForEventUntil(Deadline deadline) { return WaitUntil(deadline) == FutureStatus::kReady; }
+
+FutureStatus SingleConsumerEvent::WaitUntil(Deadline deadline) {
     // optimistic path
     if (IsReady()) {
         if (IsAutoReset()) {
             Reset();
         }
-        return true;
+        return FutureStatus::kReady;
     }
 
     auto& awaiter = current_task::GetCurrentTaskContext();
     const auto wakeup_source = awaiter.Sleep(*impl_, deadline);
-    if (!impl::HasWaitSucceeded(wakeup_source)) {
-        return false;
+    const auto status = impl::ToFutureStatus(wakeup_source);
+    if (status != FutureStatus::kReady) {
+        return status;
     }
 
     UASSERT(IsReady());
     if (IsAutoReset()) {
         Reset();
     }
-    return true;
+    return FutureStatus::kReady;
 }
 
 void SingleConsumerEvent::Reset() noexcept {

core/src/engine/single_consumer_event_test.cpp

@@ -92,6 +92,24 @@ UTEST(SingleConsumerEvent, WaitFailed) {
     EXPECT_FALSE(event.WaitForEventUntil(engine::Deadline::Passed()));
 }
 
+UTEST(SingleConsumerEvent, WaitUntilAllStatuses) {
+    engine::SingleConsumerEvent event;
+
+    // kReady: the event is already signaled.
+    event.Send();
+    EXPECT_EQ(event.WaitUntil(engine::Deadline{}), engine::FutureStatus::kReady);
+
+    // kTimeout: the event is not signaled and the deadline is reached.
+    EXPECT_EQ(event.WaitUntil(engine::Deadline::Passed()), engine::FutureStatus::kTimeout);
+
+    // kCancelled: the waiting task is cancelled before the event is signaled.
+    auto waiter = engine::CriticalAsyncNoTracing([&event] {
+        return event.WaitUntil(engine::Deadline::FromDuration(utest::kMaxTestWaitTime));
+    });
+    waiter.SyncCancel();
+    UEXPECT_NO_THROW(EXPECT_EQ(waiter.Get(), engine::FutureStatus::kCancelled));
+}
+
 UTEST(SingleConsumerEvent, SendAndWait2) {
     engine::SingleConsumerEvent event;
     auto task = engine::AsyncNoTracing([&event]() {

core/src/engine/wait_any.cpp

@@ -76,7 +76,7 @@ class WaitAnyContext::Impl final : public utils::impl::IntrusiveRefCounterOne<Im
 
     void Append(std::uint64_t id, engine::AwaitableToken awaitable);
 
-    std::optional<std::uint64_t> WaitUntil(Deadline deadline);
+    utils::expected<std::uint64_t, WaitAnyError> WaitUntil(Deadline deadline);
 
     std::size_t GetSize() const noexcept { return subscribed_count_ + pending_subscription_.size(); }
 
@@ -170,27 +170,32 @@ void WaitAnyContext::Impl::Append(std::uint64_t id, engine::AwaitableToken await
     pending_subscription_.push_front(item);
 }
 
-std::optional<std::uint64_t> WaitAnyContext::Impl::WaitUntil(Deadline deadline) {
+utils::expected<std::uint64_t, WaitAnyError> WaitAnyContext::Impl::WaitUntil(Deadline deadline) {
     for (;;) {
         queue_non_empty_.Reset();
         if (subscribed_count_ != 0) {
             auto result = TryProcessQueue();
             if (result.has_value()) {
-                return result;
+                return *result;
             }
         }
 
         auto result = TrySubscribe();
         if (result.has_value()) {
-            return result;
+            return *result;
         }
 
         if (subscribed_count_ == 0) {
-            return std::nullopt;
+            return utils::unexpected(WaitAnyError::kEmpty);
         }
 
-        if (!queue_non_empty_.WaitForEventUntil(deadline)) {
-            return std::nullopt;
+        switch (queue_non_empty_.WaitUntil(deadline)) {
+            case FutureStatus::kReady:
+                break;
+            case FutureStatus::kTimeout:
+                return utils::unexpected(WaitAnyError::kTimeout);
+            case FutureStatus::kCancelled:
+                return utils::unexpected(WaitAnyError::kCancelled);
         }
     }
 }
@@ -302,9 +307,9 @@ WaitAnyContext& WaitAnyContext::operator=(WaitAnyContext&& other) noexcept {
     return *this;
 }
 
-std::optional<std::uint64_t> WaitAnyContext::Wait() { return WaitUntil(Deadline{}); }
+utils::expected<std::uint64_t, WaitAnyError> WaitAnyContext::Wait() { return WaitUntil(Deadline{}); }
 
-std::optional<std::uint64_t> WaitAnyContext::WaitUntil(Deadline deadline) {
+utils::expected<std::uint64_t, WaitAnyError> WaitAnyContext::WaitUntil(Deadline deadline) {
     UASSERT(impl_ != nullptr);
     return impl_->WaitUntil(deadline);
 }