SSAPI(3)SSAPI(3)


NAME
     ssrt_buffer_clear, ssrt_caliper_point, ssrt_experiment_init,
     ssrt_experiment_shutdown, ssrt_experiment_suspend,
     ssrt_experiment_restart, ssrt_interface_routine - Invokes SpeedShop
     runtime library routines

SYNOPSIS
     C or C++:

        #include <SpeedShop/api.h>

        void ssrt_buffer_clear(void);

        int ssrt_caliper_point(int flags, const char *label);

        void ssrt_experiment_init(void);

        void ssrt_experiment_shutdown(void);

        void ssrt_experiment_suspend(void);

        void ssrt_experiment_restart(void);

        long ssrt_interface_routine(int op, void *context);

     Fortran:

        CALL SSRT_BUFFER_CLEAR

        INTEGER SSRT_CALIPER_POINT

        INTEGER i, flags

        i = SSRT_CALIPER_POINT(flags, 'label')

        CALL SSRT_EXPERIMENT_INIT

        CALL SSRT_EXPERIMENT_SHUTDOWN

        CALL SSRT_EXPERIMENT_SUSPEND

        CALL SSRT_EXPERIMENT_RESTART

DESCRIPTION
     The ssapi routines define a user-accessible interface to some of the
     SpeedShop run-time library routines.

     To explicitly link with the SpeedShop runtime DSO, use the -lss option
     on your compiler command line.  This option loads the two SpeedShop
     libraries, libss.so and libssrt.so, into the executable address space.

     The ssrt_buffer_clear routine clears all currently accumulated data
     and resets all values to zero.  It is used to exclude data from an
     initialization phase of the program.  Typically, this routine is not
     used; the preferred alternative is to use ssrt_caliper_point.

     The ssrt_caliper_point routine records a caliper point in the
     experiment.  It can be called from anywhere in your code.  This
     routine accepts the following arguments:

     flags     Deferred implementation.  If specified, this argument is
               ignored.

     label     Specifies a string label for the caliper point.

     An implicit caliper point is recorded when a process commences
     execution.  A final caliper point is recorded when the process exits
     normally.  The implicit caliper point is numbered 0, and the first
     caliper point after that is numbered 1.  Additional caliper points are
     numbered sequentially.

     Caliper points are automatically recorded when the following events
     occur:

     * A fatal or exit signal is received.

     * The program calls an exec(2) function.

     The ssrt_experiment_init routine starts and initializes performance
     data collection for the calling process if the
     _SPEEDSHOP_INIT_DEFERRED environment variable has been set.  Calling
     the function is equivalent to:

          % setenv _SPEEDSHOP_INIT_DEFERRED_SGI <signal>
          % ssrun -<exp> a.out
          % kill -<signal> <a.out_pid>

     But the control over when the initialization of the SpeedShop
     experiment occurs is far more flexible and precise.

     The ssrt_experiment_suspend routine temporarily suspends performance
     data collection for the calling process and inhibits writing of an
     experiment file for the process.

     The ssrt_experiment_restart routine restarts a preiviously suspended
     performance data collection (using ssrt_experiment_suspend()) for the
     calling process and enables writing of an experiment file for the
     process.

     The ssrt_experiment_shutdown routine disables performance data
     collection for the calling process and inhibits writing of an
     experiment file for the process.  Note: This routine was previously
     named ssrt_experiment_stop.

     The ssrt_interface_routine invokes the appropriate SpeedShop run-time
     routine.  This routine accepts the following arguments:

     op        Deferred implementation.

     context   Deferred implementation.

SEE ALSO
     prof(1), speedshop(1), ssdump(1), ssrun(1)