A system for managing asynchronous requests and tasks. More...

#include <CesiumAsync/AsyncSystem.h>

Public Types
template<typename T>
using	AllValueType
	The value type of the Future returned by `all`.

using	MainThreadScope
	An object that denotes a scope for the current thread acting as the "main thread". When this object is constructed, the current thread becomes the main thread. When it's destroyed, the current thread is no longer treated as the main thread.

Public Member Functions
	AsyncSystem (const std::shared_ptr< ITaskProcessor > &pTaskProcessor) noexcept
	Constructs a new instance.

template<typename T, typename Func>
Future< T >	createFuture (Func &&f) const
	Creates a new Future by immediately invoking a function and giving it the opportunity to resolve or reject a `Promise`.

template<typename T>
Promise< T >	createPromise () const
	Create a Promise that can be used at a later time to resolve or reject a Future.

template<typename Func>
CesiumImpl::ContinuationFutureType_t< Func, void >	runInWorkerThread (Func &&f) const
	Runs a function in a worker thread, returning a Future that resolves when the function completes.

template<typename Func>
CesiumImpl::ContinuationFutureType_t< Func, void >	runInMainThread (Func &&f) const
	Runs a function in the main thread, returning a Future that resolves when the function completes.

template<typename Func>
CesiumImpl::ContinuationFutureType_t< Func, void >	runInThreadPool (const ThreadPool &threadPool, Func &&f) const
	Runs a function in a thread pool, returning a Future that resolves when the function completes.

template<typename T>
Future< AllValueType< T > >	all (std::vector< Future< T > > &&futures) const
	Creates a Future that resolves when every Future in a vector resolves, and rejects when any Future in the vector rejects.

template<typename T>
Future< AllValueType< T > >	all (std::vector< SharedFuture< T > > &&futures) const
	Creates a Future that resolves when every Future in a vector resolves, and rejects when any Future in the vector rejects.

template<typename T>
Future< T >	createResolvedFuture (T &&value) const
	Creates a future that is already resolved.

Future< void >	createResolvedFuture () const
	Creates a future that is already resolved and resolves to no value.

void	dispatchMainThreadTasks ()
	Runs all tasks that are currently queued for the main thread.

bool	dispatchOneMainThreadTask ()
	Runs a single waiting task that is currently queued for the main thread. If there are no tasks waiting, it returns immediately without running any tasks.

MainThreadScope	enterMainThread () const
	Enters a scope in which the current thread is treated as the "main thread". It is essential that no other thread be acting as the main thread at the same time, or undefined behavior will result. The scope continues until the returned object is destroyed.

ThreadPool	createThreadPool (int32_t numberOfThreads) const
	Creates a new thread pool that can be used to run continuations.

bool	operator== (const AsyncSystem &rhs) const noexcept

bool	operator!= (const AsyncSystem &rhs) const noexcept

Friends
template<typename T>
class	Future

Detailed Description

A system for managing asynchronous requests and tasks.

Instances of this class may be safely and efficiently stored and passed around by value. However, it is essential that the last AsyncSystem instance be destroyed only after all continuations have run to completion. Otherwise, continuations may be scheduled using invalid scheduler instances, leading to a crash. Broadly, there are two ways to achieve this:

Wait until all Futures complete before destroying the "owner" of the AsyncSystem.
Make the AsyncSystem a global or static local in order to extend its lifetime all the way until program termination.

Definition at line 36 of file AsyncSystem.h.

Member Typedef Documentation

◆ AllValueType

template<typename T>

using CesiumAsync::AsyncSystem::AllValueType

Initial value:

std::conditional_t<std::is_void_v<T>, void, std::vector<T>>

The value type of the Future returned by all.

This will be either std::vector<T>, if the input Futures passed to the all function return values, or void if they do not.

Template Parameters

T	The value type of the input Futures passed to the function.

Definition at line 194 of file AsyncSystem.h.

◆ MainThreadScope

using CesiumAsync::AsyncSystem::MainThreadScope

Initial value:

CesiumImpl::ImmediateScheduler<

CesiumImpl::QueuedScheduler>::SchedulerScope

An object that denotes a scope for the current thread acting as the "main thread". When this object is constructed, the current thread becomes the main thread. When it's destroyed, the current thread is no longer treated as the main thread.

Definition at line 300 of file AsyncSystem.h.

Constructor & Destructor Documentation

◆ AsyncSystem()

CesiumAsync::AsyncSystem::AsyncSystem ( const std::shared_ptr< ITaskProcessor > & pTaskProcessor )

noexcept

Constructs a new instance.

Parameters

pTaskProcessor The interface used to run tasks in background threads.

Member Function Documentation

◆ all() [1/2]

template<typename T>

Future< AllValueType< T > > CesiumAsync::AsyncSystem::all ( std::vector< Future< T > > && futures ) const

inline

Creates a Future that resolves when every Future in a vector resolves, and rejects when any Future in the vector rejects.

If the input Futures resolve to non-void values, the returned Future resolves to a vector of the values, in the same order as the input Futures. If the input Futures resolve to void, the returned Future resolves to void as well.

If any of the Futures rejects, the returned Future rejects as well. The exception included in the rejection will be from the first Future in the vector that rejects.

To get detailed rejection information from each of the Futures, attach a catchInMainThread continuation prior to passing the list into all.

Template Parameters

T	The type that each Future resolves to.

Parameters

futures The list of futures.

Returns: A Future that resolves when all the given Futures resolve, and rejects when any Future in the vector rejects.

Definition at line 220 of file AsyncSystem.h.

◆ all() [2/2]

template<typename T>

Future< AllValueType< T > > CesiumAsync::AsyncSystem::all ( std::vector< SharedFuture< T > > && futures ) const

inline

Creates a Future that resolves when every Future in a vector resolves, and rejects when any Future in the vector rejects.

If the input SharedFutures resolve to non-void values, the returned Future resolves to a vector of the values, in the same order as the input SharedFutures. If the input SharedFutures resolve to void, the returned Future resolves to void as well.

If any of the SharedFutures rejects, the returned Future rejects as well. The exception included in the rejection will be from the first SharedFuture in the vector that rejects.

To get detailed rejection information from each of the SharedFutures, attach a catchInMainThread continuation prior to passing the list into all.

Template Parameters

T	The type that each SharedFuture resolves to.

Parameters

futures The list of shared futures.

Returns: A Future that resolves when all the given SharedFutures resolve, and rejects when any SharedFuture in the vector rejects.

Definition at line 248 of file AsyncSystem.h.

◆ createFuture()

template<typename T, typename Func>

Future< T > CesiumAsync::AsyncSystem::createFuture ( Func && f ) const

inline

Creates a new Future by immediately invoking a function and giving it the opportunity to resolve or reject a Promise.

The Promise passed to the callback f may be resolved or rejected asynchronously, even after the function has returned.

This method is very similar to AsyncSystem::createPromise, except that that method returns the Promise directly. The advantage of using this method instead is that it is more exception-safe. If the callback f throws an exception, the Future will be rejected automatically and the exception will not escape the callback.

Template Parameters

T	The type that the Future resolves to.
Func	The type of the callback function.

Parameters

f	The callback function to invoke immediately to create the Future.

Returns: A Future that will resolve when the callback function resolves the supplied Promise.

Definition at line 65 of file AsyncSystem.h.

◆ createPromise()

template<typename T>

Promise< T > CesiumAsync::AsyncSystem::createPromise ( ) const

inline

Create a Promise that can be used at a later time to resolve or reject a Future.

Use Promise<T>::getFuture to get the Future that is resolved or rejected when this Promise is resolved or rejected.

Consider using AsyncSystem::createFuture instead of this method.

Template Parameters

T	The type that is provided when resolving the Promise and the type that the associated Future resolves to. Future.

Returns: The Promise.

Definition at line 93 of file AsyncSystem.h.

◆ createResolvedFuture() [1/2]

Future< void > CesiumAsync::AsyncSystem::createResolvedFuture ( ) const

inline

Creates a future that is already resolved and resolves to no value.

Returns: The future.

Definition at line 271 of file AsyncSystem.h.

◆ createResolvedFuture() [2/2]

template<typename T>

Future< T > CesiumAsync::AsyncSystem::createResolvedFuture ( T && value ) const

inline

Creates a future that is already resolved.

Template Parameters

T	The type of the future.

Parameters

value The value for the future.

Returns: The future.

Definition at line 260 of file AsyncSystem.h.

◆ createThreadPool()

ThreadPool CesiumAsync::AsyncSystem::createThreadPool ( int32_t numberOfThreads ) const

Creates a new thread pool that can be used to run continuations.

Parameters

numberOfThreads The number of threads in the pool.

Returns: The thread pool.

◆ dispatchMainThreadTasks()

void CesiumAsync::AsyncSystem::dispatchMainThreadTasks ( )

Runs all tasks that are currently queued for the main thread.

The tasks are run in the calling thread.

◆ dispatchOneMainThreadTask()

bool CesiumAsync::AsyncSystem::dispatchOneMainThreadTask ( )

Runs a single waiting task that is currently queued for the main thread. If there are no tasks waiting, it returns immediately without running any tasks.

The task is run in the calling thread.

Returns: true A single task was executed.; false No task was executed because none are waiting.

◆ operator!=()

bool CesiumAsync::AsyncSystem::operator!= ( const AsyncSystem & rhs ) const

noexcept

Returns true if this instance and the right-hand side can not be used interchangeably because they schedule continuations differently. Otherwise, returns false.

◆ operator==()

bool CesiumAsync::AsyncSystem::operator== ( const AsyncSystem & rhs ) const

noexcept

Returns true if this instance and the right-hand side can be used interchangeably because they schedule continuations identically. Otherwise, returns false.

◆ runInMainThread()

template<typename Func>

CesiumImpl::ContinuationFutureType_t< Func, void > CesiumAsync::AsyncSystem::runInMainThread ( Func && f ) const

inline

Runs a function in the main thread, returning a Future that resolves when the function completes.

If the function itself returns a Future, the function will not be considered complete until that returned Future also resolves.

If this method is called from the main thread, the callback will be invoked immediately and complete before this function returns.

Template Parameters

Func	The type of the function.

Parameters

f	The function.

Returns: A future that resolves after the supplied function completes.

Definition at line 146 of file AsyncSystem.h.

◆ runInThreadPool()

template<typename Func>

CesiumImpl::ContinuationFutureType_t< Func, void > CesiumAsync::AsyncSystem::runInThreadPool	(	const ThreadPool &	threadPool,
		Func &&	f ) const

inline

Runs a function in a thread pool, returning a Future that resolves when the function completes.

Template Parameters

Func	The type of the function.

Parameters

threadPool	The thread pool in which to run the function.
f	The function to run.

Returns: A future that resolves after the supplied function completes.

Definition at line 171 of file AsyncSystem.h.

◆ runInWorkerThread()

template<typename Func>

CesiumImpl::ContinuationFutureType_t< Func, void > CesiumAsync::AsyncSystem::runInWorkerThread ( Func && f ) const

inline

Runs a function in a worker thread, returning a Future that resolves when the function completes.

If the function itself returns a Future, the function will not be considered complete until that returned Future also resolves.

If this method is called from a designated worker thread, the callback will be invoked immediately and complete before this function returns.

Template Parameters

Func	The type of the function.

Parameters

f	The function.

Returns: A future that resolves after the supplied function completes.

Definition at line 116 of file AsyncSystem.h.

Friends And Related Symbol Documentation

◆ Future

template<typename T>

friend class Future

friend

Definition at line 375 of file AsyncSystem.h.

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

/home/runner/work/cesium-native/cesium-native/CesiumAsync/include/CesiumAsync/AsyncSystem.h

Public Types

Public Member Functions

Friends

Detailed Description

Member Typedef Documentation

◆ AllValueType

◆ MainThreadScope

Constructor & Destructor Documentation

◆ AsyncSystem()

Member Function Documentation

◆ all() [1/2]

◆ all() [2/2]

◆ createFuture()

◆ createPromise()

◆ createResolvedFuture() [1/2]

◆ createResolvedFuture() [2/2]

◆ createThreadPool()

◆ dispatchMainThreadTasks()

◆ dispatchOneMainThreadTask()

◆ operator!=()

◆ operator==()

◆ runInMainThread()

◆ runInThreadPool()

◆ runInWorkerThread()

Friends And Related Symbol Documentation

◆ Future