SYNOPSIS

    #include "libut/ut.h"
    int UT_prf_create(char *name, char *description, UT_prf_scale scale);

DESCRIPTION

This function defines a profiling group. Profiling statistics that are later added to this profiling group will be printed together in the output of the prf control port command under a common banner having the name, description and scale given in the arguments.

The name and description will be copied and silently truncated to their maximum allowed length if necessary. The description is used only in the output of the control port prf command.

scale is one of the following pre-defined scales:

te_log_1u_10s

1 microsecond to 10 seconds

te_10u_100u

10 to 100 microseconds

te_100u_1m

100 microseconds to 1 millisecond

te_log_1m_10s

1 millisecond to 10 seconds

te_minute

10 second increments from 1 to 60 seconds

te_hour

10 minute increments to 1 to 60 minutes

te_non_1s_15min

1 second to 15 minutes, non-uniform increments

Selecting a scale is somewhat a matter of intuition for the time range over which a given statistic may vary.

Once a profiling group has been defined, commonly-used sections of code can be surrounded with a UT_prf_bgn(3) and UT_prf_end(3) pair of statements. This tracks the execution time of that section of code on an ongoing basis. The prf control port command displays these timings in the form of a histograms.

RELATED CONTROL PORT COMMANDS

The prf control port command displays the profiling statistics among other capabilities. See the control port online help.

EXAMPLE

    /* At program startup define the prf */
    UT_prf_create("database", "probase query timings", te_log_1m_10s);
    
    /* Later in some occasional function call... */
    UT_prf_bgn("database", "db-read");
    ... database read code...
    UT_prf_end("database", "db-read");
    
    UT_prf_bgn("database", "db-write");
    ... database write code...
    UT_prf_end("database", "db-write");

After running the read and write routines some number of times, the prf control port command output may look like this:

    =================================================================
                database  --  probase query timings
    =================================================================
    name                  count   <1m 1-10m 10-100m 0.1-1s 1-10s >10s
    --------------------- ------- --- ----- ------- ------ ----- ----
    db-read               10      60%   40%
    db-write              2             30%     70%

SEE ALSO

UT_prf_bgn(3), UT_prf_end(3)

AUTHOR

Troy D. Hanson <thanson@users.sourceforge.net>