libcollector - API for the Performance Analyzer tools collector library
#include "collectorAPI.h" ld ... -Rlib-path -Llib-path -lcollectorAPI ... (dynamic linking) ld ... -Llib-path -Bstatic -lcollectorAPI -Bdynamic ... (static linking) ld ... lib-path/libcollectorAPI.a ... (static linking) (For C++ and Fortran compilations, -L and -R are not needed.)
lib-path is described below in section "LINKING C, C++, AND FORTRAN".
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);
include "libfcollector.h" collector_sample(string) character*(*) string collector_pause() collector_resume() collector_terminate_expt()
import com.sun.forte.st.collector.CollectorAPI; CollectorAPI.sample(String name); CollectorAPI.pause(); CollectorAPI.resume(); CollectorAPI.terminate();
The libcollector APIs described here control the behavior of data collection at runtime. The API calls have an effect only if an experiment is being collected, and can therefore be left in the source code permanently.
The APIs for all languages include a set of functions that you can use to record sample points in an experiment; to stop and start the recording of event-specific data in an experiment; and to terminate an experiment. The C/C++ APIs also provide a set of functions for recording dynamically-created functions in the experiment. The Fortran and Java APIs do not provide such functions.
The collector_sample() and CollectorAPI.sample() functions record a sample point when they are called and label 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() function ensures that it writes only one sample if another call is made to it while it is recording a sample.
The collector_pause() and CollectorAPI.pause() functions turn off the writing of event-specific data to the experiment. The action applies to all threads. Calls to the functions are ignored if no experiment is active, the experiment is already terminated, or writing of data is already turned off.
The collector_resume() and CollectorAPI.resume() functions turn on the writing of event-specific data to the experiment. The action applies to all threads. Calls to the functions are ignored if no experiment is active, the experiment is already terminated, or writing of data is already turned on. In a multithreaded application, a call to pause that is made at the same time as a call to resume in another thread can cause incorrect information about the status of recording to be written in the experiment log file.
The collector_terminate_expt() and CollectorAPI.terminate() functions terminate the experiment whose data is being collected. No further data is collected, but the program continues to run normally. Calls to the function are ignored if no experiment is active or the experiment is already terminated.
The C and C++ API includes a set of functions that are used to provide information about dynamically-generated functions to the Collector:
is used to pass information about dynamically-generated functions into the Collector for recording in the experiment.
is used to inform the Collector that the dynamic function at the address given has been unloaded.
These API functions are not available in Fortran or Java. The Java HotSpot virtual machine uses a slightly different, non-public interface.
The parameters for collector_func_load() include the following:
The name of the dynamically constructed function. This name is the name that is used in the Functions view of Performance Analyzer. The name need not follow any of the normal naming conventions of functions, and they can contain embedded blanks or embedded quote characters.
Arbitrary string used to describe the function. It can be NULL. The alias string is not interpreted in any way and can contain embedded blanks. The alias is displayed in the Selection Details panel of Performance Analyzer. You can use it to indicate what the function is or why the function was dynamically constructed.
Path to the source file from which the function was constructed. It can be NULL.
Address at which the function was loaded.
Size of the function in bytes.
Count of the number of entries in the line number table. It should be zero if line number information is not provided.
Table containing lntsize entries, each of which is a pair of integers. The first integer is an offset and the second interger 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.
To access the C and C++ interface,you must include collectorAPI.h in the source file when compiling and you must link with –lcollectorAPI.
For C and C++, compile with
-Iinstallation-directory/include/cc
You must include libfcollector.h in the Fortran source file when compiling.
For Fortran, compile with
-Iinstallation-directory/include/f95
For 32-bit applications, lib-path is:
installation-directory/lib
where installation-directory is the directory in which the Oracle Developer Studio release was installed.
For 64-bit applications, lib-path is:
installation-directory/lib/v9 (SPARC) installation-directory/lib/amd64 (x86)
In either case, for C programs link with –Rlib-path –Llib-path in addition to the library specification.
For C++ and Fortran compilations, –L and –R are not needed.
To use the Java API, import com.sun.forte.st.collector.CollectorAPI and invoke the application with a classpath pointing to the following library class file:
installation-directory/lib/analyzer/lib/collector.jar
where installation-directory is the directory in which the Oracle Developer Studio release was installed.
You must also pass the –Djava.library.path=jlib-path argument to the JVM so that the shared library libcollectorAPI.so can be found by the JVM. Note that this library path is not the same as the library path used to load libcollectorAPI.so for the native languages.
For 32-bit applications, jlib-path is:
installation-directory/lib/analyzer
where installation-directory is the directory in which the Oracle Developer Studio release was installed.
For 64-bit applications, jlib-path is:
installation-directory/lib/analyzer/v9 (SPARC) installation-directory/lib/analyzer/amd64 (x86)
See attributes (5) for descriptions of the following attributes:
|
collect (1) , collector (1) , er_print (1)
Performance Analyzer manual