Man Page libcollector.3
NAME
libcollector - API for the Forte(TM) Performance tools col-
lector library
SYNOPSIS -- C and C++ API
#include "libcollector.h"
void collector_sample(char *name);
void collector_pause(void);
void collector_resume(void);
void collector_terminate_expt(void);
void collector_func_load(char *name, char *alias,
char *sourcename, void *vaddr, int size,
int lntsize, Lineno *lntable);
void collector_func_unload(void *vaddr);
void collector_module_load(char *modulename, void *vaddr);
void collector_module_unload(void *vaddr);
SYNOPSIS -- Fortran API
include "libfcollector.h"
collector_sample(string)
character*(*) string
collector_pause()
collector_resume()
collector_terminate_expt()
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 when the Collector is enabled. You
should not link your program with -lcollector.
The API defined in the C and C++ libcollector.h are macros
that check for the existence of their functions. If the
functions are not in the address space, the calls are
ignored: that is, the executable runs normally, even if the
library is not present. If the library is present, the exe-
cutable calls the API functions, although it must be invoked
from the collect command or by dbx with collection enabled
in order to record data.
The Fortran API libfcollector.h defines the interface to a
library. The application must be linked with -lfcollector to
use this library. The Fortran API provides the same
features as the C and C++ API, excluding the dynamic func-
tion and module interfaces.
The Collector API can be safely used in a multithreaded
environment.
EXPERIMENT CONTROLS
The C, C++ and Fortran API includes a set of functions that
can be used to record sample points in an experiment, to
stop and start the recording of event-specific data in an
experiment, and to close an experiment. The experiment must
be created using the collect command or by enabling the Col-
lector in dbx.
The collector_sample() function records a sample point when
it is called, and labels the sample with the string that is
passed to the API function. If no experiment is active, the
call is ignored. The label is not currently used.
Sample points contain data for the process and not for indi-
vidual threads. In a multithreaded application, the
collector_sample() API function ensures that only one sample
is written if another call is made while it is recording a
sample.
The collector_pause() function turns off the actual writing
of event-specific data to the experiment. If the experiment
is already terminated, or no experiment is active, or writ-
ing of data is already turned off, the call is ignored.
The collector_resume() function turns on the actual writing
of event-specific data to the experiment. If the experiment
is already terminated, or no experiment is active, or writ-
ing of data is already turned on, the call is ignored.
In a multithreaded application, a call to collector_pause()
that is made at the same time as a call to
collector_resume() can cause incorrect information about the
status of recording to be written in the experiment log
file.
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 a C or C++ program you need only
insert the relevant include statement into the function that
calls the API routines. To use the interface from a Fortran
program you must link with -lfcollector.
DYNAMIC FUNCTIONS
The C and C++ API includes a set of functions used to pro-
vide information about dynamically-generated functions to
the Collector.
collector_func_load() is used to pass information about
dynamically-generated functions into the collector for
recording in the experiment. (The Java[tm] HotSpot virtual
machine uses a slightly different, non-public interface.)
name gives the name of the dynamically constructed function.
This name is the name that is used in the Functions tab of
the Performance Analyzer. The name need not follow any of
the normal naming conventions of functions, although it
should not contain embedded blanks or embedded quote charac-
ters.
alias is an arbitrary string used to describe the function.
It can be NULL. It is not interpreted in any way, and can
contain embedded blanks. It is displayed in the Summary tab
of the Analyzer. It can be used to indicate what the func-
tion is, or why the function was dynamically constructed.
sourcename gives the path to the source file from which the
function was constructed. It can be NULL.
vaddr gives the address at which the function was loaded.
size is the size of the function in bytes.
lntsize is a count of the number of entries in the line
number table. It should be zero if line number information
is not provided.
lntable is a table containing lntsize entries, each of which
is a pair of integers. The first integer is an offset, and
the second entry is a line number. All instructions between
an offset in one entry and the offset given in the next
entry are attributed to the line number given in the first
entry. Offsets must be in increasing numeric order, but the
order of line numbers is arbitrary. If lntable is NULL, no
source listings of the function are possible, although
disassembly listings are available.
collector_func_unload() is used to inform the collector that
the dynamic function at the address given has been unloaded.
DYNAMIC MODULES
The C and C++ API includes a set of functions used to pro-
vide information about dynamically loaded modules to the
Collector.
collector_module_load() is used to inform the collector that
a module (*.o) has been loaded into the address space by the
target. The module is read to determine its functions and
the source and line number mappings for them.
collector_module_unload() is used to inform the collector
that a previously loaded module has been unloaded.
SEE ALSO
collect(1), collector(1), er_print(1), and the manual
Program Performance Analysis Tools.