engine Namespace Reference

Detailed Description

Asynchronous engine primitives.

Namespaces
namespace	current_task
	Namespace with functions to work with current task from within it.
namespace	io
	Low-level asynchronous I/O interfaces.

Classes
class	CancellableSemaphore
	Class that allows up to max_simultaneous_locks concurrent accesses to the critical section. It honours task cancellation, unlike Semaphore. More...
class	ConditionVariable
	std::condition_variable replacement for asynchronous tasks More...
class	Deadline
	Internal representation of a deadline time point. More...
class	Future
	std::future replacement for asynchronous tasks that works in pair with engine::Promise More...
class	Mutex
	std::mutex replacement for asynchronous tasks. More...
class	Promise
	std::promise replacement for asynchronous tasks that works in pair with engine::Future More...
class	Promise< void >
class	Semaphore
	Class that allows up to max_simultaneous_locks concurrent accesses to the critical section. It ignores task cancellation, unlike CancellableSemaphore. More...
class	SemaphoreLock
	A replacement for std::shared_lock that accepts Deadline arguments. More...
class	SemaphoreLockCancelledError
	Thrown by engine::CancellableSemaphore on current task cancellation. More...
class	SharedMutex
	std::shared_mutex replacement for asynchronous tasks. More...
class	SharedTask
	Asynchronous task that has a shared ownership of the payload. More...
class	SharedTaskWithResult
	Asynchronous task with result that has a shared ownership of payload. More...
class	SingleConsumerEvent
	A multiple-producers, single-consumer event. More...
class	SingleThreadedTaskProcessorsPool
class	SingleUseEvent
	A single-producer, single-consumer event. More...
class	SingleWaitingTaskMutex
	Lighter version of Mutex with not more than 1 waiting task. More...
class	Task
	Asynchronous task that has a unique ownership of the payload. More...
class	TaskBase
	Base class for all the asynchronous tasks (engine::Task, engine::SharedTask, engine::SharedTaskWithResult, engine::TaskWithResult, dist_lock::DistLockedTask, ...). More...
class	TaskCancellationBlocker
class	TaskCancellationToken
	Cancellation token to given task object. More...
class	TaskCancelledException
	Thrown if a TaskWithResult, for which we were waiting, got cancelled. More...
class	TaskInheritedVariable
	TaskInheritedVariable is a per-coroutine variable of arbitrary type. More...
class	TaskLocalVariable
	TaskLocalVariable is a per-coroutine variable of arbitrary type. More...
struct	TaskProcessorPoolsConfig
	A lightweight TaskProcessor config for engine::RunStandalone. More...
class	TaskProcessorsLoadMonitor
	Component to monitor CPU usage for every TaskProcessor present in the service, and dump per-thread stats into metrics. More...
class	TaskWithResult
class	UnreachableSemaphoreLockError
class	WaitInterruptedException

Enumerations
enum class	TaskCancellationReason {   kNone ,   kUserRequest ,   kDeadline ,   kOverload ,   kAbandoned ,   kShutdown }
	Task cancellation reason. More...
enum class	CvStatus {   kNoTimeout ,   kTimeout ,   kCancelled }
	std::condition_variable state extended with "cancelled" state More...
enum class	FutureStatus {   kReady ,   kTimeout ,   kCancelled }
	std::future state extended with "cancelled" state More...

Functions
void	RegisterThreadStartedHook (std::function< void()>)
	Register a function that runs on all threads on task processor creation. Used for pre-initializing thread_local variables with heavy constructors (constructor that does blocking system calls, file access, ...):
template<typename Function , typename... Args>
auto	AsyncNoSpan (TaskProcessor &task_processor, Function &&f, Args &&... args)
	Runs an asynchronous function call using specified task processor.
template<typename Function , typename... Args>
auto	SharedAsyncNoSpan (TaskProcessor &task_processor, Function &&f, Args &&... args)
	Runs an asynchronous function call using specified task processor.
template<typename Function , typename... Args>
auto	AsyncNoSpan (TaskProcessor &task_processor, Deadline deadline, Function &&f, Args &&... args)
template<typename Function , typename... Args>
auto	SharedAsyncNoSpan (TaskProcessor &task_processor, Deadline deadline, Function &&f, Args &&... args)
template<typename Function , typename... Args>
auto	AsyncNoSpan (Function &&f, Args &&... args)
	Runs an asynchronous function call using task processor of the caller.
template<typename Function , typename... Args>
auto	SharedAsyncNoSpan (Function &&f, Args &&... args)
	Runs an asynchronous function call using task processor of the caller.
template<typename Function , typename... Args>
auto	AsyncNoSpan (Deadline deadline, Function &&f, Args &&... args)
template<typename Function , typename... Args>
auto	SharedAsyncNoSpan (Deadline deadline, Function &&f, Args &&... args)
template<typename Function , typename... Args>
auto	CriticalAsyncNoSpan (TaskProcessor &task_processor, Function &&f, Args &&... args)
	Runs an asynchronous function call that will start regardless of cancellations using specified task processor.
template<typename Function , typename... Args>
auto	SharedCriticalAsyncNoSpan (TaskProcessor &task_processor, Function &&f, Args &&... args)
	Runs an asynchronous function call that will start regardless of cancellations using specified task processor.
template<typename Function , typename... Args>
auto	CriticalAsyncNoSpan (Function &&f, Args &&... args)
	Runs an asynchronous function call that will start regardless of cancellations using task processor of the caller.
template<typename Function , typename... Args>
auto	SharedCriticalAsyncNoSpan (Function &&f, Args &&... args)
	Runs an asynchronous function call that will start regardless of cancellations using task processor of the caller.
template<typename Function , typename... Args>
auto	CriticalAsyncNoSpan (Deadline deadline, Function &&f, Args &&... args)
	Runs an asynchronous function call that will start regardless of cancellations, using task processor of the caller, with deadline.
std::string_view	ToString (TaskCancellationReason reason) noexcept
	Returns a string representation of a cancellation reason.
template<typename... Tasks>
auto	GetAll (Tasks &... tasks)
	Waits for the successful completion of all of the specified tasks or the cancellation of the caller.
void	RunStandalone (utils::function_ref< void()> payload)
	Runs a payload in a temporary coroutine engine instance.
void	RunStandalone (std::size_t worker_threads, utils::function_ref< void()> payload)
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
void	RunStandalone (std::size_t worker_threads, const TaskProcessorPoolsConfig &config, utils::function_ref< void()> payload)
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
void	Yield ()
	Suspends execution for a brief period of time, possibly allowing other tasks to execute.
template<typename Rep , typename Period >
void	InterruptibleSleepFor (const std::chrono::duration< Rep, Period > &duration)
template<typename Clock , typename Duration >
void	InterruptibleSleepUntil (const std::chrono::time_point< Clock, Duration > &time_point)
template<typename Rep , typename Period >
void	SleepFor (const std::chrono::duration< Rep, Period > &duration)
template<typename Clock , typename Duration >
void	SleepUntil (const std::chrono::time_point< Clock, Duration > &time_point)
template<typename... Tasks>
void	WaitAllChecked (Tasks &... tasks)
	Waits for the successful completion of all of the specified tasks or for the cancellation of the caller.
template<typename... Tasks, typename Rep , typename Period >
FutureStatus	WaitAllCheckedFor (const std::chrono::duration< Rep, Period > &duration, Tasks &... tasks)
template<typename... Tasks, typename Clock , typename Duration >
FutureStatus	WaitAllCheckedUntil (const std::chrono::time_point< Clock, Duration > &until, Tasks &... tasks)
template<typename... Tasks>
FutureStatus	WaitAllCheckedUntil (Deadline deadline, Tasks &... tasks)
template<typename... Tasks>
std::optional< std::size_t >	WaitAny (Tasks &... tasks)
	Waits for the completion of any of the specified tasks or the cancellation of the caller.
template<typename... Tasks, typename Rep , typename Period >
std::optional< std::size_t >	WaitAnyFor (const std::chrono::duration< Rep, Period > &duration, Tasks &... tasks)
template<typename... Tasks, typename Clock , typename Duration >
std::optional< std::size_t >	WaitAnyUntil (const std::chrono::time_point< Clock, Duration > &until, Tasks &... tasks)
template<typename... Tasks>
std::optional< std::size_t >	WaitAnyUntil (Deadline, Tasks &... tasks)

Enumeration Type Documentation

CvStatus

enum class engine::CvStatus

strong

std::condition_variable state extended with "cancelled" state

Definition at line 11 of file condition_variable_status.hpp.

FutureStatus

enum class engine::FutureStatus

strong

std::future state extended with "cancelled" state

Enumerator
kReady	the future is ready
kTimeout	the wait operation timed out
kCancelled	the wait operation was interrupted by task cancellation

Definition at line 11 of file future_status.hpp.

TaskCancellationReason

enum class engine::TaskCancellationReason

strong

Task cancellation reason.

Enumerator
kNone	Not cancelled.
kUserRequest	User request.
kDeadline	Deadline.
kOverload	Task processor overload.
kAbandoned	Task destructor is called before the payload finished.
kShutdown	Task processor shutdown.

Definition at line 20 of file cancel.hpp.

Function Documentation

AsyncNoSpan() [1/4]

template<typename Function , typename... Args>

auto engine::AsyncNoSpan	(	Deadline	deadline,
		Function &&	f,
		Args &&...	args )

Runs an asynchronous function call with deadline using task processor of the caller

Definition at line 86 of file async.hpp.

AsyncNoSpan() [2/4]

template<typename Function , typename... Args>

auto engine::AsyncNoSpan	(	Function &&	f,
		Args &&...	args )

Runs an asynchronous function call using task processor of the caller.

Definition at line 73 of file async.hpp.

AsyncNoSpan() [3/4]

template<typename Function , typename... Args>

auto engine::AsyncNoSpan	(	TaskProcessor &	task_processor,
		Deadline	deadline,
		Function &&	f,
		Args &&...	args )

Runs an asynchronous function call with deadline using specified task processor

Definition at line 56 of file async.hpp.

AsyncNoSpan() [4/4]

template<typename Function , typename... Args>

auto engine::AsyncNoSpan	(	TaskProcessor &	task_processor,
		Function &&	f,
		Args &&...	args )

Runs an asynchronous function call using specified task processor.

Definition at line 39 of file async.hpp.

CriticalAsyncNoSpan() [1/3]

template<typename Function , typename... Args>

auto engine::CriticalAsyncNoSpan	(	Deadline	deadline,
		Function &&	f,
		Args &&...	args )

Runs an asynchronous function call that will start regardless of cancellations, using task processor of the caller, with deadline.

See also

Task::Importance::Critical

Definition at line 145 of file async.hpp.

CriticalAsyncNoSpan() [2/3]

template<typename Function , typename... Args>

auto engine::CriticalAsyncNoSpan	(	Function &&	f,
		Args &&...	args )

Runs an asynchronous function call that will start regardless of cancellations using task processor of the caller.

See also

Task::Importance::Critical

Definition at line 125 of file async.hpp.

CriticalAsyncNoSpan() [3/3]

template<typename Function , typename... Args>

auto engine::CriticalAsyncNoSpan	(	TaskProcessor &	task_processor,
		Function &&	f,
		Args &&...	args )

Runs an asynchronous function call that will start regardless of cancellations using specified task processor.

See also

Task::Importance::Critical

Definition at line 105 of file async.hpp.

InterruptibleSleepFor()

template<typename Rep , typename Period >

void engine::InterruptibleSleepFor

(

const std::chrono::duration< Rep, Period > &

duration

)

Suspends execution for at least the specified amount of time or until the current task is cancelled. If already cancelled, the call is equivalent to Yield.

Definition at line 28 of file sleep.hpp.

InterruptibleSleepUntil()

template<typename Clock , typename Duration >

void engine::InterruptibleSleepUntil

(

const std::chrono::time_point< Clock, Duration > &

time_point

)

Suspends execution until the specified time point is reached or until the current task is cancelled. If already cancelled, the call is equivalent to Yield.

Definition at line 36 of file sleep.hpp.

RegisterThreadStartedHook()

void engine::RegisterThreadStartedHook

(

std::function< void()>

)

Register a function that runs on all threads on task processor creation. Used for pre-initializing thread_local variables with heavy constructors (constructor that does blocking system calls, file access, ...):

Note

It is a low-level function. You might not want to use it.

RunStandalone()

void engine::RunStandalone

(

utils::function_ref< void()>

payload

)

Runs a payload in a temporary coroutine engine instance.

Creates a TaskProcessor with specified parameters, executes the payload in an Async and exits. Mainly designated for async code unit testing.

Warning

This function must not be used while another engine instance is running.

Parameters

payload	Code to be run in a Task
worker_threads	Engine thread pool size, 1 by default
config	A lightweight TaskProcessor config

Examples

core/src/engine/mutex_benchmark.cpp, and samples/hello_service/benchmarks/say_hello_bench.cpp.

SharedAsyncNoSpan() [1/4]

template<typename Function , typename... Args>

auto engine::SharedAsyncNoSpan	(	Deadline	deadline,
		Function &&	f,
		Args &&...	args )

Runs an asynchronous function call with deadline using task processor of the caller

Definition at line 95 of file async.hpp.

SharedAsyncNoSpan() [2/4]

template<typename Function , typename... Args>

auto engine::SharedAsyncNoSpan	(	Function &&	f,
		Args &&...	args )

Runs an asynchronous function call using task processor of the caller.

Definition at line 79 of file async.hpp.

SharedAsyncNoSpan() [3/4]

template<typename Function , typename... Args>

auto engine::SharedAsyncNoSpan	(	TaskProcessor &	task_processor,
		Deadline	deadline,
		Function &&	f,
		Args &&...	args )

Runs an asynchronous function call with deadline using specified task processor

Definition at line 65 of file async.hpp.

SharedAsyncNoSpan() [4/4]

template<typename Function , typename... Args>

auto engine::SharedAsyncNoSpan	(	TaskProcessor &	task_processor,
		Function &&	f,
		Args &&...	args )

Runs an asynchronous function call using specified task processor.

Definition at line 47 of file async.hpp.

SharedCriticalAsyncNoSpan() [1/2]

template<typename Function , typename... Args>

auto engine::SharedCriticalAsyncNoSpan	(	Function &&	f,
		Args &&...	args )

Runs an asynchronous function call that will start regardless of cancellations using task processor of the caller.

See also

Task::Importance::Critical

Definition at line 135 of file async.hpp.

SharedCriticalAsyncNoSpan() [2/2]

template<typename Function , typename... Args>

auto engine::SharedCriticalAsyncNoSpan	(	TaskProcessor &	task_processor,
		Function &&	f,
		Args &&...	args )

Runs an asynchronous function call that will start regardless of cancellations using specified task processor.

See also

Task::Importance::Critical

Definition at line 115 of file async.hpp.

SleepFor()

template<typename Rep , typename Period >

void engine::SleepFor

(

const std::chrono::duration< Rep, Period > &

duration

)

Suspends execution for at least a specified amount of time, ignores cancellation. Use engine::InterruptibleSleepFor to interrupt sleep by cancellation request.

Examples

postgresql/functional_tests/basic_chaos/postgres_service.cpp.

Definition at line 44 of file sleep.hpp.

SleepUntil()

template<typename Clock , typename Duration >

void engine::SleepUntil

(

const std::chrono::time_point< Clock, Duration > &

time_point

)

Suspends execution until the specified time point is reached, ignores cancellation. Use engine::InterruptibleSleepUntil to interrupt sleep by cancellation request.

Definition at line 52 of file sleep.hpp.

WaitAllCheckedFor()

template<typename... Tasks, typename Rep , typename Period >

FutureStatus engine::WaitAllCheckedFor	(	const std::chrono::duration< Rep, Period > &	duration,
		Tasks &...	tasks )

Definition at line 100 of file wait_all_checked.hpp.

WaitAllCheckedUntil() [1/2]

template<typename... Tasks, typename Clock , typename Duration >

FutureStatus engine::WaitAllCheckedUntil	(	const std::chrono::time_point< Clock, Duration > &	until,
		Tasks &...	tasks )

Definition at line 105 of file wait_all_checked.hpp.

WaitAllCheckedUntil() [2/2]

template<typename... Tasks>

FutureStatus engine::WaitAllCheckedUntil	(	Deadline	deadline,
		Tasks &...	tasks )

Definition at line 110 of file wait_all_checked.hpp.

WaitAnyFor()

template<typename... Tasks, typename Rep , typename Period >

std::optional< std::size_t > engine::WaitAnyFor	(	const std::chrono::duration< Rep, Period > &	duration,
		Tasks &...	tasks )

Definition at line 59 of file wait_any.hpp.

WaitAnyUntil() [1/2]

template<typename... Tasks, typename Clock , typename Duration >

std::optional< std::size_t > engine::WaitAnyUntil	(	const std::chrono::time_point< Clock, Duration > &	until,
		Tasks &...	tasks )

Definition at line 64 of file wait_any.hpp.

WaitAnyUntil() [2/2]

template<typename... Tasks>

std::optional< std::size_t > engine::WaitAnyUntil	(	Deadline	deadline,
		Tasks &...	tasks )

Definition at line 98 of file wait_any.hpp.