Go to main content
Oracle Developer Studio 12.6 Man Pages

Exit Print View

Updated: June 2017
 
 

libcollector (3)

Name

libcollector - API for the Performance Analyzer tools collector library

Synopsis

C and C++ API

#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);

Fortran API

include "libfcollector.h"
collector_sample(string)
     character*(*) string
collector_pause()
collector_resume()
collector_terminate_expt()

Java API

import com.sun.forte.st.collector.CollectorAPI;

CollectorAPI.sample(String name);
CollectorAPI.pause();
CollectorAPI.resume();
CollectorAPI.terminate();

Description

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.

APIs for Recording Sample Points

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.

APIs for Stopping and Starting Data Recording

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.

APIs for Terminating an Experiment

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.

APIs for Recording Dynamically Created Functions

The C and C++ API includes a set of functions that are used to provide 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.

collector_func_unload()

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:

name

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.

alias

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.

sourcename

Path to the source file from which the function was constructed. It can be NULL.

vaddr

Address at which the function was loaded.

size

Size of the function in bytes.

lntsize

Count of the number of entries in the line number table. It should be zero if line number information is not provided.

lntable

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.

Usage

Compiling With C and C++

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

Compiling With Fortran

You must include libfcollector.h in the Fortran source file when compiling.

For Fortran, compile with

-Iinstallation-directory/include/f95

Linking With C, C++, and Fortran

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.

Using the API From Java

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)

Attributes

See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE
ATTRIBUTE VALUE
Interface Stability
Committed
MT-Level
MT-Safe

See Also

collect(1), collector(1), er_print(1)

Performance Analyzer manual