User Guide: C++ : Time

2. Simulation Time

Time is an important concept in any performance model. CSIM maintains a simulation clock whose value is the current time in the model. This simulation time is distinctly different than the cpu time used in executing the model or the "real world" time of the person running the model. Simulation time starts at zero and then advances unevenly, jumping between times at which the state of the model changes. It is impossible to make time move backwards during a simulation run.

The simulation clock is implemented as a double precision floating point variable in CSIM. For most models there is no need to worry that the simulation clock will overflow or that round-off error will impact the accuracy of the clock.

The simulation clock is used extensively within CSIM to schedule events and to update performance statistics. CSIM processes may retrieve the current time for their own purposes and may indirectly cause time to advance by performing certain operations.

2.1 Choosing a Time Unit

The CSIM simulation clock has no predefined unit of time. It is the responsibility of the modeler to choose an appropriate time unit and to consistently specify all amounts of time in that unit. All performance statistics reported by CSIM should also be interpreted as being in that chosen time unit.

A good time unit might be close to the granularity of the smallest time periods in the model. For example, if the smallest time periods being modeled are on the order of tens of milliseconds, an appropriate time unit might be either milliseconds or seconds. Using microseconds or minutes as the time unit would produce performance statistics that are either very large or very small numbers.

Most numbers appearing in CSIM performance reports are printed with up to six digits to the left of the decimal point and six digits to the right of the decimal point. A time unit should be chosen to avoid numbers so large that they overflow their fields or so small that interesting digits are not visible.

2.2 Retrieving the Current Time

There are two equivalent ways to retrieve the current value of the simulation clock. One is to call the simtime function.

Prototype: double simtime(void)
Example: x = simtime();

The other is to reference the variable clock

Example: x = clock; or
x = csim_clock;

2.3 Delaying for an Amount of Time

A CSIM process can delay for a specified amount of simulation time by calling the hold function.

Prototype: void hold(double amount_of_time)
Example: hold(1.0);

If there are other processes waiting to run, the calling process will be suspended. Otherwise, time will immediately advance by the specified amount.

Caution: It is a common mistake to call hold with the wrong type of parameter, such as an integer value.

A process can delay until a specified time by calling hold with a parameter value equal to the specified time minus the current time. To make a simulation begin with a clock value other than zero, simply call hold at the beginning of the sim function with an amount of time equal to the desired initial time.

Calling the hold function with a zero amount of time might at first seem to be meaningless. But, it causes the running process to relinquish control to any other process that is waiting to run at the same simulation time. This can be used to affect the order of execution of processes that have activities scheduled for the same simulation time.

2.4 Advancing Time

There is no way for a program to directly assign a value to the simulation clock. The simulation clock advances as a side effect of a process performing one of the following function calls:

Calling one of these functions does not guarantee that time will advance. For example, calling the allocate function will cause time to pass only if the requested amount of storage is not available.

All CSIM function calls other than those in the above list, as well as all C++ language statements, occur instantaneously with respect to simulation time. A CSIM program can perform arbitrarily many activities in a single instant of simulation time.

A common programming error is to create a CSIM process that calls none of the functions in the above list. When this process receives control, it runs endlessly to the exclusion of all other CSIM processes.

2.5 Displaying the Time

There are several ways the simulation time can be automatically displayed while running a CSIM program. Every trace message contains the current simulation time. The variable clock and the function simtime() can be used to get the current simulated time. Also, when the report function is called to produce a report of all statistics, the report header contains the current simulation time.

2.6 Integer-Valued Simulation Time

In some simulation models, such as models of computer hardware, it is the case that time can only assume discrete integer values. Although CSIM maintains time as a floating point variable, some simple programming techniques can insure that the clock will always have an integer value. (Here, we are using the word "integer" in the mathematical sense.) Amounts of time appear as input parameters in calls to the following functions: hold, use, timed_reserve, timed_allocate, timed_put, timed_get, timed_receive, timed_synchronous_send, timed_wait, timed_queue, time_wait_any and timed_queue_any. To maintain an integer-valued clock, these parameters must have values that are integers (although of type double). This can be accomplished either by specifying a floating point numeric literal that has an integer value or by type casting an integer expression to type double.

Example: hold(10.0);
Example: bus->use((double) uniform_int(1,5));
Example: bus->use((double) floor (exponential(1.0)));

The IEEE Floating Point Standard guarantees that addition and subtraction with integer valued operands will yield integer valued results. CSIM performs only addition on the simulation clock.

Next Section