Package org.agrona.concurrent

Class AgentRunner

java.lang.Object
org.agrona.concurrent.AgentRunner
All Implemented Interfaces:
AutoCloseable, Runnable
public class AgentRunner extends Object implements Runnable, AutoCloseable
Agent runner containing an Agent which is run on a Thread.

Note: An instance should only be started once and then discarded, it should not be reused.

  • Field Details

    • TOMBSTONE

      public static final Thread TOMBSTONE
      Indicates that the runner is being closed.

    • RETRY_CLOSE_TIMEOUT_MS

      public static final int RETRY_CLOSE_TIMEOUT_MS
      Default retry timeout for closing.
      See Also:

  • Constructor Details

    • AgentRunner

      public AgentRunner(IdleStrategy idleStrategy, ErrorHandler errorHandler, AtomicCounter errorCounter, Agent agent)
      Create an agent runner and initialise it.
      Parameters:
      idleStrategy - to use for Agent run loop
      errorHandler - to be called if an Throwable is encountered
      errorCounter - to be incremented each time an exception is encountered. This may be null.
      agent - to be run in this thread.

  • Method Details

    • startOnThread

      public static Thread startOnThread(AgentRunner runner)
      Start the given agent runner on a new thread.
      Parameters:
      runner - the agent runner to start.
      Returns:
      the new thread that has been started.

    • startOnThread

      public static Thread startOnThread(AgentRunner runner, ThreadFactory threadFactory)
      Start the given agent runner on a new thread.
      Parameters:
      runner - the agent runner to start.
      threadFactory - the factory to use to create the thread.
      Returns:
      the new thread that has been started.

    • agent

      public Agent agent()
      The Agent which is contained.
      Returns:
      Agent being contained.

    • isClosed

      public boolean isClosed()
      Has the Agent been closed?
      Returns:
      has the Agent been closed?

    • thread

      public Thread thread()
      Get the thread which is running that Agent.

      If null then the runner has not been started. If TOMBSTONE then the runner is being closed.

      Returns:
      the thread running the Agent.

    • run

      public void run()
      Run an Agent.

      This method does not return until the run loop is stopped via close().

      Specified by:
      run in interface Runnable

    • close

      public final void close()
      Stop the running Agent and cleanup.

      This is equivalent to calling close(int, Consumer) using the default RETRY_CLOSE_TIMEOUT_MS value and a null action.

      Specified by:
      close in interface AutoCloseable

    • close

      public final void close(int retryCloseTimeoutMs, Consumer<Thread> closeFailAction)
      Stop the running Agent and cleanup.

      This will wait for the work loop to exit. The close timeout parameter controls how long we should wait before retrying to stop the agent by interrupting the thread. If the calling thread has its interrupt flag set then this method can return early before waiting for the running agent to close.

      An optional action can be invoked whenever we time out while waiting which accepts the agent runner thread as the parameter (e.g. to obtain and log a stack trace from the thread). If the action is null, a message is written to stderr. Please note that a retry close timeout of zero waits indefinitely, in which case the fail action is only called on interrupt.

      Parameters:
      retryCloseTimeoutMs - how long to wait before retrying.
      closeFailAction - function to invoke before retrying after close timeout.