asge::concurrent::Context

A cancellable context that propagates cancellation through a tree.

#include <Context.hpp>

Inherits from asge::concurrent::_internal::IContext, std::enable_shared_from_this< Context >.

Inherited by asge::concurrent::ContextWithValue< T >.

Inheritance

classDiagram
    class N1["asge::concurrent::Context"]
    class N4["asge::concurrent::ContextWithValue"]
    class N2["asge::concurrent::_internal::IContext"]
    class N3["std::enable_shared_from_this"]
    N2 <|-- N1
    N3 <|-- N1
    N1 <|-- N4
    click N1 href "classasge_1_1concurrent_1_1Context.html"
    click N4 href "classasge_1_1concurrent_1_1ContextWithValue.html"
    click N2 href "structasge_1_1concurrent_1_1__internal_1_1IContext.html"

Collaboration

classDiagram
    class N1["asge::concurrent::Context"]
    class N4["asge::concurrent::_internal::CancelState"]
    class N2["asge::concurrent::_internal::IContext"]
    class N3["std::enable_shared_from_this"]
    N2 <|-- N1
    N3 <|-- N1
    N1 --> N4 : m_State
    click N1 href "classasge_1_1concurrent_1_1Context.html"
    click N4 href "structasge_1_1concurrent_1_1__internal_1_1CancelState.html"
    click N2 href "structasge_1_1concurrent_1_1__internal_1_1IContext.html"

Context is the core building block of the cancellation system. Each context is a node in a tree — when a context is cancelled, the cancellation propagates automatically to all of its children, and transitively to their children.

A Context is never constructed directly. Instead it is created through the WithCancel() factory function, which derives a child from an existing parent. The root of any context tree is always the Background() context.

Cancellation is cooperative — a context does not forcibly stop any thread. Code that receives a context is expected to poll Done() or block on Wait() at safe points and exit cleanly when the context is cancelled.

Context is non-copyable and non-movable. It must always be heap-allocated and shared via Context::pointer (shared_ptr<Context>), which is what the factory functions return. The read-only interface (context_pointer) can be handed to consumers that should observe but never cancel the context.

Protected Types

#using child_t = std::weak_ptr< _internal::IContext >protected

#using children = std::vector< child_t >protected

Public Types

#using pointer = std::shared_ptr< Context >

Protected Attributes

#mutable std::mutex m_Mtxprotected

#_internal::CancelState m_Stateprotected

#children m_Childrenprotected

#context_pointer m_Parent {nullptr}protected

Protected Member Functions

#explicit Context(context_pointer inParent)protected

#void Attach()protected

Private Member Functions

#virtual void AddChild(context_pointer const &inChild) noexcept overrideprivate

Overrides AddChild

#virtual void Cancel(ContextErr inErr) overrideprivate

Overrides Cancel

Public Member Functions

#Context(Context const &)=delete

#Context & operator=(Context const &)=delete

#Context(Context &&)=delete

#Context & operator=(Context &&)=delete

#virtual bool Done() const noexcept

Overrides Done

#virtual void Wait() const

Overrides Wait

#virtual ContextErr Err() const noexcept

Overrides Err

#void Cancel()

Friends

#friend WithCancelprivate

Derives a child context that can be manually cancelled.

The returned context is a child of the given parent. If the parent is already cancelled at the time of this call, the child is cancelled immediately with the same error. Otherwise, the child is registered with the parent and will be cancelled automatically when the parent is.

If no parent is provided, Background() is used as the parent.

Parameters

inParent

The parent context. Defaults to Background() if nullptr.

Returns

A shared_ptr<Context> exposing Cancel() directly.