Measuring Elapsed Time with Durations

Accumulators and Events are commonly used to record data about the duration of an operation: the Event counts the number of times that an operation is run, while the Accumulator records how long each operation takes to process. A Manager then uses this collected information to calculate the average time for the operation and the standard deviation of all the times. To simplify the implementation for supporting this use case, the application can create and use Duration objects.

Note: The Duration object does not need to be used to measure the elapsed time. If timing information is already available in an application, the application can record the time by using the appropriate Accumulator.

Each Duration object is associated with a particular Accumulator, which in turn is associated with a single Event. Duration objects can be created in one of the following ways:

  • Using the constructor for the class: Duration elapsedTime(AccumulatorObject);
  • By calling the durationFactory member function of the Listener object. However, the Listener does not keep a pointer to the objects returned by durationFactory member function. Delete objects that are created in this manner after use. Duration *elapsedTime = listener->durationFactory(AccumulatorObject);
  • Through the new operator. Delete objects that are created in this manner after use.

The AccumulatorObject parameter is the Accumulator that the Duration is associated with. This object accumulates the recorded durations of the Event.

Important: Unlike Events, Accumulators, and Meters, Duration objects are to be deleted after their use.

Naming

Duration Accumulators are to be named "duration" because the Manager Dashboard looks for this Accumulator name.

Using start and stop

After a Duration object is created, it can be used to record Durations by calling the start member function at the beginning of the period to be measured. After the recording interval completes, the stop function is called to calculate the time that is passed since start was run. The elapsed time (nanoseconds) is recorded to the current Accumulator and returned.

When the application would like to increment the associated Event counter at the same time the Duration is recorded, the stop function can be called with a value of true.

Reusing a Duration Object

After the stop command is called, a Duration object can be reused. If the next use case for the Duration object is for a different Accumulator, that Accumulator object can be specified as the argument to start when it is called. The different Accumulator then becomes the default for all accumulations until another Accumulator is specified in a future call to start.