Concurrency Keys

Keys for scheduling

Concurrent invoke execution is defined in terms of a list of abstract concurrency keys. Each key is just an integer which provides a scheduling hint to the server.

The key for a specific invoke is determined by consulting the ConcurrencyStrategy.concurrencyKey, for that specific entity service, passing in the message. This allows the entity service to define how to map a given invoke into its key space on a per-invoke basis.

The rules for these keys are as follows:

• All user-defined concurrency keys must be positive integers.

• No 2 invokes, with the same concurrency key, can run at the same time. That is, they are serialized within the scope of a key.

• A special MAINTENANCE_KEY is defined which runs exclusively, relative to other keys. That is, no other invoke will run against a given entity while something is running on the MAINTENANCE_KEY.

• A special UNIVERSAL_KEY is defined which allows an invoke to run in any relative order. This is the only case where 2 invokes can run at the same time, while still being on the same key.

• All special calls into an entity, from the platform (createNew, connected, etc) are run on the MAINTENANCE_KEY.

• Concurrency key scope is purely per entity instance. That is, invokes on key n can still run concurrency if they are running on different entity instances.

Interactions with passive synchronization

Additionally, concurrency keys are used to synchronize entity data to a new passive. The synchronization operation of a given key is run within that key, thereby blocking out other invokes targeting that key. Similarly, new passive entities will only see replicated invokes for keys which have already been synchronized.

Per-entity key set

The set of concurrency keys exists per entity instance (since the space of keys must be fixed in order to support passive synchronization). Specifically, the ConcurrencyStrategy instance, created by the EntityServerService, is kept for the life of the entity and is derived only from its initial configuration (byte[] given when it is created).

Note that there is a special-case of this key space where it can be changed via a call to reconfigureEntity but the benefits of this require a passive synchronization and fail-over to be fully realized.