数据收集的程序控制

如果要控制程序中的数据收集，收集器共享库 libcollector.so 包含了一些可以使用的 API 函数。这些函数是用 C 编写的，还提供了一个 Fortran 接口。C 接口和 Fortran 接口都是在由库所提供的头文件中定义的。

API 函数定义如下所示。

void collector_sample(char *name);
void collector_pause(void);
void collector_resume(void);
void collector_thread_pause(unsigned int t);
void collector_thread_resume(unsigned int t);
void collector_terminate_expt(void);

CollectorAPI 类为 Java^TM 程序提供了类似的功能，Java 接口中对其进行了介绍。

C 和 C++ 接口

可通过两种方法来访问 C 和 C++ 接口：

• 第一种方法是包括 collectorAPI.h 并使用 -lcollectorAPI（包含用于检查底层 libcollector.so API 函数是否存在的真正的函数）进行链接。

  这种方法要求与 API 库相链接，可在所有情况下使用。如果没有活动的实验，API 调用将被忽略。

• 第二种方法是包括 libcollector.h（包含用于检查基础 libcollector.so API 函数是否存在的宏）。

  当用于主可执行文件以及数据收集功能随程序一起启动时，该方法有效。当 dbx 用于附加到进程或者从进程针对其执行 dlopen 的共享库中使用时，该方法不总是有效。提供第二种方法的目的仅在于实现向后兼容，建议不要将它用于任何其他目的。

  ---

  注 –

  请勿使用 -lcollector 链接任何语言的程序，否则，收集器可能会出现不可预知的行为。

  ---

Fortran 接口

Fortran API libfcollector.h 文件定义了库的 Fortran 接口。要使用该库，必须使用 -lcollectorAPI 链接应用程序。（还提供了该库的替代名称 -lfcollector，目的在于实现向后兼容性。）除动态函数、线程暂停和恢复调用等功能外，Fortran API 提供了与 C 和 C++ API 相同的功能。

要使用 Fortran 的 API 函数，请插入下面的语句：

include "libfcollector.h"

请勿使用 -lcollector 链接任何语言的程序，否则，收集器可能会出现不可预知的行为。

Java 接口

使用以下语句导入 CollectorAPI 类并访问 Java API。但是请注意，必须使用指向 / installation_directory/lib/collector.jar 的类路径来调用应用程序，其中 installation-directory 是 Sun Studio 软件的安装目录。

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

Java CollectorAPI 方法的定义如下所示：

CollectorAPI.sample(String name)
CollectorAPI.pause()
CollectorAPI.resume()
CollectorAPI.threadPause(Thread thread)
CollectorAPI.threadResume(Thread thread)
CollectorAPI.terminate()

除动态函数 API 之外，Java API 包含与 C 和 C++ API 相同的函数。

C 头文件 libcollector.h 包含一些宏，这些宏的作用是如果当时未在收集数据，则跳过对真正的 API 函数的调用。在这种情况下，不动态装入函数。但是，由于在某些情况下这些宏不能很好地运行，所以使用这些宏会有风险。使用 collectorAPI.h 较为安全，因为它不使用宏，而是直接引用函数。

如果正在收集性能数据，则 Fortran API 子例程会调用 C API 函数，否则这些子例程将返回。检查的开销很低，不会对程序性能产生太大的影响。

如本章稍后所述，要收集性能数据就必须使用收集器运行您的程序。插入对 API 函数的调用不会启用数据收集功能。

如果要在多线程程序中使用 API 函数，应当确保它们只由一个线程调用。除 collector_thread_pause() 和 collector_thread_resume() 之外，API 函数执行适用于进程（而不是单独的线程）的操作。如果每个线程都调用 API 函数，则记录的数据可能会与预期不同。例如，如果一个线程在其他线程到达程序中的同一点之前调用了 collector_pause() 或 collector_terminate_expt()，则会针对所有线程暂停或终止收集，从而丢失那些正在执行 API 调用之前代码的线程的数据。要在单独的线程级别控制数据收集，请使用 collector_thread_pause() 和 collector_thread_resume() 函数。可通过两种方法来使用这些函数：一种是使用一个主线程为所有线程（包括其自身）执行调用；另一种是让每个线程只执行它自己的调用。其他任何用法都可能产生不可预知的结果。