com.lhkbob.entreri.task

Interface Task

All Known Implementing Classes:

SimpleTask

public interface Task

Tasks are functional processors of the entities and components within an EntitySystem. Different Task implementations have different purposes, such as updating transforms, computing physics or AI, or rendering a scene. Generally task implementations should be as small and as independent as possible to allow for reuse and easy composability.

The Job and Scheduler work together to coordinate the execution of collections of tasks. Tasks are grouped into jobs, where a job represents a logical step such as "render frame", or "compute physics", even if it is split into multiple tasks. Within a job, tasks are executed serially, but the scheduler can run different jobs simultaneously.

The ParallelAware can be used with tasks to restrict the contention points of a job. This is important because a job acquires the locks for each of its tasks before invoking the first task. The locks are not released until the last task has terminated.

A task can communicate with the remaining tasks of a job by reporting results. The results are only reported to tasks within the owning job, and that are executed after the current task. Thus tasks that have already completed their processing will not receive new results.

A task receives results by defining any number of methods with the signature public void report(T extends Result). When a result is reported to the job, it will invoke using reflection any report() method that takes a result of the compatible type.

Task instances should only ever be used with a single job and entity system. If the task needs to be performed in multiple jobs or systems, new instances of the same type should be created.

Author:

Michael Ludwig

Method Summary

Methods

Modifier and Type	Method and Description
Task	process(EntitySystem system, Job job) Invoke task specific operations to process the EntitySystem.
void	reset(EntitySystem system) Reset any internal storage within this Task in preparation for the next execution of its owning job.

Method Detail

process

Task process(EntitySystem system,
           Job job)

Invoke task specific operations to process the EntitySystem. This will be invoked on the task's parent job's thread, after the job has acquired any locks mandated by ParallelAware. If this task is not ParallelAware, the job acquires an exclusive lock with the assumption that it could modify anything.

A task can return another task to be invoked after the owning job completes. These returned tasks are executed within their own set of locks, so it can be used to segment how long, and which locks are held by a job.

Parameters:

system - The EntitySystem being processed, which will always be the same for a given Task instance

job - The Job this task belongs to

Returns:

A nullable task that is executed after the job is completed

reset

void reset(EntitySystem system)

Reset any internal storage within this Task in preparation for the next execution of its owning job. This is used when jobs are scheduled to repeat at a given rate. Instead of instantiating new tasks every time, they can reset their tasks.

Examples of how this can be used is if a spatial index is built up per-frame, or if decorated properties cache computed results. By using reset(), it's not necessary to re-decorate or allocate again.

Parameters:

system - The EntitySystem that will be processed, which will always be the same for a given Task instance