Module org.praxislive.core
Package org.praxislive.core

Interface Root.Controller

All Known Implementing Classes:
AbstractRoot.Controller
Enclosing interface:
Root
public static interface Root.Controller
An interface used by the RootHub to control the lifecycle of, and communicate with, the Root.

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    awaitTermination(long timeout, TimeUnit unit)
    Wait for the Root to fully terminate, freeing up all resources.
    boolean
    isAlive()
    Query whether the Root is alive - has been started and has not been signalled to shutdown.
    void
    shutdown()
    Signal the Root to be shutdown.
    default void
    start()
    Convenience method to call start(org.praxislive.core.Lookup) with an empty lookup.
    void
    start(Lookup lookup)
    Start the Root.
    boolean
    submitPacket(Packet packet)
    Deliver a Packet to this Root.

  • Method Details

    • submitPacket

      boolean submitPacket(Packet packet)
      Deliver a Packet to this Root. This method is intended to be called from a thread other than the primary thread of the Root. It will add the packet to a queue and return immediately - this method will never block as it may be called from the thread of another Root.

      This method will return true if the Packet can be handled (see eg. BlockingQueue::offer)

      Parameters:
      packet - message (see Packet / Call) to handle
      Returns:
      true if the packet can be handled

    • start

      void start(Lookup lookup)
      Start the Root. Controller implementations will ensure that this method can only be invoked once.

      The lookup may contain services that the root may utilise - eg. a shared ScheduledExecutorService. This allows services to be controlled on a per-root basis, rather than relying on the hub lookup.

      Parameters:
      lookup - optional services for the root to use
      Throws:
      IllegalStateException - if the Root has already been started.

    • start

      default void start()
      Convenience method to call start(org.praxislive.core.Lookup) with an empty lookup.

    • shutdown

      void shutdown()
      Signal the Root to be shutdown. This method is intended to be called asynchronously and will return immediately - it will not wait for the Root to actually complete execution.

    • isAlive

      boolean isAlive()
      Query whether the Root is alive - has been started and has not been signalled to shutdown. This method may return false even if the Root is still in the process of termination. If the caller needs to know when the Root has finished termination, use awaitTermination(long, java.util.concurrent.TimeUnit).
      Returns:
      true if started and not signalled to shutdown

    • awaitTermination

      void awaitTermination(long timeout, TimeUnit unit) throws InterruptedException, TimeoutException, ExecutionException
      Wait for the Root to fully terminate, freeing up all resources.
      Parameters:
      timeout - maximum time to wait
      unit - unit of timeout
      Throws:
      InterruptedException - if the current thread is interrupted
      TimeoutException - if the timeout is reached before termination
      ExecutionException - if the termination is the result of an exception