libcollector(3)libcollector(3)NAMElibcollector - API for the Performance Tools collector library
SYNOPSIS -- C and C++ API
#include "collectorAPI.h"
ld ... -lcollectorAPI
(For C compilations, you must also add -L <lib-path> and -R <lib-path>
to specify where to search for the libcollectorAPI.so; for C++ and For‐
tran compilations, -L and -R are not needed.)
or
#include "libcollector.h" (provided for backward compatibility on
Solaris systems only)
void collector_sample(char *name);
void collector_pause(void);
void collector_resume(void);
void collector_thread_pause(pthread_t tid); [deprecated]
void collector_thread_resume(pthread_t tid); [deprecated]
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, and are deprecated, and will
be removed on all systems in a future release.
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); [deprecated]
CollectorAPI.threadResume(Thread thread); [deprecated]
CollectorAPI.terminate();
DESCRIPTION
The shared object, libcollector.so, is used to collect performance 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 includ‐
ing collectorAPI.h and linking with -lcollectorAPI (which contains real
functions to check for the existence of the underlying libcollector.so
API functions), or by including 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 works under all
circumstances, although it requires that the API library (libcollec‐
torAPI.so) be installed on the system on which you are running.
The second way works when used in the main executable, and when data
collection is started at the same time the program starts. It does not
always work when dbx is used to attach to the process, nor when used
from within a shared library that is loaded with dlopen by the process.
It is provided for backward compatibility on Solaris systems only.
In either case, the calls have an effect only if an experiment 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 compatibility.) 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
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 functions 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-direc‐
tory>/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 record‐
ing of event-specific data in an experiment, and to close an experi‐
ment. The experiment must be created using the collect command or by
enabling the Collector 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 individual
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 writ‐
ing 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 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 incor‐
rect 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 writ‐
ing of data for that thread is already turned off, the call is ignored.
The function argument 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_pause() is deprecated, and will be removed in a
subsequent release. A warning is recorded in experiments recorded on
targets that use the interface.
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 writ‐
ing of data for that thread is already turned on, the call is ignored.
The function argument is the POSIX thread ID, as returned by
thr_self(3THR) for Solaris operating environment threads and
pthread_self(3THR) for POSIX threads.
The collector_thread_resume() is deprecated, and will be removed in a
subsequent release. A warning is recorded in experiments recorded on
targets that use the interface.
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 provide informa‐
tion 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 Ana‐
lyzer. The name need not follow any of the normal naming conventions of
functions, and they can contain embedded blanks or embedded quote char‐
acters.
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 function is, or why the function was dynami‐
cally 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 ALSOcollect(1), collector(1), er_print(1), and the Performance Analyzer
manual.
March 2009 libcollector(3)
