Module net.minestom.server
Package net.minestom.server.thread

Interface ThreadDispatcher<P,E extends Tickable>

public sealed interface ThreadDispatcher<P,E extends Tickable>
ThreadDispatcher can be used to dispatch updates (ticks) across a number of "partitions" (such as chunks) that house Tickable instances (such as entities). The parallelism of such updates is defined when the dispatcher is constructed.

It is recommended that Tickables being added to a dispatcher also implement AcquirableSource, as doing so will allow the user to synchronize external access to them using the Acquirable API.

Instances of this class can be obtained by calling dispatcher(ThreadProvider, int), or a similar overload.

See Also:

  • Method Details

    • dispatcher

      @Contract(pure=true) static <P, E extends Tickable> ThreadDispatcher<P,E> dispatcher(ThreadProvider<P> provider, int threadCount)
      Creates a new ThreadDispatcher using default thread names (ex. Ms-Tick-n).

      Remember to start the dispatcher using start()

      Type Parameters:
      P - the dispatcher partition type
      Parameters:
      provider - the ThreadProvider instance to be used for defining thread IDs
      threadCount - the number of threads to create for this dispatcher
      Returns:
      a new ThreadDispatcher instance

    • dispatcher

      @Contract(pure=true) static <P, E extends Tickable> ThreadDispatcher<P,E> dispatcher(ThreadProvider<P> provider, IntFunction<String> nameGenerator, int threadCount)
      Creates a new ThreadDispatcher using the caller-provided thread name generator nameGenerator. This is useful to disambiguate custom ThreadDispatcher instances from ones used in core Minestom code.

      Remember to start the dispatcher using start()

      Type Parameters:
      P - the dispatcher partition type
      Parameters:
      provider - the ThreadProvider instance to be used for defining thread IDs
      nameGenerator - a function that should return unique names, given a thread index
      threadCount - the number of threads to create for this dispatcher
      Returns:
      a new ThreadDispatcher instance

    • singleThread

      @Contract(pure=true) static <P, E extends Tickable> ThreadDispatcher<P,E> singleThread()
      Creates a single-threaded dispatcher that uses default thread names.

      Remember to start the dispatcher using start()

      Type Parameters:
      P - the dispatcher partition type
      Returns:
      a new ThreadDispatcher instance

    • threads

      @Internal @Unmodifiable List<TickThread> threads()
      Gets the unmodifiable list of TickThreads used to dispatch updates.

      This method is marked internal to reflect TickThreads own internal status.

      Returns:
      the TickThreads used to dispatch updates

    • updateAndAwait

      void updateAndAwait(long time)
      Prepares the update by creating the TickThread tasks.
      Parameters:
      time - the tick time in nanos

    • refreshThreads

      void refreshThreads(long nanoTimeout)
      Called at the end of each tick to clear removed tickables, refresh the partition linked to a tickable, and partition threads based on ThreadProvider.findThread(Object).
      Parameters:
      nanoTimeout - max time in nanoseconds to update partitions

    • refreshThreads

      default void refreshThreads()
      Refreshes all thread as per refreshThreads(long), with a timeout of Long.MAX_VALUE.

    • signalUpdate

      void signalUpdate(ThreadDispatcher.Update<P,E> update)
      Signals an update to the dispatcher.

      This method is used to notify the dispatcher of changes that need to be processed, such as partition loads, unloads, or element updates.

      Updates are processed at the start of each tick, before the actual ticking of elements.

      Parameters:
      update - the update to signal

    • createPartition

      default void createPartition(P partition)

    • deletePartition

      default void deletePartition(P partition)

    • updateElement

      default void updateElement(E element, P partition)

    • removeElement

      default void removeElement(E element)

    • start

      void start()
      Starts all the tick threads.

      This will throw an IllegalThreadStateException if the threads have already been started.

    • isAlive

      boolean isAlive()
      Checks if all the tick threads are alive.
      Returns:
      true if all threads are alive, false otherwise

    • shutdown

      void shutdown()
      Shutdowns all the tick threads.

      Action is irreversible.