instrumentation.h

Go to the documentation of this file.

/*
 * instrumentation.h
 *
 * Copyright (c) 2003, 2004 The University of Utah and the Flux Group.
 * All rights reserved.
 *
 * This file is licensed under the terms of the GNU Public License.  
 * See the file "license.terms" for restrictions on redistribution 
 * of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 */

#ifndef _misc_instrumentation_h
#define _misc_instrumentation_h

/**
 * @file instrumentation.h
 *
 * Header file for instrumentation tools.  Instrumenting blocks of code or
 * expressions is done by adding a call to CB_INSTR_POINT in the configure.in
 * file and surrounding the code with a macro call.  For example, to do high
 * resolution timings of the following code:
 *
 * @code
 *   for( lpc = 0; lpc < 100; lpc++ )
 *   {
 *       ...
 *   }
 * @endcode
 *
 * You would modify the configure.in to include:
 *
 * @code
 *   CB_INSTR_POINT([my_point],
 *                  [HRTIME_INSTR],
 *                  [My instrumentation point])
 * @endcode
 *
 * Where 'my_point' is the name of the instrumentation point, #HRTIME_INSTR is
 * the C macro that will record the timings, and 'My instrumentation point' is
 * the description of the point.  The result of this call will be two new
 * definitions in the config.h: 'INSTR_my_point' and 'INSTR_my_point_data'.
 * The first C macro is used to surround the code block and the second contains
 * the data used to initialize the instrumentation point structure (iPoint).
 * With these new definitions, we can modify our original code to add
 * instrumentation:
 *
 * @code
 *   #if defined(INSTR_my_point_data)
 *   static struct iPoint IP_my_point = {
 *       INSTR_my_point_data
 *   };
 *   #endif
 * ...
 *   INSTR_my_point(&IP_my_point, ({
 *       for( lpc = 0; lpc < 100; lpc++ )
 *       {
 *           ...
 *       }
 *   }));
 * @endcode
 *
 * (Notice the parentheses around the code block, these are required for things
 * to parse correctly.)
 *
 * Finally, to enable this instrumentation point, you either need to use
 * --enable-instrumentation to enable all of the points, or
 * --enable-instrumentation="my_point ..." to enable this point and any others
 * named.
 *
 * Any instrumentation data collected during a run is usually appended to a
 * file #iPrintPointsAtExit function.
 *
 * @see configure.in
 * @see instrumentation_test.c
 */

#ifdef __cplusplus
extern "C" {
#endif

#include <stdio.h>
#include <stdlib.h>
#include <sys/time.h>
#include <sys/resource.h>

/**
 * Container for low-resolution timer values.
 */
typedef unsigned long long lrtime_t;

/**
 * @return A low-resolution time stamp.  The current resolution is on the order
 * of microseconds.
 */
static inline lrtime_t lrtime(void);

static inline lrtime_t lrtime(void)
{
    struct timeval tv;
    lrtime_t retval;
    
    if( gettimeofday(&tv, NULL) == -1 )
    {
        abort();
    }
    retval = (lrtime_t)tv.tv_usec / (lrtime_t)(1);
    retval += ((lrtime_t)tv.tv_sec * (lrtime_t)(1000 * 1000));
    
    return( retval );
}

/**
 * @return The low-resolution CPU usage for the current PID.  The current
 * resolution is on the order of microseconds, when available.
 */
static inline lrtime_t lrcputime(void);

static inline lrtime_t lrcputime(void)
{
    struct rusage ru;
    lrtime_t retval;

    if( getrusage(RUSAGE_SELF, &ru) == -1 )
    {
        abort();
    }
    retval = (lrtime_t)ru.ru_utime.tv_usec / (lrtime_t)(1);
    retval += ((lrtime_t)ru.ru_utime.tv_sec * (lrtime_t)(1000 * 1000));
    retval += (lrtime_t)ru.ru_stime.tv_usec / (lrtime_t)(1);
    retval += ((lrtime_t)ru.ru_stime.tv_sec * (lrtime_t)(1000 * 1000));

    return( retval );
}

/**
 * Container for high-resolution timer values.
 */
typedef unsigned long long hrtime_t;

/**
 * @return A high-resolution time stamp.
 */
static inline hrtime_t hrtime(void);

#if defined(i386)
static inline hrtime_t hrtime(void)
{
    unsigned long long retval;
    
    __asm__ __volatile__ ("rdtsc" : "=A" (retval) );
    return( retval );
}
#else
#warning "CPU timestamp counter not available, using gettimeofday"
static inline hrtime_t hrtime(void)
{
    struct timeval tv;
    hrtime_t retval;
    
    gettimeofday(&tv, 0);
    retval = (hrtime_t)tv.tv_usec;
    retval += ((hrtime_t)tv.tv_sec * (hrtime_t)(1000 * 1000));
    return( retval );
}
#endif

enum {
    IPB_PRINT_HISTORY,
    IPB_DROP_HISTORY_START,
};

/**
 * Flags for the iPoint structure.
 */
enum {
    /** Print the entire history in addition to the summary data. */
    IPF_PRINT_HISTORY = (1L << IPB_PRINT_HISTORY),
    /** Drop data values at the start of the history instead of the tail. */
    IPF_DROP_HISTORY_START = (1L << IPB_DROP_HISTORY_START),

    /** Bitmask covering all of the meaningful flag bits. */
    IPF_MASK = (IPF_PRINT_HISTORY |
                IPF_DROP_HISTORY_START)
};

/*
 * ip_Name - The name of this instrumentation point.
 * ip_Description - A description of this instrumentation point, can be NULL.
 * ip_Flags - Holder for any IPF_ flags.
 * ip_History.data - An array that can contain atleast ip_History.length
 *   elements that should be used to record data values as they are posted.  If
 *   left NULL, the values won't be recorded and only statistics will be
 *   available.
 * ip_History.length - The maximum number of elements that can be placed in
 *   the 'data' array.
 * ip_History.start - The index where the oldest recorded value is in the
 *   'data' array.  Normally, this will be zero, unless the
 *   IPF_DROP_HISTORY_START flag is set and the 'data' array overflowed.
 * ip_History.lost - The number of data values that were not added to the
 *   'data' array because it overflowed.
 * ip_Format - The format to use when printing values.  If this is NULL, the
 *   default format, '%10.2f  ', is used.
 * ip_Count - The number of data values posted to this instrumentation point.
 * ip_Total - The sum of the data values posted.
 * ip_Minimum - The minimum observed data value that has been posted.
 * ip_Maximum - The maximum observed data value that has been posted.
 * ip_Succ - Link to the next instrumentation point in the global linked list.
 *   Note, the instrumentation point is not added to the list until the first
 *   data value is posted.
 */
struct iPoint {
    const char *ip_Name;
    const char *ip_Description;
    unsigned long ip_Flags;
    struct {
        double *data;
        size_t length;
        unsigned int start;
        unsigned int lost;
    } ip_History;
    const char *ip_Format;
    unsigned long long ip_Count;
    double ip_Total;
    double ip_Minimum;
    double ip_Maximum;
    struct iPoint *ip_Succ;
};

/**
 * Macro used to statically initialize the ip_History field of the iPoint
 * structure.
 *
 * @param history A statically allocated array of doubles.
 */
#define IPOINT_INIT_HISTORY(history) { \
    history, \
    sizeof(history) / sizeof(double) \
}

/**
 * Macro used to perform high-resolution timings of a block of code.
 *
 * @param point The iPoint to use when recording data.
 * @param block The code block to instrument.
 *
 * @see NOINSTR
 */
#define HRTIME_INSTR(point, block) { \
    hrtime_t _start, _end; \
\
    _start = hrtime(); \
    block; \
    _end = hrtime(); \
    iPostFloatData(point, (_end - _start)); \
}

/**
 * Macro used to perform low-resolution timings of a block of code.
 *
 * @param point The iPoint to use when recording data.
 * @param block The code block to instrument.
 *
 * @see NOINSTR
 */
#define LRTIME_INSTR(point, block) { \
    lrtime_t _start, _end; \
\
    _start = lrtime(); \
    block; \
    _end = lrtime(); \
    iPostFloatData(point, (_end - _start)); \
}

/**
 * Macro used to perform low-resolution CPU timings of a block of code.
 *
 * @param point The iPoint to use when recording data.
 * @param block The code block to instrument.
 *
 * @see NOINSTR
 */
#define LRCPUTIME_INSTR(point, block) { \
    lrtime_t _start, _end; \
\
    _start = lrcputime(); \
    block; \
    _end = lrcputime(); \
    iPostFloatData(point, (_end - _start)); \
}

/**
 * Macro used to accumulate the value of a numeral expression.
 *
 * @param point The iPoint to use when recording data.
 * @param expr An expression that results in a number value.
 *
 * @see NOINSTR
 */
#define ACCUM_INSTR(point, expr) { \
    iPostFloatData(point, (double)(expr)); \
}

/**
 * Macro used to avoid instrumenting a block of code.
 *
 * @param point Not used.  This is only here so it can mimic the other INSTR
 * macros.
 * @param block A block of code to execute.
 */
#define NOINSTR(point, block) (void)(block)

/**
 * The environment variable name to check for the instrumentation output file
 * name.
 */
#define INSTR_FILE_NAME_ENV "CB_INSTR_FILE_NAME"

/*
 * The structure of global data needed by the instrumentation infrastructure.
 *
 * iid_OutputFileName - The name of the file where results should be written.
 * If NULL, a file be created with a name having the form:
 * '<PACKAGE>-instrumentation-<pid>.txt'.  If it is a '-', the results will be
 * written to standard out.
 * iid_FirstPoint - The first instrumentation point in the list.
 * iid_NullPoint - A special instrumentation point value used to detect whether
 * an iPoint object is in the global list or not.
 */
struct iInstrumentationData {
    const char *iid_OutputFileName;
    struct iPoint *iid_FirstPoint;
    struct iPoint iid_NullPoint;
};

/**
 * The global data needed by the instrumentation infrastructure.
 */
extern struct iInstrumentationData instrumentation_data;

/**
 * Post a floating point data value to an instrumentation point.
 *
 * @param ip The instrumentation point to add the given value to.
 * @param value The value to add.
 */
void iPostFloatData(struct iPoint *ip, double value);

/**
 * Print the collected values for an instrumentation point.  The summary data
 * printed depends on whether or not a history array has been provided:  no
 * history means the summary covers all of the posted data; otherwise the
 * summary covers only the data held in the history.
 *
 * @param file The file to print the data to.
 * @param ip The instrumentation point to print out.
 */
void iPrintPoint(FILE *file, struct iPoint *ip);

/**
 * Print all of the instrumentation points that have had data posted to them
 * using iPrintPoint.
 *
 * @param file The file to print the data to.
 */
void iPrintPoints(FILE *file);

/**
 * An atexit(3) function that calls iPrintPoints with a file from one of the
 * following sources (listed in order of precedence):
 *
 * @li The value of the CB_INSTR_FILE_NAME environment variable, if it is
 * defined.  Note: A value of "-" represents stdout.
 * @li The instrumentation_data.iid_OutputFileName variable, if it is non-NULL.
 * Note: A value of "-" represents stdout.
 * @li A formatted file name derived from PACKAGE and the current process ID.
 *
 * All of the files are opened in append mode and the current time is printed
 * out before calling #iPrintPoints.  When the function finishes it will clear
 * instrumentation_data.iid_FirstPoint so that any future calls to this
 * function will not result in data being printed more than once.
 */
void iPrintPointsAtExit(void);

#ifdef __cplusplus
}
#endif

#endif

---