Github   Telegram
Loading...
Searching...
No Matches
Public Types | Public Member Functions | Static Public Member Functions | Friends | List of all members
engine::Task Class Reference

Asynchronous task. More...

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

+ Inheritance diagram for engine::Task:

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

 Task ()
 Default constructor. More...
 
virtual ~Task ()
 Destructor. More...
 
 Task (Task &&) noexcept
 
Taskoperator= (Task &&) noexcept
 
bool IsValid () const
 Checks whether this Task object owns an actual task (not State::kInvalid) More...
 
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(). More...
 
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. More...
 
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. More...
 
void WaitUntil (Deadline) const
 Suspends execution until the task finishes or until the specified deadline is reached or until caller is cancelled. More...
 
void Detach () &&
 Detaches task, allowing it to continue execution out of scope; memory safety is much better with concurrent::BackgroundTaskStorage. More...
 
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 const std::string & GetStateName (State state)
 

Friends

class TaskCancellationToken
 

Detailed Description

Asynchronous task.

Definition at line 36 of file task.hpp.

Member Enumeration Documentation

◆ Importance

enum class engine::Task::Importance
strong

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 39 of file task.hpp.

◆ State

enum class engine::Task::State
strong

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 51 of file task.hpp.

◆ WaitMode

enum class engine::Task::WaitMode
strong

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 62 of file task.hpp.

Constructor & Destructor Documentation

◆ Task()

engine::Task::Task ( )

Default constructor.

Creates an invalid task.

◆ ~Task()

virtual engine::Task::~Task ( )
virtual

Destructor.

When the task is still valid and is not finished, cancels it and waits until it finishes

Member Function Documentation

◆ BlockingWait()

void engine::Task::BlockingWait ( ) const

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

◆ Detach()

void engine::Task::Detach ( ) &&

Detaches task, allowing it to continue execution out of scope; memory safety is much better with concurrent::BackgroundTaskStorage.

Note
After detach, Task becomes invalid
Warning
Variables, which are captured by reference for this task in Async*, should outlive the task execution. This is hard to achieve in general, detached tasks may outlive all the components! Use concurrent::BackgroundTaskStorage as a safe and efficient alternative to calling Detach().

◆ IsValid()

bool engine::Task::IsValid ( ) const

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

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

  1. Task(), the default constructor
  2. Detach()
  3. Get() (see engine::TaskWithResult)

◆ Wait()

void engine::Task::Wait ( ) 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().

Exceptions
WaitInterruptedExceptionwhen current_task::IsCancelRequested() and no TaskCancellationBlockers are present.

◆ WaitFor()

template<typename Rep , typename Period >
void engine::Task::WaitFor ( const std::chrono::duration< Rep, Period > &  duration) const
noexcept

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

Exceptions
WaitInterruptedExceptionwhen current_task::IsCancelRequested() and no TaskCancellationBlockers are present.

Definition at line 209 of file task.hpp.

◆ WaitUntil() [1/2]

template<typename Clock , typename Duration >
void engine::Task::WaitUntil ( const std::chrono::time_point< Clock, Duration > &  until) const
noexcept

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

Exceptions
WaitInterruptedExceptionwhen current_task::IsCancelRequested() and no TaskCancellationBlockers are present.

Definition at line 215 of file task.hpp.

◆ WaitUntil() [2/2]

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

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

Exceptions
WaitInterruptedExceptionwhen current_task::IsCancelRequested() and no TaskCancellationBlockers are present.

Friends And Related Function Documentation

◆ TaskCancellationToken

friend class TaskCancellationToken
friend

Definition at line 177 of file task.hpp.


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