Meta Developers

Context is a tool for coordinating the operation of disparate instances in a generalized and decoupled way: different instances can collaborate with one another without directly depending on one another by sharing data and conventions using a Context.

A common example of this kind of collaboration is for instance decoration; for detailed commentary on that usage, see DecoratorBase<InstanceT, DecorationT>.

Conceptually, a Context is a logical scope of ownership and operation which is not bound to a specific region of the implementation. Just as a code scope (the braces after an if or for statement, for example) both owns and provides access to the data it contains for example, an int variable declared in a scope will be automatically released when the scope end, but within the scope it can be accessed by its name so too is a Context capable of owning and providing access to data required by the operations it supports/logically "contains." Contexts are a common feature of many libraries, including examples such as System.AppContext from the .NET API itself.

The Context implementation provided here is specifically designed to support a "safe singleton" pattern in Unity applications. The "safe singleton" pattern aims to provide the majority of the benefits of singletons (mainly simplicity) while avoiding the problems associated with global state; this is achieved because "safe singletons" are not "global" to the app, but are merely "global" to a particular Context instance which owns, enforces the uniqueness of, and provides access to its singletons.

The impact of this pattern on true global state is thus confined to the provided Global Context instance. This instance is provided for convenience and is very valuable for quick-and-dirty work. However, because this does have an (albeit confined) impact on centralized global state, development which must be scalable should not rely on the Global Context. Libraries, for example, which wish to leverage Context-based patterns should simply define and expose their own Instance to avoid colliding with global considerations.

Properties

static Instance Global[Get]

The global Context, which can be used as a default Context for quick-and-dirty development.

This Instance is provided for convenience and can be safely used for end-product development (i.e., for the development of an individual game), but development that must incorporate or scale (i.e., library development) should rely on independently Context Instances instead. See the remarks on Context and Instance for a more detailed exploration of this topic.

Events

Action WhenDestroyed

Event which signals the destruction of a Context, allowing dependent instances an opportunity to react.

Static Member Functions

static void ExecuteOnMainThread

( Action work )

Executes the specified work on the main Unity thread.

This function provides an easy way for work triggered from arbitrary threads to be performed specifically on the main thread; for example, FinalAction uses this method to cause a callback invoked during destruction (which can happen on any thread) to be executed on the Unity main thread.Unity 6+ introduces improved support for asynchronous programming techniques, including a new Awaitable.MainThreadAsync which can be used for the same purpose as this method.

Parameters

work

The work to execute on the main thread

Member Functions

T GetOrCreateSingleton< T > ( )

Retrieves a Context-local or "safe" singleton instance from this Context.

If an instance of the requested type already exists on this Context, that instance will be returned; otherwise, a new one will be lazily created. This method implements the "safe singleton" pattern discussed in the remarks on the Context. While the name "GetOrCreate" is used to clarify that the requested instance may be created during this call, this method should really only be thought of as an accessor with any instantiation that may or may not happen being simply an irrelevant implementation detail. Ideally, you should think of Context-local singletons as aspects of the Context itself rather than as separate instances which can be created and destroyed independently. Adhering to this thinking will ensure that order-of-operations and independent lifecycles do not complicate the usage of Context. As long as the Context merely exists, all singletons on it can always be accessed identically using GetOrCreateSingleton; all other considerations are the purview of the singletons themselves.

Others

The type of the singleton to be retrieved

Returns

A Context-local singleton of the requested type

T GetOrCreateSingleton< T >

( Func< T > factory )

Retrieves a Context-local or "safe" singleton instance from this Context.

If an instance of the requested type already exists on this Context, that instance will be returned; otherwise, a new one will be lazily created by invoking the provided factory callback. This method differs from GetOrCreateSingleton<T> in that it accepts a factory callback, which it will invoke to create the singleton if necessary instead of simply calling new(). This is useful for singleton types which can only be constructed with arguments, or for types with private constructors. This method implements the "safe singleton" pattern discussed in the remarks on Context and further explored in the remarks on GetOrCreateSingleton<T>.

Others

The type of the singleton to be retrieved

Parameters

factory

A callback which creates a singleton of the requested type

Returns

A Context-local singleton of the requested type