Scheduling, awaiting and cancelling actions

What is an Action?

An Action is like Runnable but for an ActionEngine (see Creating an Action for more information).

What is an ActionEngine?

An ActionEngine is used to schedule and execute Actions.

There are several default ActionEngine implementations availaible but this page will use the default common pool engine for the examples (see Picking an ActionEngine implementation for more information).

ActionEngine engine = ForkJoinActionEngine.commonPoolEngine();

Creating a SchedulableActionContext

A SchedulableActionContext is constructed for an Action and it is used for binding information, scheduling, awaiting and cancelling execution. Here the context is created:

Action<?> action = /* Some action */
SchedulableActionContext<?> context = engine.newContext(action);

A context can also be created referencing a specific actor (typed):

Action<String> strAction = /* Some action */
SchedulableActionContext<String> context = engine.newContext(action, "Ellzord");

Binding in additional information

SchedulableActionContext is a subclass of ActionBindings so information can be bound directly to the context (key-value pairs):

context.put("framework", "JALSE");

ActionEngine provides a set of bindings for the entire engine - these are copied to the context on creation. So adding the information to the engine bindings before creating the context could also achieve the same result:

engine.putInBindings("framework", "JALSE");

This is most useful for information not unique to a specific Action instance but many.

Scheduling an Action

The SchedulableActionContext set all of the execution parameters before scheduling the Action. This includes initial delay context.setInitialDelay(long, TimeUnit) and repeat period context.setPeriod(long, TimeUnit). The Action can be scheduled as shown below:

context.schedule();

ActionEngine provides a way to create and schedule an Action easily: engine.schedule(/* some action */).

Awaiting an Actions completion

A scheduled Action can be awaited:

context.await();

This will await either completion or cancellation. The Action can be both scheduled and awaited using context.scheduleAndAwait().

Cancelling an Action

A scheduled Action can be cancelled:

context.cancel();

Additional information

ActionContext also provides methods for checking the execution state of an Action (see API docs).