madkit.kernel

## Class Activator<A extends AbstractAgent>

- java.lang.Object
- - madkit.kernel.Activator<A>

- Direct Known Subclasses:
    GenericBehaviorActivator

      public abstract class Activator<A extends AbstractAgent>
      extends Object

  This class defines a tool for scheduling mechanism. An activator is configured according to a community, a group and a role. It could be used to activate a group of agents on a particular behavior (a method of the agent's class) Subclasses should override `execute(List, Object...)` for defining how a sequential execution of a list of agents take place. By default, this list corresponds to all the agents in a single core mode or to partial views of the entire list when the multicore mode is used. The multicore mode is set to `false` by default.
  Since:
    MaDKit 2.0
  Version:
    5.0
  Author:
    Fabien Michel, Olivier Gutknecht
  See Also:
    `Scheduler`, `GenericBehaviorActivator`

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `Activator(String community, String group, String role)` Builds a new Activator on the given CGR location of the artificial society with multicore mode set to `false`.

  - ### Method Summary

    All Methods Static Methods Instance Methods Abstract Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `protected void` | `adding(A agent)` This method is automatically called when an agent joins the corresponding group and role.
    `protected void` | `adding(List<A> agents)` Called when a list of agents joins the corresponding group and role.
    `void` | `allAgentsLeaveRole()` Makes all the agents leave the corresponding role at once.
    `abstract void` | `execute(List<A> agentsList, Object... args)` This should define what has to be done on the agents for a simulation step.
    `void` | `execute(Object... args)` Call #execute(List agentsList) on all the agents, i.e. using `Overlooker.getCurrentAgentsList()`.
    `void` | `executeBehaviorOf(AbstractAgent agent, String behaviorName, Object... args)` Executes a specific method on a targeted agent.
    `static <T> Method` | `findMethodOn(Class<T> agentClass, String methodName, Class<?>... parameterTypes)` Returns the agent's method named `methodName` considering a given agentClass.
    `static <T> Method` | `findMethodOnFromArgsSample(Class<T> agentClass, String methodName, Object... argsSample)` Returns the agent's method named `methodName` considering a given agentClass and a sample of the arguments which could be passed to it.
    `String` | `getCommunity()` Gets the community to which this activator/probe is binded to.
    `List<A>` | `getCurrentAgentsList()` Returns a snapshot at moment t of the agents handling the group/role couple
    `String` | `getGroup()` Gets the group to which this activator/probe is binded to.
    `static ExecutorService` | `getMadkitServiceExecutor()` Returns the MDK ExecutorService that executes task in parallel
    `Integer` | `getPriority()` The priority of this activator when conflicting with another Activator.
    `String` | `getRole()` Gets the role to which this activator/probe is binded to.
    `List<A>` | `getShuffledList()` Returns a ListIterator over the agents which is shuffled
    `Scheduler.SimulationTime` | `getSimulationTime()` Get the `Scheduler.SimulationTime` associated with the simulation
    `void` | `initialize()` Called by the MaDKit kernel when the Activator or Probe is first added.
    `boolean` | `isMulticoreModeOn()`
    `void` | `killAgents()` Kills all the agents which are monitored.
    `protected void` | `multicoreExecute(Object... args)` Executes the behavior on all the agents in a concurrent way, using several processor cores if available.
    `int` | `nbOfParallelTasks()` Returns the number of tasks that will be created by this activator in order to benefit from multicore platforms.
    `protected void` | `removing(A agent)` This method is automatically called when an agent leaves the corresponding group and role.
    `protected void` | `removing(List<A> agents)` This method is automatically called when a list of agents has leaved the corresponding group and role.
    `int` | `size()` Returns the number of the agents handling the group/role couple
    `String` | `toString()` returns a string containing the CGR location and the number of monitored agents.
    `void` | `useMulticore(int nbOfParallelTasks)` Sets the number of tasks which will be used on a multicore architecture.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

- - ### Constructor Detail

    - #### Activator

          public Activator(String community,
                           String group,
                           String role)

      Builds a new Activator on the given CGR location of the artificial society with multicore mode set to `false`. This has the same effect as `Activator(community, group, role, false)`.
      Parameters:
        `community` -
        `group` -
        `role` -
      See Also:
        `Scheduler`

  - ### Method Detail

    - #### getPriority

          public Integer getPriority()

      The priority of this activator when conflicting with another Activator. A lesser priority means that the activator will be triggered first. When the activator's priority is not set, a default priority is defined using the order in which the activators are added to the simulation engine using `Scheduler.addActivator(Activator)`, that is the first activator has priority 0, the second has 1, and so on. Setting the activator's priority should be done using `Scheduler.setActivatorPriority(Activator, int)` so that the scheduler can maintain the ordering coherence of the activators list. By default, when two activators have the same priority, the order of activation is undefined.
      Returns:
        the priority of this scheduler.

    - #### execute

          public void execute(Object... args)

      Call #execute(List agentsList) on all the agents, i.e. using `Overlooker.getCurrentAgentsList()`. By default, this is automatically called by the default scheduler's loop once the activator is added.
      Parameters:
        `args` - arguments that could be used by the scheduler to pass information to this activator for an activation
      See Also:
        `Scheduler.doSimulationStep()`

    - #### executeBehaviorOf

          public void executeBehaviorOf(AbstractAgent agent,
                                        String behaviorName,
                                        Object... args)

      Executes a specific method on a targeted agent.
      Parameters:
        `agent` - the targeted agent.
        `behaviorName` - the name of a method belonging to the agents (even private or inherited ones)
        `args` - parameters to be passed for the invocation

    - #### adding

          protected void adding(A agent)

      This method is automatically called when an agent joins the corresponding group and role. This method is empty by default. Override this method when you want to do some initialization when an agent enters the group/role.
      Parameters:
        `agent` - which has been added to this group/role

    - #### execute

          public abstract void execute(List<A> agentsList,
                                       Object... args)

      This should define what has to be done on the agents for a simulation step. By default, this calls is automatically made using a list containing all the agents for this CGR, i.e. `Overlooker.getCurrentAgentsList()` is used by default. When the multicore mode is on, the list is only a portion and this method will automatically be distributed over several threads. So, one has to take care about how the activator's fields are used here to avoid a `ConcurrentModificationException` for instance.
      Parameters:
        `agentsList` -

    - #### multicoreExecute

          protected void multicoreExecute(Object... args)

      Executes the behavior on all the agents in a concurrent way, using several processor cores if available. This call decomposes the execution of the activator in `nbOfParallelTasks()` tasks so that there are independently performed by the available core of the host.

      Default implementation Beware that using this call will produce different outputs for each run unless a concurrent simulation model is used. That is to say, a model supporting concurrent phases in the simulation execution such as the IRM4S model

    - #### toString

          public String toString()

      returns a string containing the CGR location and the number of monitored agents.
      Returns:
        a string representation of this tool.

    - #### isMulticoreModeOn

          public boolean isMulticoreModeOn()

      Returns:
        `true` if the multicore mode is on. I.e. `nbOfParallelTasks()` > 1. This method could be used by the default behavior of scheduler agents as they test in which mode each activator has to be used.

    - #### useMulticore

          public void useMulticore(int nbOfParallelTasks)

      Sets the number of tasks which will be used on a multicore architecture. If set to a number greater than 1, the scheduler will automatically use `multicoreExecute(Object...)` on this activator when `execute(Object...)` is called. If set to 1, the agents are sequentially activated. Beware that this is the only way to do exact replication of simulations, unless you have clear specifications for your model, see `multicoreExecute(Object...)`.
      Parameters:
        `nbOfParallelTasks` - the number of simultaneous tasks that this activator will use to make a step. Default is 1 upon creation, so that `isMulticoreModeOn()` returns `false`.

    - #### nbOfParallelTasks

          public int nbOfParallelTasks()

      Returns the number of tasks that will be created by this activator in order to benefit from multicore platforms.
      Returns:
        the number of tasks that will be created.

    - #### getMadkitServiceExecutor

          public static ExecutorService getMadkitServiceExecutor()

      Returns the MDK ExecutorService that executes task in parallel
      Returns:
        an ExecutorService running task in parallel

    - #### findMethodOn

          public static <T> Method findMethodOn(Class<T> agentClass,
                                                String methodName,
                                                Class<?>... parameterTypes)
                                         throws NoSuchMethodException

      Returns the agent's method named `methodName` considering a given agentClass. This also works for private and inherited methods.
      Parameters:
        `agentClass` - the class wherein the search has to be made
        `methodName` - the name of the method
        `parameterTypes` - the parameter types of the targeted method
      Returns:
        the agent's method named `methodName`
      Throws:
        `NoSuchMethodException`

    - #### findMethodOnFromArgsSample

          public static <T> Method findMethodOnFromArgsSample(Class<T> agentClass,
                                                              String methodName,
                                                              Object... argsSample)
                                                       throws NoSuchMethodException

      Returns the agent's method named `methodName` considering a given agentClass and a sample of the arguments which could be passed to it. The purpose of this method is restricted to a limited number of use cases since `findMethodOn(Class, String, Class...)` should be preferred if the exact signature of the searched method is known. A typical use case of this method is when the only information available is the arguments which are passed, for instance when overriding the `execute(List, Object...)` method and the like in `Activator` subclasses. This also works for private and inherited methods.
      Parameters:
        `agentClass` - the class wherein the search has to be made
        `methodName` - the name of the method
        `argsSample` - a sample of the args which can be passed to the method
      Returns:
        the agent's method named `methodName`
      Throws:
        `NoSuchMethodException` - if a matching method cannot be found

    - #### getSimulationTime

          public Scheduler.SimulationTime getSimulationTime()

      Get the `Scheduler.SimulationTime` associated with the simulation
      Returns:
        the simulationTime associated with the simulation

    - #### getCommunity

          public String getCommunity()

      Gets the community to which this activator/probe is binded to.
      Returns:
        a string representing the community's name

    - #### getGroup

          public String getGroup()

      Gets the group to which this activator/probe is binded to.
      Returns:
        a string representing the group's name

    - #### getRole

          public String getRole()

      Gets the role to which this activator/probe is binded to.
      Returns:
        a string representing the role's name

    - #### initialize

          public void initialize()

      Called by the MaDKit kernel when the Activator or Probe is first added. Default behavior is: `adding(getCurrentAgentsList());`

    - #### adding

          protected void adding(List<A> agents)

      Called when a list of agents joins the corresponding group and role. This method is automatically called by the MaDKit kernel when agents enter a role due to the use of `AbstractAgent.launchAgentBucket(String, int, String...)`. Override this method when you want to do some initialization on the agents that enter the group/role. Default implementation is:

           protected void adding(final List<A> agents) {
               for (A agent : agents) {
                  adding(agent);
               }
           }

      Parameters:
        `agents` - the list of agents which have been added to this group/role at once.

    - #### removing

          protected void removing(List<A> agents)

      This method is automatically called when a list of agents has leaved the corresponding group and role. This method is empty by default. Override this method when you want to do some initialization on the agents that enter the group/role. Default implementation is:

           protected void removing(final List<A> agents) {
               for (A agent : agents) {
                  removing(agent);
               }
           }

      Parameters:
        `agents` - the list of agents which have been removed from this group/role

    - #### removing

          protected void removing(A agent)

      This method is automatically called when an agent leaves the corresponding group and role. This method is empty by default. Override this method when you want to do some work when an agent leaves the group/role. Note that the role is still handled by the agent when invoked.
      Parameters:
        `agent` - the agent which is being removed from this group/role

    - #### size

          public int size()

      Returns the number of the agents handling the group/role couple
      Returns:
        the number of the agents that handle the group/role couple

    - #### getCurrentAgentsList

          public List<A> getCurrentAgentsList()

      Returns a snapshot at moment t of the agents handling the group/role couple
      Returns:
        a list view (a snapshot at moment t) of the agents that handle the group/role couple (in proper sequence)
      Since:
        MaDKit 3.0

    - #### getShuffledList

          public List<A> getShuffledList()

      Returns a ListIterator over the agents which is shuffled
      Returns:
        a ListIterator which has been previously shuffled
      Since:
        MaDKit 3.0

    - #### killAgents

          public void killAgents()

      Kills all the agents which are monitored.

    - #### allAgentsLeaveRole

          public void allAgentsLeaveRole()

      Makes all the agents leave the corresponding role at once.

Fabien Michel, Olivier Gutknecht, Jacques Ferber - February 17 2020