A.2 SHMEM Measurement API

The prototypes for the SHMEM measurement API are shown below:

     #include <pshmem.h>
     
     int pshmem_control(int on);
     
     unsigned int pshmem_create_event(const char *name, const char *desc);
     
     void pshmem_event_start(unsigned int evttag, ...);
     void pshmem_event_end(unsigned int evttag, ...);
     void pshmem_event_atomic(unsigned int evttag, ...);

A.2.1 SHMEM 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 communication or 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_PSHMEM__ macro. Any C compiler or performance tool supporting the measurement API described here will define the __GASP_PSHMEM__ macro, so protecting any manual instrumentation with #ifdefs will allow your code to remain portable to systems not supporting this API.

A.2.2 SHMEM API Examples

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

     #include <shmem.h>
     #include <pshmem.h>
     
     int main() {
       unsigned int evin, evcp, evcm;
     
       shmem_init();
     
       evin = pshmem_create_event("Init phase", NULL);
       evcp = pshmem_create_event("Compute phase", "%d");
       evcm = pshmem_create_event("Comm phase", NULL);
     
       /* initialization phase */
       pshmem_event_start(evin);
       /* ... */
       shmem_barrier_all();
       pshmem_event_end(evin);
     
       pshmem_event_start(evcp, -1);
       /* computation phase with N iterations */
       for (i = 0; i < N; i++) {
         pshmem_event_atomic(evcp, i);
         /* ... */
         shmem_barrier_all();
       }
       pshmem_event_end(evcp, -1);
     
       /* communication phase */
       pshmem_event_start(evcm);
       /* ... */
       shmem_barrier_all();
       pshmem_event_end(evcm);
     
       return 0;
     }

A.2.3 SHMEM 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.