org.powertac.common
Class TimeService

java.lang.Object
  org.powertac.common.TimeService

@Scope(value="singleton")
@Service
public class TimeService
extends Object

This is the simulation time-keeper and event queue. Here's how it works:

• You create it with four parameters: (base, start, rate, modulo), defined as
  • base is the start time of the simulation scenario. So if we are simulating a period in the summer of 2007, base might be 2007-06-21-12:00.
  • start is the start time of the simulation run.
  • rate is the time-compression ratio for the simulation. So if we are running one-hour timeslots every 5 seconds, the rate would be 720.
  • modulo controls the values of simulation time values reported. If we are running one-hour timeslots, then the modulo should be one hour, expressed in milliseconds. If we are running one-hour timeslots but want to update time every 30 minutes of simulated time, then the modulo would be 30*60*1000. Note that this will not work correctly unless the calls to updateTime() are made at modulo/rate intervals. Also note that the reported time is computed as rawTime - rawTime % modulo, which means it will never be ahead of the raw simulation time.
• Some process periodically calls updateTime(), at least once every simulated hour. This sets the currentTime property to the correct scenario time as
  currentTime = base + (systemTime - start) * rate
  and runs any simulation actions that are due.
• If you want something to happen sometime in the future, you add an action by calling addAction(time, action). Assuming time is not in the past, then the action (a closure with a single argument, the current time) is added to a time-ordered queue, and will be run when its time arrives.

Note that all times are absolute times represented as UTC; timezone offset is 0, and there is no "daylight-saving" time. If we want to represent the effects of DST, we'll have to have our customers wake up earlier in the summertime.

Author:

John Collins

Field Summary

static long	DAY
static long	HOUR
static long	MINUTE
static long	SECOND
static long	WEEK

Constructor Summary

TimeService()
Default constructor.

TimeService(long base, long start, long rate, long modulo)
Handy constructor for testing

Method Summary

void	addAction(org.joda.time.Instant time, TimedAction act) Adds an action to the simulation queue, to be triggered at the specified time.
long	getBase()
org.joda.time.Instant	getBaseInstant()
org.joda.time.DateTime	getCurrentDateTime()
org.joda.time.Instant	getCurrentTime() Returns the current time as an Instant
int	getHourOfDay() Returns the current hour-of-day
long	getModulo()
long	getRate()
long	getStart()
void	init() Sets current time to modulo before base time.
void	setBase(long value) Deprecated. use setClockParameters instead
void	setClockParameters(long base, long rate, long modulo) Sets base, rate, and modulo clock parameters with a single call.
void	setClockParameters(Map<String,Long> params) Sets base, rate, and modulo parameters from a map, which is wrapped in a Configuration to allow for conversions and default values.
protected void	setCurrentTime(org.joda.time.base.AbstractDateTime time) Sets current time to a specific value.
void	setCurrentTime(org.joda.time.Instant time) Sets current time to a specific value.
void	setModulo(long value) Deprecated. use setClockParameters instead
void	setRate(long value) Deprecated. use setClockParameters instead
void	setStart(long start)
org.joda.time.Instant	truncateInstant(org.joda.time.Instant time, long mod) Returns the most recent Instant at which time % modulo was zero
void	updateTime() Updates simulation time when called as specified by clock parameters, then runs any actions that may be due.

Methods inherited from class java.lang.Object

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

Field Detail

SECOND

public static final long SECOND

See Also:

Constant Field Values

MINUTE

public static final long MINUTE

See Also:

Constant Field Values

HOUR

public static final long HOUR

See Also:

Constant Field Values

DAY

public static final long DAY

See Also:

Constant Field Values

WEEK

public static final long WEEK

See Also:

Constant Field Values

Constructor Detail

TimeService

public TimeService()

Default constructor. You need to set base, rate, start, and modulo before using it.

TimeService

public TimeService(long base,
                   long start,
                   long rate,
                   long modulo)

Handy constructor for testing

Method Detail

init

public void init()

Sets current time to modulo before base time. This allows scheduling of actions to take place on the first tick, which should be at the base time. Call this after setting clock parameters.

updateTime

public void updateTime()

Updates simulation time when called as specified by clock parameters, then runs any actions that may be due.

truncateInstant

public org.joda.time.Instant truncateInstant(org.joda.time.Instant time,
                                             long mod)

Returns the most recent Instant at which time % modulo was zero

setClockParameters

public void setClockParameters(long base,
                               long rate,
                               long modulo)

Sets base, rate, and modulo clock parameters with a single call. We do not set start at this point, because it is changed whenever the clock is paused and therefore needs to be treated separately.

setClockParameters

public void setClockParameters(Map<String,Long> params)

Sets base, rate, and modulo parameters from a map, which is wrapped in a Configuration to allow for conversions and default values. The map must contain entries named "base", "rate", and "modulo". We also init the clock here, because we have all the parameters.

getBase

public long getBase()

getBaseInstant

public org.joda.time.Instant getBaseInstant()

setBase

@Deprecated
public void setBase(long value)

Deprecated. use setClockParameters instead

getStart

public long getStart()

setStart

public void setStart(long start)

getRate

public long getRate()

setRate

@Deprecated
public void setRate(long value)

Deprecated. use setClockParameters instead

getModulo

public long getModulo()

setModulo

@Deprecated
public void setModulo(long value)

Deprecated. use setClockParameters instead

getCurrentTime

public org.joda.time.Instant getCurrentTime()

Returns the current time as an Instant

getCurrentDateTime

public org.joda.time.DateTime getCurrentDateTime()

getHourOfDay

public int getHourOfDay()

Returns the current hour-of-day

setCurrentTime

public void setCurrentTime(org.joda.time.Instant time)

Sets current time to a specific value. Intended for testing purposes only.

setCurrentTime

protected void setCurrentTime(org.joda.time.base.AbstractDateTime time)

Sets current time to a specific value. Intended for testing purposes only.

addAction

public void addAction(org.joda.time.Instant time,
                      TimedAction act)

Adds an action to the simulation queue, to be triggered at the specified time.