Class myphysicslab.lab.util.Clock

Provided By
All Implemented Interfaces

A clock that advances along with real time and can execute tasks at appointed times. There are commands to pause, resume, and single-step the Clock, as well as set its time and speed relative to system time. Clock has a list of myphysicslab.lab.util.ClockTasks which it causes to be executed at the times specified by the ClockTasks. Clock has a parallel real time clock for measuring performance.

Clock time is used with a Simulation to know how much to advance the simulation. This is done by a client object such as By matching Clock time, operations on Clock like pause, single-step, setting time rate, etc. will also therefore affect the display of the Simulation.

Note that while a unit of simulation time can be interpreted to mean anything from a millisecond to a millenium, we use the Clock to advance the Simulation time along with real time as though each unit of time is equal to one second of real time.

Types of Time

There are several types of time considered here: system time, clock time, simulation time, and real time. All of these are measured in seconds, though simulation time might have a different meaning – see About Units Of Measurement. Since simulation time follows clock time, you should think of clock time being in the same units as simulation time.

  • System Time is given by UtilityCore.getSystemTime(). System time is the basis of the other time measurements. For example, clock time and real time each have a 'system start time' by which they are measured. System time is always running.

  • Clock Time is given by Clock.getTime(). Clock time advances at the current time-rate (multiple of system time). Clock time can be modified directly by calling Clock.setTime(). Clock time can be paused or resumed.

  • Simulation Time is given by Simulation.getTime(). Simulation time is advanced by the client, usually to keep up with clock time. When performance problems occur, the clock time is retarded via Clock.setTime() to match the current simulation time.

  • Real Time is given by Clock.getRealTime(). Closely related to clock time, real time is used to measure performance: how much the simulation time (usually same as clock time) has slipped behind real time because the simulation couldn't compute quickly enough. Real time usually mirrors clock time – they are paused or resumed together and have the same time rate relative to system time – but real time is not affected by Clock.setTime(). When performance problems happen the usual result is that clock time is retarded to match simulation time by setting clock time to an earlier value. In this case, real time is unaffected and will be ahead of clock time by the amount of time lost to performance problems.


A ClockTask contains a function which is to be executed at a specific time. ClockTasks are scheduled as a side effect of Clock methods such as setTime(), resume(), addTask(). ClockTasks are cancelled as a side effect of Clock methods such as pause(), removeTask().

Step Mode

The #step method puts the Clock into a special step mode. Clients should check for this step mode by calling #isStepping. Step mode being true means that

  • clock time has advanced even though the clock is paused*. The client should update the simulation to match the new clock time, and then call #clearStepMode to indicate that it has advanced the simulation.

Parameters and Events

As a Subject, Clock broadcasts to its Observers these SubjectEvents and Parameters:

new Clock( opt_name )


name of this Clock.

Instance Methods

Static Properties

Type Definitions