The Profile object is used to enable profiling during the lifetime of the object. When created, it takes arguments to indicate the output file and the profiling mode (trace or accumulate). When destroyed (i.e. goes out of scope or is explicitly deleted), the profile data is written to the specified output file. For example:

  profile::Profile profile("profile.txt", profile::accum)

During the lifetime of the Profile object, timing data is stored through a simple interface provided by the Scope object. These objects are used to profile library operations for the different areas mentioned in Table 5.1, “Profiling Configuration Mask” above. Any Scope objects defined in user programs fall into the 'user' category.

The declaration of an instance of this object starts a timer and when it is destroyed, the timer is stopped. The timing data is subsequently reported when the Profile object is destroyed. For example:

  profile::Scope<profile::user> scope("Scope Name", op_count);

The profile::user template argument indicates that this scope falls into the user category (and thus can be enabled with -DVSIP_PROFILE_USER). The first constructor argument is the name that will be used to display the scope's performance data in the log file (Section 5.3.2, “Scope names” describes the names used internally by the library.) The second parameter, op_count, is an optional unsigned integer specifying an estimate of the total number of operations (floating point or otherwise) performed. This is used by the profiler to compute the rate of computation. Without it, the profiler will still yield useful timing data, but the average rate of computation will be shown as zero in the log.

Creating a Scope object on the stack is the easiest way to control the region it will profile. For example, from within the body of a function (or as the entire function), use this to define a region of interest:

  {
    profile::Scope<profile::user> scope("Main computation:");

    // perform main computation
    //
    ...
  }

The closing brace causes scope to go out of scope, logging the amount of time spent doing the computation.

In trace mode, the start and stop times where scopes begin and end are stored as profile data. The log will present these events in chronological order. This mode is preferred when a highly detailed view of program execution is desired.

In accum (accumlate) mode, the start and stop times are subtracted to compute the time spent in a scope and the cumulative sum of these durations are stored as profile data. The log will indicate the total amount of time spent in each scope. This mode is desirable when investigating a specific function's average performance.