#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 lib-
collectorAPI.so; for C++ and Fortran 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.
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.threadPause(Thread thread); [deprecated] CollectorAPI.threadResume(Thread thread); [deprecated] CollectorAPI.terminate();
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 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 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 (libcollectorAPI.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 Solaris 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, for v8 or x86 applications, link with
-R<installation-directory>/lib -L<installation-directory>/lib
or, for v9 applications
-R<installation-directory>/lib/v9 -L<installation-directory>/lib/v9
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).
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 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 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 argument is the POSIX thread ID, as returned by thr_self (3C) for Solaris[tm] operating environment threads and pthread_self (3C) 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 writing 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() for Solaris operating environment threads and pthread_self() 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.
The C and C++ API includes a set of functions 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. (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 can 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 function 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.
____________________________________________________________
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
|_____________________________|_____________________________|
| Stability Level | Stable |
|_____________________________|_____________________________|
collect (1) , collector (1) , er_print (1)
Performance Analyzer manual