User Guide: C++ : Boxes

14. Boxes

A box conceptually encloses part or all of a model. The box gathers statistics on the number of entities in the box (i.e., the population) and the amount of time entities spend in the box (i.e., the elapsed time). An entity might be a customer, a message, or a resource. Boxes are usually used to gather statistics on queue lengths, response times, and populations. Instrumenting a model involves inserting function calls at the places that entities enter and exit the box.

A table and a qtable are invisible but integral parts of every box. Statistics on the elapsed times are kept in the table, statistics on the population are kept in the qtable.

First-time users of boxes should focus on the following three sections, which explain how to set up boxes, instrument a model, and produce reports. Subsequent sections describe the more advanced features of boxes.

14.1. Declaring and Initializing a Box

A pointer to a dynamic box is declared in a CSIM program as follows:

Dynamic Example: box *bd;

Before a box can be used, it must be initialized by invoking the box constructor.

Prototype: box::box(char *name)
Static Example: box bs("box");
Dynamic Example: bd = new box("system");

The box name is used only to identify the box in the output reports. Up to 80 characters in the name will be stored by CSIM. A newly created box is always empty. To create a non-empty box, call the enter_box function (described in the following section) the appropriate number of times immediately after creating the box.

A box can be initialized as a permanent box using the box class.

Prototype: box::permanent_box(char * name)
Dynamic Example: b = new permanent_box("system");

The information in a permanent box is not cleared when the reset function is called, and a permanent box is not deleted when rerun is called. In all other ways, a permanent box is exactly like a box. As a general rule, do not make a box permanent unless you have a specific reason for doing so.

14.2. Instrumenting a Model

An entity enters a box by calling the enter method.

Prototype: double box::enter(void)
Dynamic Example: timestamp = bd->enter_box();

This function returns a timestamp that must be saved by the entity that entered the box. The entity exits the box by calling the exit method and passing to it the timestamp that it received upon entry.

Prototype: void box::exit(double entry_time)
Dynamic Example: bd->exit(timestamp);

It is the responsibility of the programmer to ensure that the integrity of the timestamp is maintained while the entity is in the box. Because boxes may be nested or may overlap, it is advisable to make the timestamp local to the CSIM process and to use a separate timestamp variable for each box. An invalid timestamp (i.e., one that is less than zero or greater than the current time) will cause an error.

14.3. Producing Reports

Reports for boxes are most often produced by calling the report function, which prints reports for all statistics gathering objects. A report can be generated for a specified box at any time by calling the report method.

Prototype: void box::report(void)
Dynamic Example: bd->report();

Reports can be produced for all existing boxes by calling the report_boxes function.

Prototype: void report_boxes(void)
Example: report_boxes();

The report for a box, as illustrated below, will include the box name, statistics on the elapsed times, and statistics on the population of the box. If the box is empty or no time has passed since its creation or reset, messages to that effect are printed instead of the statistics. Note that statistics on the elapsed times reflect only those entities that have exited the box. Entities still in the box when the report is produced contribute to the population statistics but not to the elapsed time statistics.

A summary report for all boxes can be generated by calling the box_summary function.

Prototype: void box_summary(void)
Example: box_summary();

The report that is produced contains one line for each box and includes only a subset of the statistics. If a box is empty or no time has passed since its creation or reset, some statistics will not appear.

14.4. Histograms

A histogram can be specified for the elapsed times in a box and for the population of a box using the following functions:

Prototype: void box::add_time_histogram(long nbucket, double min, double max)
Dynamic Example: bd->add_time_histogram (10, 0.0, 10.0);

Prototype: void box::add_number_histogram(long nbucket, long min, long max)
Dynamic Example: bd->add_number_histogram(10, 0, 10);

The histogram for the elapsed times is the same as the histogram for a table. See section 9.4, "Histograms", for details. The histogram for the population of a box is the same as the histogram for a qtable. See section 10.4, "Histograms", for details.

Caution: The min and max parameters of box_time_histogram are of type double, whereas the corresponding parameters of box_number_histogram are of type long.

14.5. Confidence Intervals

Confidence intervals can be requested for the mean of the elapsed times in a box and for the mean population of a box using the following functions:

Prototype: void box::time_confidence(void)
Dynamic Example: bd->time_confidence();

Prototype: void box::number_confidence(void)
Dynamic Example: bd->number_confidence();

These two types of confidence intervals are identical to the confidence intervals for a table and qtable, respectively. See sections 16.1, "Confidence Intervals" for details.

14.6. Moving Windows

Moving windows can be specified for the elapsed times in a box and for the population of a box using the following functions:

Prototype: void box::time_moving_window(long n)
Dynamic Example: bd->time_moving_window(1000);

Prototype: void box::number_moving_window(long n)
Dynamic Example: bd->number_moving_window(1000);

The window for the elapsed times specifies the number of entities whose elapsed times will be included in the statistics. The window for the population specifies the number of changes in the population that will be included in the statistics. Consequently, the simulation time covered by these two windows may not be the same.

14.7. Inspector Methods

All statistics maintained by a box can be retrieved during the execution of a model or upon its completion. The name of a box can also be retrieved.

The pointer to a box's elapsed time table can be passed to the inspector methods for a table in order to obtain statistics on the times that entities have spent in the box.

Dynamic Example: max_time_in_box
=bd->time_table()->max();

If no entities have exited the box, the table will be empty and zeros will be returned for the undefined statistics.

The pointer to a box's population qtable can be passed to the inspector methods for a qtable in order to obtain statistics on the population.

Dynamic Example: max_population
=bd->number_qtable->max();

If no time has passed, zero values will be returned for the undefined statistics.

14.8. Renaming a Box

The name of a box can be changed at any time using the set_name method.

Prototype: void box::set_name(char *new_name)
Dynamic Example: bd->set_name("system");

Only the first 80 characters of the box's name are stored.

14.9. Resetting a Box

Resetting a box causes all information maintained by the box to be reinitialized, except that the number currently present in the box is saved for use in computing future populations. All optional features selected for the box (e.g., histogram, confidence intervals, moving window) remain in effect and are also reinitialized.

The reset function is usually used to reset all statistics gathering tools at once. A specific box can be reset using the reset method.

Prototype: void box::reset(void)
Dynamic Example: bd->reset();

Although permanent boxes are not reset by the reset function, they can be reset explicitly by calling the reset method.

14.10. Deleting a Box

When a dynamic box is no longer needed, its storage can be reclaimed as follows:

Example: delete bd;

Once a box has been deleted, it must not be further referenced.

Next Section