NAME
libcollector - API for the Performance Tools collector
library
SYNOPSIS -- C and C++ API
#include "collectorAPI.h"
ld ... -lcollectorAPI
or
#include "libcollector.h" (provided for backward compati-
bility on Solaris systems only)
void collector_sample(char *name);
void collector_pause(void);
void collector_resume(void);
void collector_thread_pause(unsigned int t);
void collector_thread_resume(unsigned int t);
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);
Note: Functions collector_thread_pause() and
collector_thread_resume are not available on Linux
systems.
SYNOPSIS -- Fortran API
include "libfcollector.h"
collector_sample(string)
character*(*) string
collector_pause()
collector_resume()
collector_terminate_expt()
SYNOPSIS -- Java(TM) API
import com.sun.forte.st.collector.CollectorAPI
CollectorAPI.sample(String name);
CollectorAPI.pause();
CollectorAPI.resume();
CollectorAPI.threadPause(Thread thread);
CollectorAPI.threadResume(Thread thread);
CollectorAPI.terminate();
Note: Java profiling is available on Solaris and Linux sys-
tems.
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.
There are two ways to access the C and C++ interface, either
by including collectorAPI.h and linking with -lcollectorAPI
(which contains real functions to check for the existence of
the underlying libcollector.so API functions), or by includ-
ing libcollector.h (which contains macros that check for the
existence of the underlying libcollector.so API functions.)
The first way requires linking with an API library, and will
work under all circumstances, although it requires that the
API library (libcollecorAPI.so) be installed on the system
on which you are running.
The second way will work when used in the main executable,
and when data collection is started at the same time the
program starts. It will not always work when dbx is used to
attach to the process, nor when used from within a shared
library that is dlopen'd by the process. It is provided for
backward compatibility on Solaris systems only.
In either case, the calls only have an effect if an experi-
ment is being collected.
The Fortran API libfcollector.h file defines the Fortran
interface to the library. The application must be linked
with -lcollectorAPI to use this library. (An alternate name
for the library, -lfcollector, is provided for backward com-
patibility.) The Fortran API provides the same features as
the C and C++ API, excluding the dynamic function and thread
pause and resume calls.
The Java(TM) API file defines the methods accessible from a
Java code. The application must be invoked with a classpath
pointing to:
<installation-directory>/lib/collector.jar
where the <installation-directory> is the directory into
which the Sun ONE Studio release was installed.
If you want the Java API to be accessible to classes loaded
with -Xbootclasspath, you must append
<installation-directory>/lib/collector.jar
to the -Xbootclasspath argument, and add
<installation-directory>/lib
to the sun.boot.library.path property.
The Java API includes the same functions as the C/C++ API,
excluding the dynamic function calls. Neither dynamic func-
tions from the JVM, nor JIT(HotSpot)-compiled code use the
Java API; they use the C++ API.
When compiling or linking with compilers other than those
coming from the same release as the performance tools, paths
to the include file and library (if needed) must be
specified.
For C and C++, compile with
-I<installation-directory>/prod/include/cc
For Fortran, compile with
-I<installation-directory>/prod/include/f95.
In either case, link with:
-R<installation-directory>/lib -L<installation-
directory>/lib (v8 or x86 applications)
or
-R<installation-directory>/lib/v9 -L<installation-
directory>/lib/v9 (v9 applications)
The Collector API can be safely used in a multithreaded
environment. The implementation of all of these functions
is contained entirely in the libcollector.so file, and none
of them makes any calls back to any routines in the target
process (other than to functions within the libc.so and
libthread.so files).
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 writing of
event-specific data to the experiment. The action applies
to all threads. 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 writing of
event-specific data to the experiment. The action applies
to all threads. If the experiment is already terminated, or
no experiment is active, or writing 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_thread_pause() function turns off the writing
of event-specific data from a particular thread to the
experiment. If the experiment is already terminated, or no
experiment is active, or writing of data for that thread is
already turned off, the call is ignored. The function argu-
ment is the POSIX thread ID, as returned by thr_self(3THR)
for Solaris[tm] operating environment threads and
pthread_self(3THR) for POSIX threads.
The collector_thread_resume() function turns on the writing
of event-specific data from a particular thread to the
experiment. If the experiment is already terminated, or no
experiment is active, or writing of data for that thread is
already turned on, the call is ignored. The function argu-
ment is the POSIX thread ID, as returned by thr_self(3THR)
for Solaris operating environment threads and
pthread_self(3THR) for POSIX threads.
The global pause or resume setting and any thread-specific
pause or resume settings are independent. Data is not writ-
ten by a thread if either the global setting or the setting
for that thread is "pause". Data is written by a thread if
both the global setting and the setting for that thread are
"resume". The initial setting for all threads is "resume".
There are two ways of using the thread-specific pause and
resume functionality: by having one master thread make all
the calls for all threads, including itself; or by having
each thread make calls only for itself. Any other usage can
lead to unpredictable results.
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.
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, and they may
contain embedded blanks or embedded quote characters.
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.
ATTRIBUTES
____________________________________________________________
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
|_____________________________|_____________________________|
| Stability Level | Stable |
|_____________________________|_____________________________|
SEE ALSO
collect(1), collector(1), er_print(1), and the Performance
Analyzer manual.