org.spongepowered.api.scheduler

Interface Task.Builder

All Superinterfaces:

ResettableBuilder<Task,Task.Builder>

Enclosing interface:

Task

public static interface Task.Builder
extends ResettableBuilder<Task,Task.Builder>

Represents a builder to create a Task.

Method Summary

Modifier and Type	Method and Description
Task.Builder	async() Sets whether the task should run asynchronous, outside of the main loop, and in it's own thread.
Task.Builder	delay(long delay, TimeUnit unit) Sets the delay before the task runs.
Task.Builder	delayTicks(long ticks) Sets the delay before the task runs, in unit ticks.
Task.Builder	execute(Consumer<Task> executor) Sets the consumer that runs when this task executes.
default Task.Builder	execute(Runnable runnable) Sets the Runnable to run when this task executes.
Task.Builder	interval(long interval, TimeUnit unit) Sets the interval between repetitions of the task.
Task.Builder	intervalTicks(long ticks) Sets the interval in unit ticks between repetitions of the task.
Task.Builder	name(String name) Sets the name of the task, the name cannot be blank.
Task	submit(Object plugin) Submits the task to the scheduler and returns the task that was created.

Methods inherited from interface org.spongepowered.api.util.ResettableBuilder

from, reset

Method Detail

async

Task.Builder async()

Sets whether the task should run asynchronous, outside of the main loop, and in it's own thread. By default, tasks are synchronous.

A synchronous task is ran in alignment with the game's main loop, in the same thread. Each synchronous task is ran in series with the tick cycle. It is safe to manipulate game data when running in this mode.

In contrast, a task set to run asynchronously will run independently of the tick cycle and in it's own thread. Therefore the task is not thread safe with game data and care must be taken. It is strongly advised to not manipulate game data in asynchronous tasks.

It is not possible to schedule a task in unit ticks when running asynchronously. If the delay or interval is specified in ticks, it will be converted to the equivalent wall clock time by multiplying the value by Scheduler.getPreferredTickInterval().

Returns:

This builder, for chaining

execute

default Task.Builder execute(Runnable runnable)

Sets the Runnable to run when this task executes.

Parameters:

runnable - The actual task to run

Returns:

This builder, for chaining

execute

Task.Builder execute(Consumer<Task> executor)

Sets the consumer that runs when this task executes.

Parameters:

executor - The executor to run

Returns:

This builder, for chaining

delay

Task.Builder delay(long delay,
                   TimeUnit unit)

Sets the delay before the task runs. This delay is an initial offset, subsequent runs (when the interval is not 0) will not be offset. By default, the delay is 0.

Parameters:

delay - The delay in the given TimeUnit

unit - The unit the delay is in

Returns:

This builder, for chaining

Throws:

IllegalArgumentException - If the delay is below 0

delayTicks

Task.Builder delayTicks(long ticks)

Sets the delay before the task runs, in unit ticks.

Parameters:

ticks - The delay in ticks

Returns:

This builder, for chaining

Throws:

IllegalArgumentException - If the delay is below 0

See Also:

delay(long, TimeUnit)

interval

Task.Builder interval(long interval,
                      TimeUnit unit)

Sets the interval between repetitions of the task. The task will not repeat if the interval is 0. By default, the interval is 0.

If the scheduler detects that two tasks will overlap, the 2nd task will not be started. The next time the task is due to run, the test will be made again to determine if the previous occurrence of the task is still alive (running). As long as a previous occurrence is running no new occurrences of that specific task will start, although the scheduler will never cease in trying to start it a 2nd time.

Parameters:

interval - The interval in the given TimeUnit

unit - The unit the interval is in

Returns:

This builder, for chaining

Throws:

IllegalArgumentException - If the interval is below 0

intervalTicks

Task.Builder intervalTicks(long ticks)

Sets the interval in unit ticks between repetitions of the task.

Parameters:

ticks - The number of ticks between runs

Returns:

This builder, for chaining

Throws:

IllegalArgumentException - If the interval is below 0

See Also:

interval(long, TimeUnit)

name

Task.Builder name(String name)

Sets the name of the task, the name cannot be blank.

If the name is not set in the builder, the name of the task will be the form:
PLUGIN_ID "-" ( "A-" | "S-" ) SERIAL_ID

Examples of default Task names:
"FooPlugin-A-12"
"BarPlugin-S-4322"

No two active tasks will have the same serial ID for the same synchronisation type.
i.e APlugin-A-15 and BPlugin-A-15 is not possible but BPlugin-S-15 is.

Parameters:

name - The task name

Returns:

This builder, for chaining

Throws:

IllegalArgumentException - If the name is blank

submit

Task submit(Object plugin)

Submits the task to the scheduler and returns the task that was created.

Parameters:

plugin - The owner of the task

Returns:

A new instance of a Task

Throws:

IllegalArgumentException - If the object passed in is not a plugin instance

IllegalStateException - If the builder is incomplete