Class: TaskScheduler

SFSApi. TaskScheduler

The TaskScheduler class allows to manage multiple delayed or repeating activities.

In games, a delayed scheduled task can be useful to set the duration of a match, or set a time limit to a user action, etc. An interval-based task instead can be used to spawn new NPC enemies on a time basis, or divide the game in rounds, etc.

Notes

  • In general it is recommended to use one TaskScheduler per application/Zone. If this needs to be accessed in different parts of the code, a reference should be mantained in a Zone-level Extension and accessed from any other Extension(s) attached to Rooms in the same Zone.
  • It is advisable to avoid spawning very large thread pools, unless there are specific reasons for doing so. A setting of 1-4 threads is usually sufficient to handle any number of concurrent delayed events. The only exception to this is when the tasks to be executed are long-running such as accessing a database, a remote web-service or HTTP server, etc.
  • Any runtime exception will stop the execution of the task, so it is strongly recommended to always add a try/catch block to prevent this from happening.

See also

Constructor


new TaskScheduler(threadPoolSize)

Creates a new TaskScheduler instance.

Using the SFSApi#newScheduler factory method instead of this constructor is recommended. See the method description for a usage example.

Parameters:
Name Type Description
threadPoolSize number The number of threads backing the scheduler (recommended value between 1 and 4).

Methods


destroy()

Destroys the TaskScheduler instance and all the tasks that are currently running.

getThreadPoolSize()

Returns the size of the thread pool handling the tasks.
Returns:
The number of threads backing the scheduler.
Type: number

schedule(runnerFn, delay [, context])

Schedules a new task to be executed in the future, once.
Parameters:
Name Type Argument Description
runnerFn function The function to be executed after the provided time delay has passed.
delay number The amount of time before the runner function is executed.
context object <optional>
An object representing the scope of the runner function (also known as the "this" object).
Throws:
An IllegalArgumentException Java exception if the delay is lower than or equal to 0.
Returns:
A reference to the ScheduledFuture Java class representing the scheduled task; it is useful to keep a reference to this object, in case the task execution needs to be cancelled later.
Type: ScheduledFuture

scheduleAtFixedRate(runnerFn, interval [, delay] [, context])

Schedules a new task to be executed periodically.
Parameters:
Name Type Argument Default Description
runnerFn function The function to be executed at each interval.
interval number The interval at which the runner function should be executed.
delay number <optional>
0 The initial amount of time before the runner function is executed for the first time.
context object <optional>
An object representing the scope of the runner function (also known as the "this" object).
Throws:
An IllegalArgumentException Java exception if the interval is lower than or equal to 0.
Returns:
A reference to the ScheduledFuture Java class representing the scheduled task; it is useful to keep a reference to this object, in case the task execution needs to be cancelled later.
Type: ScheduledFuture