madkit.kernel

## Class Scheduler

- java.lang.Object
- - madkit.kernel.AbstractAgent
  - - madkit.kernel.Agent
    - - madkit.kernel.Scheduler

- All Implemented Interfaces:
    java.lang.Comparable<AbstractAgent>

      public class Scheduler
      extends Agent

  This class defines a generic threaded scheduler agent. It holds a collection of activators. The default state of a scheduler is `Scheduler.SimulationState.PAUSED`. The default delay between two steps is 0 ms (max speed).
  Since:
    MaDKit 2.0
  Version:
    5.2
  Author:
    Fabien Michel
  See Also:
    `Activator`

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static class` | `Scheduler.SimulationState` A simulation state.

    - ### Nested classes/interfaces inherited from class madkit.kernel.AbstractAgent

      `AbstractAgent.ReturnCode, AbstractAgent.State`

  - ### Field Summary

    - ### Fields inherited from class madkit.kernel.AbstractAgent

      `logger`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `Scheduler()` This constructor is equivalent to `Scheduler(Double.MAX_VALUE)`
    `Scheduler(double endTime)` Constructor specifying the time at which the simulation ends.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `addActivator(Activator<? extends AbstractAgent> activator)` Adds an activator to the kernel engine.
    `protected void` | `checkMail(Message m)` Changes my state according to a `SchedulingMessage` and sends a reply to the sender as acknowledgment.
    `void` | `doSimulationStep()` Executes all the activators in the order they have been added, using `Activator.execute(Object...)`, and then increments the global virtual time of this scheduler by one unit.
    `protected void` | `end()` This method corresponds to the last behavior which is called by the MaDKit kernel.
    `int` | `getDelay()` Returns the delay between two simulation steps
    `double` | `getGVT()` Returns the simulation global virtual time.
    `javax.swing.JLabel` | `getGVTLabel()` Returns a label giving the simulation time
    `javax.swing.JMenu` | `getSchedulerMenu()` Returns a menu which could be used in any GUI.
    `javax.swing.JLabel` | `getSchedulerStatusLabel()` Returns a label giving some information on the simulation process
    `javax.swing.JToolBar` | `getSchedulerToolBar()` Returns a toolbar which could be used in any GUI.
    `double` | `getSimulationDuration()`
    `Scheduler.SimulationState` | `getSimulationState()` The state of the simualtion.
    `protected void` | `live()` Scheduler's default behavior.
    `protected void` | `paused()` Runs `checkMail(Message)` every 1000 ms.
    `void` | `removeActivator(Activator<? extends AbstractAgent> activator)` Removes an activator from the kernel engine.
    `void` | `removeAllActivators()` Remove all the activators which have been previously added
    `void` | `setDelay(int delay)` Sets the delay between two simulation steps.
    `void` | `setGVT(double GVT)` Sets the simulation global virtual time.
    `void` | `setSimulationDuration(double endTime)` Sets the simulation time for which the scheduler should end the simulation.
    `protected void` | `setSimulationState(Scheduler.SimulationState newState)` Changes the state of the scheduler
    `void` | `setupFrame(javax.swing.JFrame frame)` Setup the default Scheduler GUI when launched with the default MaDKit GUI mechanism.

    - ### Methods inherited from class madkit.kernel.Agent

      `broadcastMessageWithRoleAndWaitForReplies, getThreadPriority, isDaemon, killAgent, pause, sendMessageAndWaitForReply, sendMessageAndWaitForReply, sendMessageAndWaitForReply, sendMessageAndWaitForReply, sendMessageWithRoleAndWaitForReply, sendMessageWithRoleAndWaitForReply, sendMessageWithRoleAndWaitForReply, sendMessageWithRoleAndWaitForReply, sendReplyAndWaitForReply, sendReplyAndWaitForReply, sendReplyWithRoleAndWaitForReply, sendReplyWithRoleAndWaitForReply, setThreadPriority, waitAnswer, waitAnswer, waitNextMessage, waitNextMessage, waitNextMessage, waitNextMessage`

    - ### Methods inherited from class madkit.kernel.AbstractAgent

      `activate, broadcastMessage, broadcastMessageWithRole, bucketModeCreateGroup, bucketModeRequestRole, checkAgentAddress, compareTo, createGroup, createGroup, createGroup, createGroupIfAbsent, createGroupIfAbsent, createGroupIfAbsent, createGUIOnStartUp, destroyCommunity, destroyGroup, destroyRole, executeThisAgent, executeThisAgent, executeThisAgent, getAgentAddressIn, getAgentsWithRole, getAgentsWithRole, getAgentWithRole, getDistantAgentWithRole, getExistingCommunities, getExistingGroups, getExistingRoles, getKernelAddress, getLogger, getMadkitConfig, getMadkitProperty, getMadkitProperty, getMyGroups, getMyRoles, getName, getNetworkID, getOrganizationSnapShot, getReplyTo, getServerInfo, getSimpleNetworkID, getState, hasGUI, hashCode, hasRole, isAlive, isCommunity, isGroup, isKernelOnline, isMadkitPropertyTrue, isMessageBoxEmpty, isRole, killAgent, launchAgent, launchAgent, launchAgent, launchAgent, launchAgent, launchAgent, launchAgent, launchAgent, launchAgentBucket, launchAgentBucket, launchAgentBucket, launchAgentBucket, launchNode, launchXmlAgents, leaveGroup, leaveRole, nextMessage, nextMessage, nextMessages, proceedEnumMessage, purgeMailbox, receiveMessage, reload, requestRole, requestRole, sendMessage, sendMessage, sendMessageWithRole, sendMessageWithRole, sendReply, sendReplyWithRole, setLogLevel, setMadkitProperty, setMadkitProperty, setName, toString`

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

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

- - ### Constructor Detail

    - #### Scheduler

          public Scheduler()

      This constructor is equivalent to `Scheduler(Double.MAX_VALUE)`

    - #### Scheduler

          public Scheduler(double endTime)

      Constructor specifying the time at which the simulation ends.
      Parameters:
        `endTime` - the GVT at which the simulation will automatically stop

  - ### Method Detail

    - #### getDelay

          public int getDelay()

      Returns the delay between two simulation steps
      Returns:
        the delay between two simulation steps.

    - #### setDelay

          public void setDelay(int delay)

      Sets the delay between two simulation steps. That is the pause time between to call to `doSimulationStep()`. The value is automatically adjusted between 0 and 400.
      Parameters:
        `delay` - the pause between two steps in milliseconds, an integer between 0 and 400: O is max speed.

    - #### getGVT

          public double getGVT()

      Returns the simulation global virtual time.
      Returns:
        the gVT

    - #### setGVT

          public void setGVT(double GVT)

      Sets the simulation global virtual time.
      Parameters:
        `GVT` - the actual simulation time

    - #### setupFrame

          public void setupFrame(javax.swing.JFrame frame)

      Setup the default Scheduler GUI when launched with the default MaDKit GUI mechanism.
      Overrides:
        `setupFrame` in class `AbstractAgent`
      Parameters:
        `frame` - the default frame which has been created by MaDKit for this agent.
      Since:
        MaDKit 5.0.0.8
      See Also:
        `AbstractAgent.setupFrame(javax.swing.JFrame)`

    - #### addActivator

          public void addActivator(Activator<? extends AbstractAgent> activator)

      Adds an activator to the kernel engine. This has to be done to make an activator work properly
      Parameters:
        `activator` - an activator.

    - #### removeActivator

          public void removeActivator(Activator<? extends AbstractAgent> activator)

      Removes an activator from the kernel engine.
      Parameters:
        `activator` - an activator.

    - #### doSimulationStep

          public void doSimulationStep()

      Executes all the activators in the order they have been added, using `Activator.execute(Object...)`, and then increments the global virtual time of this scheduler by one unit. This also automatically calls the multicore mode of the activator if it is set so. This method should be overridden to define customized scheduling policy. So default implementation is :

           @Override
                  public void doSimulationStep() {
                          if (logger != null) {
                                  logger.finer("Doing simulation step " + GVT);
                          }
                          for (final Activator activator : activators) {
                                  if (logger != null)
                                          logger.finer("Activating\n--------> " + activator);
                                  activator.execute();
                          }
                          setGVT(getGVT() + 1);

    - #### end

          protected void end()

      Description copied from class: `AbstractAgent`
      This method corresponds to the last behavior which is called by the MaDKit kernel. This call occurs when a threaded agent normally exits its live method or when the agent is killed. Usually a good place to release taken resources or log what has to be logged. It has to be noted that the kernel automatically takes care of removing the agent from the organizations it is in. However, this cleaning is not logged by the agent. Therefore it could be of interest for the agent to do that itself.

      Here is a typical example:

           @Override
           protected void end()
           {
                  AbstractAgent.ReturnCode returnCode = leaveRole("a community", "a group", "my role");
                  if (returnCode == AbstractAgent.ReturnCode.SUCCESS){
                          if(logger != null)
                                  logger.info("I am leaving the artificial society");
                  }
                  else{
                          if(logger != null)
                                  logger.warning("something wrong when ending, return code is "+returnCode);
                  }
                  if(logger != null)
                          logger.info("I am done");
                  }
           }

      Overrides:
        `end` in class `AbstractAgent`

    - #### getSimulationState

          public Scheduler.SimulationState getSimulationState()

      The state of the simualtion.
      Returns:
        the state in which the simulation is.
      See Also:
        `Scheduler.SimulationState`

    - #### setSimulationState

          protected void setSimulationState(Scheduler.SimulationState newState)

      Changes the state of the scheduler
      Parameters:
        `newState` - the new state

    - #### live

          protected void live()

      Scheduler's default behavior. default code is:

           while (isAlive()) {
                  if (GVT > getSimulationDuration()) {
                          if (logger != null)
                                  logger.info("Quitting: Simulation has reached end time " + getSimulationDuration());
                          return;
                  }
                  pause(getDelay());
                  checkMail(nextMessage());
                  switch (getSimulationState()) {
                  case RUNNING:
                          doSimulationStep();
                          break;
                  case PAUSED:
                          paused();
                          break;
                  case STEP:
                          simulationState = PAUSED;
                          doSimulationStep();
                          break;
                  case SHUTDOWN:
                          return; // shutdown
                  default:
                          getLogger().severe("state not handled " + getSimulationState);
                  }
           }

      Overrides:
        `live` in class `Agent`
      See Also:
        `Agent.live()`

    - #### checkMail

          protected void checkMail(Message m)

      Changes my state according to a `SchedulingMessage` and sends a reply to the sender as acknowledgment.
      Parameters:
        `m` - the received message

    - #### paused

          protected void paused()

      Runs `checkMail(Message)` every 1000 ms.

    - #### removeAllActivators

          public void removeAllActivators()

      Remove all the activators which have been previously added

    - #### setSimulationDuration

          public void setSimulationDuration(double endTime)

      Sets the simulation time for which the scheduler should end the simulation.
      Parameters:
        `endTime` - the end time to set

    - #### getSimulationDuration

          public double getSimulationDuration()

      Returns:
        the simulationDuration

    - #### getSchedulerToolBar

          public javax.swing.JToolBar getSchedulerToolBar()

      Returns a toolbar which could be used in any GUI.
      Returns:
        a toolBar controlling the scheduler's actions

    - #### getSchedulerMenu

          public javax.swing.JMenu getSchedulerMenu()

      Returns a menu which could be used in any GUI.
      Returns:
        a menu controlling the scheduler's actions

    - #### getSchedulerStatusLabel

          public javax.swing.JLabel getSchedulerStatusLabel()

      Returns a label giving some information on the simulation process
      Returns:
        a label giving some information on the simulation process

    - #### getGVTLabel

          public javax.swing.JLabel getGVTLabel()

      Returns a label giving the simulation time
      Returns:
        a label giving the simulation time

Fabien Michel, Olivier Gutknecht, Jacques Ferber - November 18 2014