Package org.powertac.server

Class SimulationClockControl

  • public class SimulationClockControl
extends Object
    Timer-based clock management for the Power TAC simulator. This is a singleton class, but it must be initialized with a reference to the timeService in order to do its job. Therefore, it is an error to attempt to retrieve the instance before initialization.

    The basic design for this scheme is given at https://github.com/powertac/powertac-server/wiki/Time-management. The goal is to produce a tick by calling timeService.updateTime() every n seconds, where n is 3600/timeService.rate. So if timeService.rate is 360, this would be a tick every 10 seconds. Current simulation time is given by the formula time = rate * (systemTime - start) + base where start, base, and rate are simulation parameters.

    We assume that the simulator is a single thread, although it may control other threads. That thread waits for the next tick, then does some work. Ideally, that work will be completed in fewer than n seconds, but occasionally it may take longer. Since the broker needs to keep track of time on its own, it needs to know when this happens, and must be informed of the updated start time so that it can compute a simulation time that agrees with the server. In addition, a broker might want to pause the clock in order to allow a user to fill out a dialog or otherwise interact with a user. Given an appropriate set of messages, this event could be handled in much the same way as a server timeslot overrun.

    Author:
    John Collins

    • Method Detail

      • initialize

        public static void initialize​(CompetitionControlService competitionControl,
                              TimeService timeService)
        Creates the instance and sets the reference to the timeService.

      • getInstance

        public static SimulationClockControl getInstance()
        Returns the instance, which of course will be null if the singleton is not yet initialized.

      • setStart

        public void setStart​(long start)
        Sets the sim clock start time, which in turn gets propagated to the timeService.

      • scheduleTick

        public void scheduleTick()
        Schedules the next tick. The interval between now and the next tick is determined by comparing the current system time with what the time should be on the next tick.

      • complete

        public void complete()
        Indicates that the simulator has completed its work on the current timeslot. If the sim was delayed, then resume it. On the last tick, client must call stop() rather than complete().

      • stop

        public void stop()
        Stops the clock. Call this method when processing on the last tick is finished.

      • waitUntilStop

        public void waitUntilStop()

      • waitForTick

        public void waitForTick​(int n)
        Blocks the caller until the next tick.

      • checkClockDrift

        public void checkClockDrift()
        Compares sim time to sys time, updates start if it's off too much

      • requestPause

        public void requestPause()
        Serves an external pause request.

      • releasePause

        public void releasePause()
        Releases an externally-requested pause.