#include <userver/engine/task/shared_task_with_result.hpp>

Detailed Description

template<typename T>
class engine::SharedTaskWithResult< T >

Asynchronous task with result that has a shared ownership of payload.

Example usage:

    // Creating task that will be awaited in parallel
    auto shared_task = utils::SharedAsync("shared_task", []() {
        engine::InterruptibleSleepFor(std::chrono::milliseconds(100));
 
        return 1;
    });
 
    std::vector<engine::TaskWithResult<void>> tasks;
    std::atomic_int sum{0};
    for (size_t i = 0; i < 4; ++i) {
        // Getting shared_task's result in parallel
        tasks.push_back(utils::Async("waiter_task", [shared_task /* copy is allowed */, &sum]() {
            sum += shared_task.Get();
        }));
    }
 
    for (auto& task : tasks) task.Wait();

See also: Synchronization Primitives

Definition at line 35 of file shared_task_with_result.hpp.

Inheritance diagram for engine::SharedTaskWithResult< T >:

Public Types
enum class	Importance { kNormal , kCritical }
	Task importance. More...

enum class	State { kInvalid , kNew , kQueued , kRunning , kSuspended , kCancelled , kCompleted }
	Task state. More...

enum class	WaitMode { kSingleWaiter , kMultipleWaiters }
	Task wait mode. More...

Public Member Functions
	SharedTaskWithResult ()=default
	Default constructor.

	~SharedTaskWithResult ()=default
	If the task is still valid and is not finished and this is the last shared owner of the payload, cancels the task and waits until it finishes.

	SharedTaskWithResult (const SharedTaskWithResult &other)=default
	Assigns the other task into this.

SharedTaskWithResult &	operator= (const SharedTaskWithResult &other)=default
	If this task is still valid and is not finished and other task is not the same task as this and this is the last shared owner of the payload, cancels the task and waits until it finishes before assigning the other. Otherwise just assigns the other task into this.

	SharedTaskWithResult (SharedTaskWithResult &&other) noexcept=default
	Moves the other task into this, leaving the other in an invalid state.

SharedTaskWithResult &	operator= (SharedTaskWithResult &&other) noexcept=default
	If this task is still valid and is not finished and other task is not the same task as this and this is the last shared owner of the payload, cancels the task and waits until it finishes before move assigning the other. Otherwise just move assigns the other task into this, leaving the other in an invalid state.

decltype(auto)	Get () const &noexcept(false)
	Returns (or rethrows) the result of task invocation. Task remains valid after return from this method, thread(coro)-safe.

std::add_lvalue_reference< const T >	Get () &&

bool	IsValid () const
	Checks whether this object owns an actual task (not `State::kInvalid`)

State	GetState () const
	Gets the task State.

bool	IsFinished () const
	Returns whether the task finished execution.

void	Wait () const noexcept(false)
	Suspends execution until the task finishes or caller is cancelled. Can be called from coroutine context only. For non-coroutine context use BlockingWait().

template<typename Rep , typename Period >
void	WaitFor (const std::chrono::duration< Rep, Period > &) const noexcept(false)
	Suspends execution until the task finishes or after the specified timeout or until caller is cancelled.

template<typename Clock , typename Duration >
void	WaitUntil (const std::chrono::time_point< Clock, Duration > &) const noexcept(false)
	Suspends execution until the task finishes or until the specified time point is reached or until caller is cancelled.

void	WaitUntil (Deadline) const
	Suspends execution until the task finishes or until the specified deadline is reached or until caller is cancelled.

bool	WaitNothrow () const noexcept
	Suspends execution until the task finishes or caller is cancelled. Can be called from coroutine context only. For non-coroutine context use BlockingWait().

FutureStatus	WaitNothrowUntil (Deadline) const noexcept
	Suspends execution until the task finishes or until the specified deadline is reached or until caller is cancelled.

void	RequestCancel ()
	Queues task cancellation request.

void	SyncCancel () noexcept
	Cancels the task and suspends execution until it is finished. Can be called from coroutine context only. For non-coroutine context use RequestCancel() + BlockingWait().

TaskCancellationReason	CancellationReason () const
	Gets task cancellation reason.

void	BlockingWait () const

Static Public Member Functions
static std::string_view	GetStateName (State state)

Member Enumeration Documentation

◆ Importance

enum class engine::TaskBase::Importance

stronginherited

Task importance.

Enumerator
kNormal	Normal task.
kCritical	Critical task. The task will be started regardless of cancellations, e.g. due to user request, deadline or TaskProcessor overload. After the task starts, it may be cancelled. In particular, if it received any cancellation requests before starting, then it will start as cancelled.

Definition at line 36 of file task_base.hpp.

◆ State

enum class engine::TaskBase::State

stronginherited

Task state.

Enumerator
kInvalid	Unusable.
kNew	just created, not registered with task processor
kQueued	awaits execution
kRunning	executing user code
kSuspended	suspended, e.g. waiting for blocking call to complete
kCancelled	exited user code because of external request
kCompleted	exited user code with return or throw

Definition at line 48 of file task_base.hpp.

◆ WaitMode

enum class engine::TaskBase::WaitMode

stronginherited

Task wait mode.

Enumerator
kSingleWaiter	Can be awaited by at most one task at a time.
kMultipleWaiters	Can be awaited by multiple tasks simultaneously.

Definition at line 59 of file task_base.hpp.

Constructor & Destructor Documentation

◆ SharedTaskWithResult()

template<typename T >

engine::SharedTaskWithResult< T >::SharedTaskWithResult ( )

default

Default constructor.

Creates an invalid task.

Member Function Documentation

◆ BlockingWait()

void engine::TaskBase::BlockingWait ( ) const

inherited

Waits for the task in non-coroutine context (e.g. non-TaskProcessor's std::thread).

◆ Get() [1/2]

template<typename T >

std::add_lvalue_reference< const T > engine::SharedTaskWithResult< T >::Get ( ) &&

inline

Definition at line 86 of file shared_task_with_result.hpp.

◆ Get() [2/2]

template<typename T >

decltype(auto) engine::SharedTaskWithResult< T >::Get ( ) const &

inline

Returns (or rethrows) the result of task invocation. Task remains valid after return from this method, thread(coro)-safe.

Returns: const T& or void

Exceptions

WaitInterruptedException	when `current_task::IsCancelRequested()` and no TaskCancellationBlockers are present.
TaskCancelledException	if no result is available because the task was cancelled

Definition at line 75 of file shared_task_with_result.hpp.

◆ IsValid()

bool engine::TaskBase::IsValid ( ) const

inherited

Checks whether this object owns an actual task (not State::kInvalid)

An invalid task cannot be used. The task becomes invalid after each of the following calls:

the default constructor
Detach()
Get() (see engine::TaskWithResult)

◆ Wait()

void engine::TaskBase::Wait ( ) const

inherited

Suspends execution until the task finishes or caller is cancelled. Can be called from coroutine context only. For non-coroutine context use BlockingWait().

Exceptions

WaitInterruptedException when current_task::IsCancelRequested() and no TaskCancellationBlockers are present.

◆ WaitFor()

template<typename Rep , typename Period >

void engine::TaskBase::WaitFor ( const std::chrono::duration< Rep, Period > & duration ) const

inherited

Suspends execution until the task finishes or after the specified timeout or until caller is cancelled.

Exceptions

WaitInterruptedException when current_task::IsCancelRequested() and no TaskCancellationBlockers are present.

Definition at line 180 of file task_base.hpp.

◆ WaitNothrow()

bool engine::TaskBase::WaitNothrow ( ) const

noexceptinherited

Suspends execution until the task finishes or caller is cancelled. Can be called from coroutine context only. For non-coroutine context use BlockingWait().

Returns: false when current_task::IsCancelRequested() and no TaskCancellationBlockers are present.

◆ WaitNothrowUntil()

FutureStatus engine::TaskBase::WaitNothrowUntil ( Deadline ) const

noexceptinherited

Suspends execution until the task finishes or until the specified deadline is reached or until caller is cancelled.

Returns: FutureStatus::kCancelled when current_task::IsCancelRequested() and no TaskCancellationBlockers are present.

◆ WaitUntil() [1/2]

template<typename Clock , typename Duration >

void engine::TaskBase::WaitUntil ( const std::chrono::time_point< Clock, Duration > & until ) const

inherited

Suspends execution until the task finishes or until the specified time point is reached or until caller is cancelled.

Exceptions

WaitInterruptedException when current_task::IsCancelRequested() and no TaskCancellationBlockers are present.

Definition at line 185 of file task_base.hpp.

◆ WaitUntil() [2/2]

void engine::TaskBase::WaitUntil ( Deadline ) const

inherited

Suspends execution until the task finishes or until the specified deadline is reached or until caller is cancelled.

Exceptions

WaitInterruptedException when current_task::IsCancelRequested() and no TaskCancellationBlockers are present.

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

userver/engine/task/shared_task_with_result.hpp

Detailed Description

Example usage:

Public Types

Public Member Functions

Static Public Member Functions

Member Enumeration Documentation

◆ Importance

◆ State

◆ WaitMode

Constructor & Destructor Documentation

◆ SharedTaskWithResult()

Member Function Documentation

◆ BlockingWait()

◆ Get() [1/2]

◆ Get() [2/2]

◆ IsValid()

◆ Wait()

◆ WaitFor()

◆ WaitNothrow()

◆ WaitNothrowUntil()

◆ WaitUntil() [1/2]

◆ WaitUntil() [2/2]