Previous: MPI Measurement API, Up: API Reference

A.4 C Measurement API

The prototypes for the sequential C measurement API are shown below:

     #include <cprof.h>
     int cprof_control(int on);
     unsigned int cprof_create_event(const char *name, const char *desc);
     void cprof_event_start(unsigned int evttag, ...);
     void cprof_event_end(unsigned int evttag, ...);
     void cprof_event_atomic(unsigned int evttag, ...);

A.4.1 C API Description

These functions may be used to turn data measurement on and off at runtime, and to manually instrument your program to notify PPW about application-specific events, such as when your program enters certain phases of computation.

If you plan on using your code with systems that might not support these functions, such as non-GASP compilers, you may protect each part of your program that is related to these functions by checking for the existence of the __GASP_CPROF__ macro. Any C compiler or performance tool supporting the measurement API described here will define the __GASP_CPROF__ macro, so protecting any manual instrumentation with #ifdefs will allow your code to remain portable to systems not supporting this API.

A.4.2 C API Examples

Using the measurement API described here, you might do this:

     #include <cprof.h>
     int main() {
       unsigned int evin, evcp;
       evin = cprof_create_event("Init phase", NULL);
       evcp = cprof_create_event("Compute phase", "%d");
       /* initialization phase */
       /* ... */
       cprof_event_start(evcp, -1);
       /* computation phase with N iterations */
       for (i = 0; i < N; i++) {
         cprof_event_atomic(evcp, i);
         /* ... */
       cprof_event_end(evcp, -1);
       return 0;

A.4.3 C API Notes

These functions are analogous to the pupc_create_event(3) functions and are subject to the same notes and limitations. See the pupc_create_event(3) for more documentation on how to properly use these functions.

For more information on pupc_create_event, see See UPC Measurement API.