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 , kOOM , kAbandoned , kShutdown }
	Task cancellation reason. More...

enum class	FutureStatus { kReady , kTimeout , kCancelled }
	std::future state extended with "cancelled" state More...

enum class	CvStatus { kNoTimeout , kTimeout , kCancelled }
	std::condition_variable state extended with "cancelled" state More...

enum class	DeadlockDetector { kOff , kOn , kDetectOnly }

enum class	TaskQueueType { kGlobalTaskQueue , kWorkStealingTaskQueue , kTSanTaskQueue }
	Scheduler types. More...

Functions
std::size_t	GetQueueSize (const TaskProcessor &task_processor) noexcept
	Get approximate count of ready-to-run tasks on the `task_processor`

std::size_t	GetWorkerCount (const TaskProcessor &task_processor) noexcept
	Get the number of worker threads in `task_processor`.

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

void	DetachUnscopedUnsafe (Task &&task)
	Detaches task, allowing it to continue execution out of scope; memory safety is much better with concurrent::BackgroundTaskStorage.

std::string_view	ToString (TaskCancellationReason reason) noexcept
	Returns a string representation of a cancellation reason.

template<typename Function , typename... Args>
auto	AsyncNoSpan (TaskProcessor &task_processor, Function &&f, Args &&... args)
	Runs an asynchronous function call using the specified task processor.

template<typename Function , typename... Args>
auto	SharedAsyncNoSpan (TaskProcessor &task_processor, Function &&f, Args &&... args)
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

template<typename Function , typename... Args>
auto	AsyncNoSpan (TaskProcessor &task_processor, Deadline deadline, Function &&f, Args &&... args)
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

template<typename Function , typename... Args>
auto	SharedAsyncNoSpan (TaskProcessor &task_processor, Deadline deadline, Function &&f, Args &&... args)
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

template<typename Function , typename... Args>
auto	AsyncNoSpan (Function &&f, Args &&... args)
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

template<typename Function , typename... Args>
auto	SharedAsyncNoSpan (Function &&f, Args &&... args)
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

template<typename Function , typename... Args>
auto	AsyncNoSpan (Deadline deadline, Function &&f, Args &&... args)
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

template<typename Function , typename... Args>
auto	SharedAsyncNoSpan (Deadline deadline, Function &&f, Args &&... args)
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

template<typename Function , typename... Args>
auto	CriticalAsyncNoSpan (TaskProcessor &task_processor, Function &&f, Args &&... args)

template<typename Function , typename... Args>
auto	SharedCriticalAsyncNoSpan (TaskProcessor &task_processor, Function &&f, Args &&... args)

template<typename Function , typename... Args>
auto	CriticalAsyncNoSpan (Function &&f, Args &&... args)

template<typename Function , typename... Args>
auto	SharedCriticalAsyncNoSpan (Function &&f, Args &&... args)

template<typename Function , typename... Args>
auto	CriticalAsyncNoSpan (Deadline deadline, Function &&f, Args &&... args)

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)

DeadlockDetector	Parse (const yaml_config::YamlConfig &value, formats::parse::To< DeadlockDetector >)

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)

void	RunStandalone (std::size_t worker_threads, const TaskProcessorPoolsConfig &config, utils::function_ref< void()> payload)

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)

TaskQueueType	Parse (const yaml_config::YamlConfig &value, formats::parse::To< TaskQueueType >)

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.

◆ DeadlockDetector

enum class engine::DeadlockDetector

strong

Definition at line 10 of file deadlock_detector_config.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.
kOOM	Not enough memory.
kAbandoned	Task destructor is called before the payload finished.
kShutdown	Task processor shutdown.

Definition at line 20 of file cancel.hpp.

◆ TaskQueueType

enum class engine::TaskQueueType

strong

Scheduler types.

Enumerator
kWorkStealingTaskQueue	< Global `moodycamel` queue from which each thread gets tasks
kTSanTaskQueue	< Global+thread-specific queues with interqueues work stealing (experimental queue)

Definition at line 13 of file task_queue_type.hpp.

Function Documentation

◆ AsyncNoSpan() [1/4]

template<typename Function , typename... Args>

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

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 121 of file async.hpp.

◆ AsyncNoSpan() [2/4]

template<typename Function , typename... Args>

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

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 109 of file async.hpp.

◆ AsyncNoSpan() [3/4]

template<typename Function , typename... Args>

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

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 85 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 the specified task processor.

Warning: If any logs are written in the task function (outside any manual tracing::Span scopes), then those logs will have no span_id (yikes!). If you create a span there manually, it will be disconnected from the outside trace. Prefer utils::Async by default instead.; To hide a spammy span from traces, use tracing::Span::CurrentSpan plus tracing::Span::SetLogLevel instead. Logs will then be linked to the nearest span that is written out.; Some clients may call tracing::Span::CurrentSpan unconditionally, so don't be too surprised if they won't work without a span scope. Do write tests.

AsyncNoSpan is useful for:

implementing periodic tasks (like utils::PeriodicTask);
worker tasks that typically run until service shutdown, and it makes no sense to have a span for the task itself;
some low-level (e.g. driver or filesystem-IO) code where logs are definitely not written;
breaking traces e.g. this is (rarely) wanted for some background tasks.

See also: utils::Async for main documentation on Async function family.

Definition at line 61 of file async.hpp.

◆ CriticalAsyncNoSpan() [1/3]

template<typename Function , typename... Args>

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

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

See also: Task::Importance::Critical

Definition at line 192 of file async.hpp.

◆ CriticalAsyncNoSpan() [2/3]

template<typename Function , typename... Args>

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

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

See also: Task::Importance::Critical

Definition at line 170 of file async.hpp.

◆ CriticalAsyncNoSpan() [3/3]

template<typename Function , typename... Args>

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

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

See also: Task::Importance::Critical

Definition at line 144 of file async.hpp.

◆ DetachUnscopedUnsafe()

void engine::DetachUnscopedUnsafe ( Task && task )

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.

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

Examples: samples/ydb_service/components/federated_topic_reader.cpp, and samples/ydb_service/components/topic_reader.cpp.

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() [1/3]

void engine::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.

Parameters

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

◆ RunStandalone() [2/3]

void engine::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.

Parameters

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

◆ RunStandalone() [3/3]

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

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
	)

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 132 of file async.hpp.

◆ SharedAsyncNoSpan() [2/4]

template<typename Function , typename... Args>

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

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 115 of file async.hpp.

◆ SharedAsyncNoSpan() [3/4]

template<typename Function , typename... Args>

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

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 97 of file async.hpp.

◆ SharedAsyncNoSpan() [4/4]

template<typename Function , typename... Args>

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

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 73 of file async.hpp.

◆ SharedCriticalAsyncNoSpan() [1/2]

template<typename Function , typename... Args>

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

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

See also: Task::Importance::Critical

Definition at line 181 of file async.hpp.

◆ SharedCriticalAsyncNoSpan() [2/2]

template<typename Function , typename... Args>

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

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

See also: Task::Importance::Critical

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

Detailed Description

Namespaces

Classes

Enumerations

Functions

Enumeration Type Documentation

◆ CvStatus

◆ DeadlockDetector

◆ FutureStatus

◆ TaskCancellationReason

◆ TaskQueueType

Function Documentation

◆ AsyncNoSpan() [1/4]

◆ AsyncNoSpan() [2/4]

◆ AsyncNoSpan() [3/4]

◆ AsyncNoSpan() [4/4]

◆ CriticalAsyncNoSpan() [1/3]

◆ CriticalAsyncNoSpan() [2/3]

◆ CriticalAsyncNoSpan() [3/3]

◆ DetachUnscopedUnsafe()

◆ InterruptibleSleepFor()

◆ InterruptibleSleepUntil()

◆ RegisterThreadStartedHook()

◆ RunStandalone() [1/3]

◆ RunStandalone() [2/3]

◆ RunStandalone() [3/3]

◆ SharedAsyncNoSpan() [1/4]

◆ SharedAsyncNoSpan() [2/4]

◆ SharedAsyncNoSpan() [3/4]

◆ SharedAsyncNoSpan() [4/4]

◆ SharedCriticalAsyncNoSpan() [1/2]

◆ SharedCriticalAsyncNoSpan() [2/2]

◆ SleepFor()

◆ SleepUntil()

◆ WaitAllCheckedFor()

◆ WaitAllCheckedUntil() [1/2]

◆ WaitAllCheckedUntil() [2/2]

◆ WaitAnyFor()

◆ WaitAnyUntil() [1/2]

◆ WaitAnyUntil() [2/2]