Terasology/docs/5.3-Migrating-to-Project-Reactor.md

Migrating to Project Reactor

Motivation

The two main reasons we are adopting Reactor for our concurrent operations:

1. Using a consistent API helps with thread management, making it easier to allocate the right amount of threads and clean them up when we need to.
2. The Flux API offered by Project Reactor provides better ways to define and schedule asynchronous operations than the standard Java API does.

Deprecations

• The creation of threads and threadpools is something that should be mediated by the engine. Modules should not be using new Thread() directly.
• o.t.e.utilites.concurrency.TaskMaster and its related Task class.

New Interfaces

Most Project Reactor classes (from Reactor Core, Reactor Extra, and Reactor Test) are available to modules. The Reactor Reference Guide includes an introduction to them. (It occasionally assumes familiarity with the Reactive Streams specification, but its examples are complete on their own.)

The o.t.e.core.GameScheduler class provides methods for scheduling work or obtaining a Scheduler instance.

Migration Guide

TaskMaster

Replacements for TaskMaster methods:

• TaskMaster.create*(name, threads): Use GameScheduler to use an existing Scheduler instance. We do not expect modules need to create new Schedulers.
• Task: Runnable. (Runnable is a Functional Interface in Java; any zero-argument method may be passed anywhere a Runnable is expected.)
• task.getName(): Pass a name to GameScheduler.scheduleParallel(name, task).
• tm.offer(task): GameScheduler.scheduleParallel(name, task).
• tm.put(task): This is a blocking method; no direct replacement is offered. Replace it with an asynchronous method, perhaps using Reactor's Mono to schedule work to continue after its completion.

The above methods are only the ones that most directly correspond to the old TaskMaster interface. You will likely want to take advantage of other Flux operations to use the results of asynchronous methods and handle errors.