#include <userver/engine/wait_any.hpp>

Detailed Description

Stores a set of awaitables and allows waiting for completion of any of the stored awaitables.

Works with different types of awaitables:

    std::vector<TestAwaitable> awaitables(3);
 
    auto wait_any = engine::MakeWaitAny(awaitables[0], awaitables[1], awaitables[2]);
    ASSERT_EQ(wait_any.GetNextId(), awaitables.size());
 
    EXPECT_EQ(wait_any.WaitUntil(engine::Deadline::Passed()), utils::unexpected(engine::WaitAnyError::kTimeout));
 
    for (std::size_t i = 0; i < awaitables.size(); ++i) {
        ASSERT_EQ(wait_any.GetSize(), awaitables.size() - i);
        awaitables[(i + 1) % awaitables.size()].SetReady();
        auto index = wait_any.Wait();
        ASSERT_TRUE(index.has_value());
        EXPECT_EQ(*index, (i + 1) % awaitables.size());
    }
    ASSERT_EQ(wait_any.GetSize(), 0);
    EXPECT_EQ(wait_any.Wait(), utils::unexpected(engine::WaitAnyError::kEmpty));

No methods (except .dtor) should be called on a moved-out instance.

Definition at line 134 of file wait_any.hpp.

Public Member Functions
	WaitAnyContext (WaitAnyContext &&) noexcept
WaitAnyContext &	operator= (WaitAnyContext &&other) noexcept
	WaitAnyContext (const WaitAnyContext &)=delete
WaitAnyContext &	operator= (const WaitAnyContext &)=delete
void	Append (engine::Awaitable auto &awaitable)
	Appends a single awaitable to the context.
void	Append (std::uint64_t id, engine::Awaitable auto &awaitable)
	Appends the given awaitable to the context with an explicit id.
utils::expected< std::uint64_t, WaitAnyError >	Wait ()
	Waits either for the completion of any of the awaitables stored in the context or for the cancellation of the caller.
utils::expected< std::uint64_t, WaitAnyError >	WaitUntil (Deadline deadline)
	Waits for the completion of any of the awaitables stored in the context or cancellation of the caller or deadline expiration.
template<typename Rep, typename Period>
utils::expected< std::uint64_t, WaitAnyError >	WaitFor (const std::chrono::duration< Rep, Period > &duration)
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
template<typename Clock, typename Duration>
utils::expected< std::uint64_t, WaitAnyError >	WaitUntil (const std::chrono::time_point< Clock, Duration > &until)
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
std::size_t	GetSize () const noexcept
	Returns the number of awaitables stored in the context.
std::uint64_t	GetNextId () const noexcept
	Returns the next id that will be assigned by the next Append call.

Member Function Documentation

◆ Append() [1/2]

void engine::WaitAnyContext::Append ( engine::Awaitable auto & awaitable )

Appends a single awaitable to the context.

The appended awaitable will be assigned the next id from the auto-incrementing counter; see also GetNextId.

Definition at line 216 of file wait_any.hpp.

◆ Append() [2/2]

void engine::WaitAnyContext::Append	(	std::uint64_t	id,
		engine::Awaitable auto &	awaitable )

Appends the given awaitable to the context with an explicit id.

The id is an arbitrary number that will be returned by Wait. It does not have to be sequential or starting from 0. Duplicate ids are allowed.

GetNextId will be unaffected by this call. When mixing the id-less Append and this overload, the id-less Append maintains a sequence only within its own calls.

Works well together with utils::SlotMap to process and erase tasks in completion order:

    utils::SlotMap<engine::TaskWithResult<int>> tasks;
 
    // Spawn several tasks and register each one in the WaitAnyContext using its
    // SlotMap index as the explicit WaitAnyContext index.
    engine::WaitAnyContext wait_any;
    for (int value : {1, 2, 3, 4}) {
        auto [task, index] = tasks.emplace(engine::AsyncNoTracing([value] { return value; }));
        wait_any.Append(index, task);
    }
 
    // Collect results as tasks finish, in completion order.
    int sum = 0;
    while (!tasks.empty()) {
        const auto index = wait_any.Wait();
        ASSERT_TRUE(index.has_value());
 
        sum += tasks[*index].Get();
        tasks.erase(*index);
    }
 
    EXPECT_EQ(sum, 1 + 2 + 3 + 4);

Parameters

id	the id that will be returned by Wait.
awaitable	the awaitable to append.

Definition at line 218 of file wait_any.hpp.

◆ GetNextId()

std::uint64_t engine::WaitAnyContext::GetNextId ( ) const

noexcept

Returns the next id that will be assigned by the next Append call.

It could be used to calculate ids of awaitables appended via Append call.

◆ GetSize()

std::size_t engine::WaitAnyContext::GetSize ( ) const

noexcept

Returns the number of awaitables stored in the context.

These are awaitables which have been Appended, but not yet retrieved by Wait or WaitUntil. The awaitables that have already been reported using Wait* are dropped out.

◆ Wait()

utils::expected< std::uint64_t, WaitAnyError > engine::WaitAnyContext::Wait ( )

Waits either for the completion of any of the awaitables stored in the context or for the cancellation of the caller.

The completed awaitable is dropped out of the context.

Returns: the index of the completed awaitable, or a WaitAnyError if there are no completed awaitables (possible if current task was cancelled or the context is empty).

◆ WaitFor()

template<typename Rep, typename Period>

utils::expected< std::uint64_t, WaitAnyError > engine::WaitAnyContext::WaitFor ( const std::chrono::duration< Rep, Period > & duration )

inline

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Definition at line 185 of file wait_any.hpp.

◆ WaitUntil() [1/2]

template<typename Clock, typename Duration>

utils::expected< std::uint64_t, WaitAnyError > engine::WaitAnyContext::WaitUntil ( const std::chrono::time_point< Clock, Duration > & until )

inline

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Definition at line 191 of file wait_any.hpp.

◆ WaitUntil() [2/2]

utils::expected< std::uint64_t, WaitAnyError > engine::WaitAnyContext::WaitUntil ( Deadline deadline )

Waits for the completion of any of the awaitables stored in the context or cancellation of the caller or deadline expiration.

The completed awaitable is dropped from the context.

Returns: the index of the completed awaitable, or a WaitAnyError if there are no completed awaitables (possible if current task was cancelled, the deadline was reached, or the context is empty).

The documentation for this class was generated from the following file:

userver/engine/wait_any.hpp