CeresEngine::ExecutionContext Class Reference

A context for function object execution. More...

#include <CeresEngine/Foundation/Threading/ExecutionContext.hpp>

Inheritance diagram for CeresEngine::ExecutionContext:

Classes
class	Scope
	Scope object that sets the current execution context as current. More...
class	Service

Public Types
using	ID = id
using	executor_type = AnyExecutor

Public Member Functions
virtual	~ExecutionContext () noexcept=default
	Virtual destructor for the execution context object.
template<typename T >
bool	hasService () noexcept
	Determine if the ExecutionContext contains the specified service type.
template<typename T >
T &	getService () noexcept
	Obtain the service object corresponding to the given type.
template<typename T >
T *	getServiceIf () noexcept
	Obtain the service object corresponding to the given type.
virtual AnyExecutor	getExecutor () noexcept=0
	Returns an executor that run execute scheduled commands on the context.
executor_type	get_executor () noexcept
	Returns an executor that run execute scheduled commands on the context.
bool	isActive () const noexcept
	Checks if the execution context is currently active.

Static Public Member Functions
static ExecutionContext *	getCurrent () noexcept
	Gets the current execution context, if any is active.
static ExecutionContext &	get () noexcept
	Gets the current execution context, if any is active.

Detailed Description

A context for function object execution.

An execution context represents a place where function objects will be executed. An io_context is an example of an execution context.

The ExecutionContext class and services

Class ExecutionContext implements an extensible, type-safe, polymorphic set of services, indexed by service type.

Services exist to manage the resources that are shared across an execution context. For example, timers may be implemented in terms of a single timer queue, and this queue would be stored in a service.

Access to the services of an execution_context is via three function templates, use_service(), add_service() and has_service().

In a call to use_service<Service>(), the type argument chooses a service, making available all members of the named type. If Service is not present in an execution_context, an object of type Service is created and added to the execution_context. A C++ program can check if an execution_context implements a particular service with the function template has_service<Service>().

Service objects may be explicitly added to an execution_context using the function template add_service<Service>(). If the Service is already present, the service_already_exists exception is thrown. If the owner of the service is not the same object as the execution_context parameter, the invalid_service_owner exception is thrown.

Once a service reference is obtained from an execution_context object by calling use_service(), that reference remains usable as long as the owning execution_context object exists.

All service implementations have execution_context::service as a public base class. Custom services may be implemented by deriving from this class and then added to an execution_context using the facilities described above.

The execution_context as a base class

Class execution_context may be used only as a base class for concrete execution context types. The io_context is an example of such a derived type.

On destruction, a class that is derived from execution_context must perform execution_context::shutdown() followed by execution_context::destroy().

This destruction sequence permits programs to simplify their resource management by using shared_ptr<>. Where an object's lifetime is tied to the lifetime of a connection (or some other sequence of asynchronous operations), a shared_ptr to the object would be bound into the handlers for all asynchronous operations associated with it. This works as follows:

• When a single connection ends, all associated asynchronous operations complete. The corresponding handler objects are destroyed, and all shared_ptr references to the objects are destroyed.

• To shut down the whole program, the io_context function stop() is called to terminate any run() calls as soon as possible. The io_context destructor calls shutdown() and destroy() to destroy all pending handlers, causing all shared_ptr references to all connection objects to be destroyed.

Member Typedef Documentation

executor_type

using CeresEngine::ExecutionContext::executor_type = AnyExecutor

ID

using CeresEngine::ExecutionContext::ID = id

Constructor & Destructor Documentation

~ExecutionContext()

virtual CeresEngine::ExecutionContext::~ExecutionContext ( )

virtualdefaultnoexcept

Virtual destructor for the execution context object.

Member Function Documentation

get()

static ExecutionContext & CeresEngine::ExecutionContext::get ( )

inlinestaticnoexcept

Gets the current execution context, if any is active.

Returns

The currently active execution context. If multiple executions contexts are active on this thread, returns the top most one.

get_executor()

executor_type CeresEngine::ExecutionContext::get_executor ( )

noexcept

Returns an executor that run execute scheduled commands on the context.

getCurrent()

static ExecutionContext * CeresEngine::ExecutionContext::getCurrent ( )

staticnoexcept

Gets the current execution context, if any is active.

Returns

The currently active execution context. If multiple executions contexts are active on this thread, returns the top most one.

getExecutor()

virtual AnyExecutor CeresEngine::ExecutionContext::getExecutor ( )

pure virtualnoexcept

Returns an executor that run execute scheduled commands on the context.

Implemented in CeresEngine::AppleDispatchQueue, CeresEngine::AppleRunLoop, CeresEngine::EmscriptenRunLoop, CeresEngine::Win32RunLoop, CeresEngine::Win32ThreadPool, and CeresEngine::ThreadPool.

getService()

template<typename T >

T & CeresEngine::ExecutionContext::getService ( )

inlinenoexcept

Obtain the service object corresponding to the given type.

This function is used to locate a service object that corresponds to the given service type. If there is no existing implementation of the service, then the ExecutionContext will create a new instance of the service.

Returns

The service interface implementing the specified service type. Ownership of the service interface is not transferred to the caller.

getServiceIf()

template<typename T >

T * CeresEngine::ExecutionContext::getServiceIf ( )

inlinenoexcept

Obtain the service object corresponding to the given type.

This function is used to locate a service object that corresponds to the given service type. If there is no existing implementation of the service, nullptr is returned.

Returns

The service interface implementing the specified service type. Ownership of the service interface is not transferred to the caller.

hasService()

template<typename T >

bool CeresEngine::ExecutionContext::hasService ( )

inlinenoexcept

Determine if the ExecutionContext contains the specified service type.

This function is used to determine whether the ExecutionContext contains a service object corresponding to the given service type.

Returns

A boolean indicating whether the ExecutionContext contains the service.

isActive()

bool CeresEngine::ExecutionContext::isActive ( ) const

noexcept

Checks if the execution context is currently active.

Returns

true if the execution context is active (top most or not); false otherwise.

---

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

• /Users/Rogiel/Developer/CeresEngine/Engine/Sources/CeresEngine/Foundation/Threading/ExecutionContext.hpp