org.powertac.server

Class SimulationClockControl

java.lang.Object

org.powertac.server.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

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	SimulationClockControl.Status

Method Summary

Modifier and Type	Method and Description
void	checkClockDrift() Compares sim time to sys time, updates start if it's off too much
void	complete() Indicates that the simulator has completed its work on the current timeslot.
static SimulationClockControl	getInstance() Returns the instance, which of course will be null if the singleton is not yet initialized.
static void	initialize(CompetitionControlService competitionControl, TimeService timeService) Creates the instance and sets the reference to the timeService.
void	releasePause() Releases an externally-requested pause.
void	requestPause() Serves an external pause request.
void	scheduleTick() Schedules the next tick.
void	setStart(long start) Sets the sim clock start time, which in turn gets propagated to the timeService.
void	stop() Stops the clock.
void	waitForTick(int n) Blocks the caller until the next tick.
void	waitUntilStop()

Methods inherited from class java.lang.Object

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

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.

Returns:

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.