#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()), std::nullopt);
 
    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(), std::nullopt);

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

Definition at line 124 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.

std::optional< std::uint64_t >	Wait ()
	Waits either for the completion of any of the awaitables stored in the context or for the cancellation of the caller.

std::optional< std::uint64_t >	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>
std::optional< std::uint64_t >	WaitFor (const std::chrono::duration< Rep, Period > &duration)
	Waits for the completion of any of the awaitables stored in the context or cancellation of the caller or expiration of the given duration.

template<typename Clock, typename Duration>
std::optional< std::uint64_t >	WaitUntil (const std::chrono::time_point< Clock, Duration > &until)

std::size_t	GetSize () const noexcept
	Returns the number of awaitables actually 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 205 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_opt = wait_any.Wait();
        ASSERT_TRUE(index_opt.has_value());
 
        const std::size_t index = *index_opt;
        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 207 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 actually stored in the context.

It consists of actively awaited and pending subscription awaitables. Already notified awaitables are dropped out.

◆ Wait()

std::optional< std::uint64_t > engine::WaitAnyContext::Wait ( )

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).

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

◆ WaitFor()

template<typename Rep, typename Period>

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

inline

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).

Definition at line 174 of file wait_any.hpp.

◆ WaitUntil() [1/2]

template<typename Clock, typename Duration>

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

inline

Definition at line 180 of file wait_any.hpp.

◆ WaitUntil() [2/2]

std::optional< std::uint64_t > 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.

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).

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

userver/engine/wait_any.hpp