Class BasicHubBalancer

All Implemented Interfaces:
CondObserver<Condition,Actor>, NamedObjectOps

public class BasicHubBalancer extends HubBalancer
Basic hub balancer class. This class provides a simple implementation of a hub balancer in which additional workers are scheduled based on the fraction of hubs that are in the hub balancer's user domain and that (1) have bicycles in their overflow areas, (2) have more bicycles in their preferred areas than the value provided by an upper trigger, or (3) have fewer bicycles in their preferred areas than the value provided by a lower trigger. When this fraction is larger than a threshold, an additional worker is scheduled from each storage hub in the hub balancer's system domain. In addition, a timer is started (the interval is called the quiet period and is configurable). Additional workers will not be scheduled until this timer expires.

Subclasses that change the behavior of this class only by overriding HubBalancer.getHubSorter(HubWorker.Mode,StorageHub,Hub[]) are relatively simple extensions of this class. For more complex changes, one will want to override startAdditionalWorkers() as well, in which case it might be better to create a subclass of HubBalancer itself.

  • Constructor Details

    • BasicHubBalancer

      public BasicHubBalancer(DramaSimulation sim, String name, boolean intern)
      Constructor.
      Parameters:
      sim - the simulation
      name - the name of this object
      intern - true if this object should be interned in the simulation's name table; false otherwise
  • Method Details

    • setQuietPeriod

      public void setQuietPeriod(double value)
      Set the quiet period. If additional workers are scheduled at some simulation time t, the quiet period δ indicates that no more workers should be scheduled until the simulation time reaches t + δ.
      Parameters:
      value - the quiet period in seconds
    • getQuietPeriod

      public long getQuietPeriod()
      Get the quiet period. If additional workers are scheduled at some simulation time t, the quiet period δ indicates that no more workers should be scheduled until the simulation time reaches t + δ.
      Returns:
      the quite period in units of simulation ticks
    • setThreshold

      public void setThreshold(double value)
      Set the fraction of the number of hubs beyond which a worker may be scheduled. If the fraction of the number of hubs in the sets returned by the methods HubBalancer.getUnderSet(), HubBalancer.getOverSet(), or HubBalancer.getOverflowSet(), when compared to the total number of hubs, exceeds the threshold, one or more worker may be scheduled.
      Parameters:
      value - the value of the threshold, which must be in the range [0, 1].
    • getThreshold

      public double getThreshold()
      Get the fraction of the number of hubs beyond which a worker may be scheduled. If the fraction of the number of hubs in the sets returned by the methods HubBalancer.getUnderSet(), HubBalancer.getOverSet(), or HubBalancer.getOverflowSet(), when compared to the total number of hubs, exceeds the threshold, one or more worker may be scheduled.
      Returns:
      the current value of the threshold
      See Also:
    • getHubSorter

      public HubWorker.HubSorter getHubSorter(HubWorker.Mode mode, StorageHub shub, Hub[] hubs)
      Description copied from class: HubBalancer
      Get a hub sorter.
      Specified by:
      getHubSorter in class HubBalancer
      Parameters:
      mode - the worker mode for this hub sorter
      shub - the storage hub used to obtain a worker.
      hubs - a list of hubs to sort.
      Returns:
      a hub sorter.
      See Also:
    • startAdditionalWorkers

      protected void startAdditionalWorkers()
      Start additional works on an as-needed basis. This method may be called in response to a condition change. When a subclass implements this method, it is the responsibility of the subclass to determine the number of workers that should be used. This number may be zero. The class BasicHubBalancer, for example, uses an implementation where there is a threshold for the number of hubs that can use an extra worker and a quiet period that prevents a large number of workers from being scheduled at once.

      This method uses a "quiet period" to prevent multiple workers from responding to the same event. It also uses a threshold that looks at the ratio of three counts to the total number of hubs for this hub balancer. These counts are:

      • the number of hubs for which the number of bicycles stored the preferred area exceeds the upper limit.
      • the number of hubs for which the number of bicycles stored the preferred area is below the lower limit.
      • the number of hubs with bicycles in their overflow areas.
      For an additional worker to be scheduled, one of these counts must exceed the threshold multiplied by the total number of hubs for this hub balancer.
      Specified by:
      startAdditionalWorkers in class HubBalancer
    • printConfiguration

      public void printConfiguration(String iPrefix, String prefix, boolean printName, PrintWriter out)
      Print the configuration for an instance of HubBalancer. The documentation for method SimObject.printConfiguration(String,String,boolean,java.io.PrintWriter) contains a description of how this method is used and how to override it. The method GenericActor.printConfiguration(String,String,boolean,java.io.PrintWriter) describes the data that will be printed for the superclass of this class. The data that will be printed when this method is called are the following.

      For class HubBalancer:

      • (No data associated with the HubBalancer class is printed.)
      Defined for class BasicHubBalancer:
      • the quiet period in seconds.
      • the threshold (the fraction of the number of hubs beyond which a worker may be scheduled).
      Overrides:
      printConfiguration in class HubBalancer
      Parameters:
      iPrefix - the prefix to use for an initial line when printName is true with null treated as an empty string
      prefix - a prefix string (typically whitespace) to put at the start of each line other than the initial line that is printed when printName is true
      printName - requests printing the name of an object
      out - the output print writer
    • printState

      public void printState(String iPrefix, String prefix, boolean printName, PrintWriter out)
      Print the state for an instance of HubBalancer. The documentation for method SimObject.printState(String,String,boolean,java.io.PrintWriter) contains a description of how this method is used and how to override it. The method GenericSimObject.printState(String,String,boolean,java.io.PrintWriter) describes the data that will be printed for the superclass of this class. The data that will be printed when this method is called are the following.

      For class HubBalancer:

      • the over-trigger set (the hubs whose bicycle count is larger than its upper-trigger value).
      • the under-trigger set (the hubs whose bicycle count is below its under-trigger value).
      • the overflow set (the hubs that have bicycles in their overflow areas).
      Defined for class BasicHubBalancer:
      • parameters set as the simulation starts:
        • initial bicycle count.
        • nominal bicycle count.
        • the number of hubs.
      Overrides:
      printState in class HubBalancer
      Parameters:
      iPrefix - the prefix to use for an initial line when printName is true with null treated as an empty string
      prefix - a prefix string (typically whitespace) to put at the start of each line other than the initial line that is printed when printName is true
      printName - requests printing the name of an object
      out - the output print writer
    • clone

      protected Object clone() throws CloneNotSupportedException
      Overrides:
      clone in class Object
      Throws:
      CloneNotSupportedException
    • isInterned

      public boolean isInterned()
      Specified by:
      isInterned in interface NamedObjectOps
    • getObjectNamer

      protected Simulation getObjectNamer()
    • getName

      public final String getName()
      Specified by:
      getName in interface NamedObjectOps
    • canDelete

      public boolean canDelete()
      Specified by:
      canDelete in interface NamedObjectOps
    • delete

      public final boolean delete()
      Specified by:
      delete in interface NamedObjectOps
    • isDeleted

      public final boolean isDeleted()
      Specified by:
      isDeleted in interface NamedObjectOps
    • deletePending

      public final boolean deletePending()
      Specified by:
      deletePending in interface NamedObjectOps