Man Page libcollector.3

NAME

     libcollector - API for the Forte(TM) Performance tools  col-
     lector library

SYNOPSIS

     #include "libcollector.h"

     void collector_sample(char *name);

     void collector_pause(void);

     void collector_resume(void);

     void collector_terminate_expt(void);

AVAILABILITY

     Part of Forte C, Forte C++, and Forte for  High  Performance
     Computing.

DESCRIPTION

     The shared object, libcollector.so, is used to collect  per-
     formance data and is normally loaded using LD_PRELOAD by the
     collect command or by dbx.

     The API defined in libcollector.h are macros that check  for
     the  existence  of  their  functions. If they are not in the
     address  space,  the  calls  are  ignored,  with  no   error
     reported: that is, the executable runs normally, even if the
     library is not present.  If the library is present, the exe-
     cutable  can  access  its API functions, although it must be
     invoked from the collect command or by dbx  with  collection
     enabled in order to record data.

     The collector_sample() function takes a sample  when  it  is
     invoked,  and  labels the sample with the given name.  If no
     experiment is active, the call is ignored. The label is  not
     currently used.

     The collector_pause() function turns off the actual  writing
     of  profile  data  to  the experiment.  If the experiment is
     already terminated, or no experiment is active,  or  writing
     of data is already turned off, the call is ignored.

     The collector_resume() function turns on the actual  writing
     of  profile  data  to  the experiment.  If the experiment is
     already terminated, or no experiment is active,  or  writing
     of data is already turned on, the call is ignored.

     The  collector_terminate_expt()  function   terminates   the
     experiment  whose  data is being collected.  No further data
     is collected, but the program continues to run normally.  If
     the  experiment  is  already terminated, or no experiment is
     active, the call is ignored.

     To use the interface from C or C++, include the  definitions
     given  above.  To  use the interface from Fortran, include a
     C$PRAGMA C (API-function-list) directive in the  routine  in
     which  the  calls are to be made, and link with -lcollector.
     You should pass an integer zero to collector_sample().

SEE ALSO

     analyzer(1),     collect(1),      collector(1),      dbx(1),
     er_archive(1),     er_cp(1),     er_export(1),     er_mv(1),
     er_print(1), er_rm(1), er_src(1), workshop(1), and
     Analyzing Program Performance With Sun WorkShop.