Overview

One of the main design principles of the ManagerInterface is that it is a reentrant and thread-safe API. Consequently, the result of any call to an instance of this class should solely depend on the initialization settings, underlying asset data and the method arguments. Any session state is held by the caller and supplied to the manager as part of the method signature. This is to allow multi-threaded access to the ManagerInterface and avoid the inherent need for any additional internal state to exist within its implementation. The Manager class wraps the interface implementation to help the host with basic session state management.

Many common use cases require multiple calls to the API to complete a task. Several textures need to be published together, or multiple frames of a render need to be distributed to a render-farm.

If a manager wants to support the concept of a Meta-version, it becomes essential that there is some way for the manager to know that disparate calls to the API are part of the same conceptual action, so that the resolution of references is stable.

To achieve this, we introduce the idea of a Manager State token.

Note: Generating a state token is optional for the manager. However, without one, it is not possible to know if any two API calls are being made from a related process.

Manager State

The manager state mechanism allows a manager to embed state within the host, such that it can correlate API calls.

Whenever a Context is created by the host, if the manager is capable, the ManagerInterface.createState (or ManagerInterface.createChildState) method will be called, and the returned token stored in the Context's managerState property.

Warning: The host must treat the token as being opaque, and is solely responsible for managing the lifetime of each Context such that it is re-used for logically correlated series of actions. The API middleware takes care of requesting and persisting the state token.

Distributed Processing

Distributed processing requires the same context to be shared by multiple discrete working processes.

The Manager.persistenceTokenForContext and contextFromPersistenceToken methods provide a mechanism by which a host can obtain a portable version of the manager's state token for a given context for distribution to other processes that are logically connected.

Note: The above diagram omits the interaction between the Manager and ManagerInterface classes for readability. Right-click to open in a larger view.

This mechanism allows for distributed API calls to be anchored to specific snapshot of a manager's view of the world. It is not intended to be used to group discrete publishing actions into a batch. This (may be) covered (in the future) by a separate transaction API.

The reason for this is that a host may need to perform multiple independent transactions during the lifetime of a single context.

Implementation Guidelines

Because a state restored from a persistence token may be passed to multiple child processes, the manager must be prepared for the state to be restored more than once, at the same time.