Package org.agrona.concurrent

Class DynamicCompositeAgent

java.lang.Object
org.agrona.concurrent.DynamicCompositeAgent
All Implemented Interfaces:
Agent
public class DynamicCompositeAgent extends Object implements Agent
Group several Agents into one composite, so they can be scheduled as a unit.

Agents can be dynamically added and removed.

Note: This class is threadsafe for add and remove.

  • Constructor Details

    • DynamicCompositeAgent

      public DynamicCompositeAgent(String roleName)
      Construct a new composite that has no Agents to begin with.
      Parameters:
      roleName - to be given for Agent.roleName().

    • DynamicCompositeAgent

      public DynamicCompositeAgent(String roleName, List<? extends Agent> agents)
      Construct a new composite with a given list Agents to begin with.
      Parameters:
      roleName - to be given for Agent.roleName().
      agents - the parts of this composite, at least one agent and no null agents allowed.
      Throws:
      NullPointerException - if the array or any element is null.

    • DynamicCompositeAgent

      public DynamicCompositeAgent(String roleName, Agent... agents)
      Construct a new composite with a given list Agents to begin with.
      Parameters:
      roleName - to be given for Agent.roleName().
      agents - the parts of this composite, at least one agent and no null agents allowed.
      Throws:
      NullPointerException - if the array or any element is null.

  • Method Details

    • status

      public DynamicCompositeAgent.Status status()
      Get the DynamicCompositeAgent.Status for the Agent.
      Returns:
      the DynamicCompositeAgent.Status for the Agent.

    • onStart

      public void onStart()
      To be overridden by Agents that need to do resource init on start.

      This method will be called by the agent thread once on start.

      Note that one agent throwing an exception on start may result in other agents not being started.

      Specified by:
      onStart in interface Agent

    • doWork

      public int doWork() throws Exception
      An agent should implement this method to do its work.

      The return value is used for implementing a backoff strategy that can be employed when no work is currently available for the agent to process.

      If the Agent wished to terminate and close then a AgentTerminationException can be thrown.

      Specified by:
      doWork in interface Agent
      Returns:
      0 to indicate no work was currently available, a positive value otherwise.
      Throws:
      Exception - if an error has occurred

    • onClose

      public void onClose()
      To be overridden by Agents that need to do resource cleanup on close.

      This method will be called after the agent thread has terminated or if the agent is closed before it runs.

      Note that one agent throwing an exception on close will not prevent other agents from being closed.

      Specified by:
      onClose in interface Agent
      Throws:
      RuntimeException - if any sub-agent throws an exception onClose. The agents exceptions are collected as suppressed exceptions in the thrown exception.

    • roleName

      public String roleName()
      Get the name of this agent's role.
      Specified by:
      roleName in interface Agent
      Returns:
      the name of this agent's role.

    • tryAdd

      public boolean tryAdd(Agent agent)
      Try and add a new Agent to the composite. This method does not block and will return false if another concurrent attempt to add is in progress.

      The agent will be added during the next invocation of doWork() if this operation is successful. If the Agent.onStart() method throws an exception then it will not be added and Agent.onClose() will be called.

      Parameters:
      agent - to be added to the composite.
      Returns:
      true is a successful add request is pending otherwise false if another concurrent add request is in progress.
      See Also:

    • hasAddAgentCompleted

      public boolean hasAddAgentCompleted()
      Has the last successful tryAdd(Agent) operation been processed in the doWork() cycle?
      Returns:
      the last successful tryAdd(Agent) operation been processed in the doWork() cycle?
      See Also:

    • tryRemove

      public boolean tryRemove(Agent agent)
      Try and remove an Agent from the composite. The agent is removed during the next doWork() duty cycle if this operation is successful. This method does not block and will return false if another concurrent attempt to remove is in progress.

      The Agent is removed by identity. Only the first found is removed.

      Parameters:
      agent - to be removed.
      Returns:
      true is a successful remove request is pending otherwise false if another concurrent remove request is in progress.
      See Also:

    • hasRemoveAgentCompleted

      public boolean hasRemoveAgentCompleted()
      Has the last tryRemove(Agent) operation been processed in the doWork() cycle?
      Returns:
      the last tryRemove(Agent) operation been processed in the doWork() cycle?
      See Also: