com.lhkbob.entreri.task

Interface ParallelAware

public interface ParallelAware

ParallelAware is an interface that Task implementations can implement. Tasks that are parallel aware hold to the contract that they will only modify a limited and knowable set of component types, or that they will or will not add or remove entities from the entity system.

With that assumption based on the what is returned by getAccessedComponents() and isEntitySetModified(), jobs will automatically guarantee thread safe execution of their tasks.

It is highly recommended to implement ParallelAware if it's known what types of components or entities will be modified at compile time.

Author:

Michael Ludwig

Method Summary

Methods

Modifier and Type	Method and Description
Set<Class<? extends Component>>	getAccessedComponents() Get the set of all component data types that might have their data mutated, be added to, or removed from an entity.
boolean	isEntitySetModified() Return whether or not entities are added or removed from an EntitySystem.

Method Detail

getAccessedComponents

Set<Class<? extends Component>> getAccessedComponents()

Get the set of all component data types that might have their data mutated, be added to, or removed from an entity. This must always return the same types for a given instance, it cannot change based on state of the task. Instead, it must return the maximal set of types that might be added, removed, or modified by the task.

If a task's component access is determined at runtime, then it should not be parallel aware, or it should return true from isEntitySetModified().

Jobs that do not share any access to the same component types (i.e. their intersection of the returned set is empty), can be run in parallel if they both return false from isEntitySetModified().

Returns:

The set of all component types that might be added, removed, or modified by the task

isEntitySetModified

boolean isEntitySetModified()

Return whether or not entities are added or removed from an EntitySystem. Note that this refers to using EntitySystem.addEntity() or EntitySystem.removeEntity(Entity). When true is returned, the job will be forced to execute with an exclusive lock that blocks other jobs.

Thus it is a best practice to limit the run-time of tasks that require exclusive locks. It is better to have a parallel aware task that accesses only specific component types to determine if an entity must be added or removed.

Once these are determined, it keeps track and returns a new task from Task.process(EntitySystem, Job) that will get the exclusive lock and perform the determined additions or removals.

Like getAccessedComponents(), this must always return the same value for a given instance, and cannot change during its lifetime.

Returns:

True if the task might add or remove entities from the system