Concurrency & Threading

Introduction

The game engine provides general-purpose multi-threading through the Job System (code). This is a recommended approach for compute-heavy tasks which may slow down the game. When a 'job' is launched, it is scheduled to be executed on an available thread at some time in the future.

The job system uses Java's CompletableFuture class to return job results. We recommend reading a tutorial or the documentation before using the job system.

Concurrency

Do not use jobs purely to run code concurrently, i.e. running two things at the same time. The update pattern (see Entity Component System) is designed to allow everything in the game to run 'concurrently' by computing one step at a time. If you want to run two things at the same time, consider just doing this in update().

Do not use jobs purely to create delays. It may be tempting when creating some delay to use Thread.sleep(delay) or equivalent on a separate thread. This is computationally expensive and unnecessary. Consider using the update() function together with class variables which store game time. For example, the following component would print to the console every 1000ms:

class PrintComponent extends Component {
  private long lastTime = 0L;

  @Override
  public void update() {
    long currentTime = ServiceLocator.getTimeSource().getTime();
    if (currentTime - lastTime >= 1000L) {
       System.out.println("Hello!");
       lastTime = currentTime;
    }
  }
}

Usage

It's important to consider whether your job is blocking or non-blocking. A blocking job is one that stops execution while waiting on something, such as a delay (Thread.sleep()) or an I/O operation (accessing a file, user input, networking).

Non-blocking jobs

Below is an example of creating a job that performs an expensive path-finding calculation for an NPC.

public class PathFindComponent extends Component {
  private Path currentPath;
  private CompletableFuture<Path> nextPathFuture;

  @Override
  public void create() {
    // Start calculating the next path
    nextPathFuture = JobSystem.launch(this::findNewPath);
  }

  @Override
  public void update() {
    if (nextPathFuture.isDone()) {
      currentPath = nextPathFuture.join();
      // Start calculating the next path
      JobSystem.launch(this::findNewPath);
    } else {
      // Continue moving along the path
      moveAlong(currentPath);
    }
  }

  Path findNewPath() {
    // This method is running on a separate thread, be careful 
    // about accessing class variables!
    return expensivePathCalculation();
  }
}

Further Reading

• Introduction to Concurrency: Chapter 4, Game Engine Architecture (3rd Edition)
• Concurrency in Game Engines: Parallelizing the Naughty Dog Engine or Chapter 8.6, Game Engine Architecture (3rd Edition)