The C, C++, Fortran, and Java API Functions

The descriptions of the API functions follow.

• C and C++: collector_sample(char *name)

  Fortran: collector_sample(string name)

  Java: CollectorAPI.sample(String name)

  Record a sample packet and label the sample with the given name or string. The label is displayed by the Performance Analyzer in the Event tab. The Fortran argument string is of type character.

  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 number of samples recorded can be less than the number of threads making the call.

  The Performance Analyzer does not distinguish between samples recorded by different mechanisms. If you want to see only the samples recorded by API calls, you should turn off all other sampling modes when you record performance data.

• C, C++, Fortran: collector_pause()

  Java: CollectorAPI.pause()

  Stop writing event-specific data to the experiment. The experiment remains open, and global data continues to be written. The call is ignored if no experiment is active or if data recording is already stopped. This function stops the writing of all event-specific data even if it is enabled for specific threads by the collector_thread_resume() function.

• C, C++, Fortran: collector_resume()

  Java: CollectorAPI.resume()

  Resume writing event-specific data to the experiment after a call to collector_pause() . The call is ignored if no experiment is active or if data recording is active.

• C and C++ only: collector_thread_pause(unsigned int t)

  Java: CollectorAPI.threadPause(Thread t)

  Stop writing event-specific data from the thread specified in the argument list to the experiment. The argument t is the POSIX thread identifier for C/C++ programs and a Java thread for Java programs. 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. This function stops the writing of data from the specified thread even if the writing of data is globally enabled. By default, recording of data for individual threads is turned on.

• C and C++ only: collector_thread_resume(unsigned int t)

  Java: CollectorAPI.threadResume(Thread t)

  Resume writing event-specific data from the thread specified in the argument list to the experiment. The argument t is the POSIX thread identifier for C/C++ programs and a Java thread for Java programs. 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. Data is written to the experiment only if the writing of data is globally enabled as well as enabled for the thread.

• C, C++, Fortran: collector_terminate_expt()

  Java: CollectorAPI.terminate

  Terminate the experiment whose data is being collected. No further data is collected, but the program continues to run normally. The call is ignored if no experiment is active.