数据收集的程序控制

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

API 函数定义如下所示。

void collector_sample(char *name);
void collector_pause(void);
void collector_resume(void);
void collector_terminate_expt(void);

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

C 和 C++ 接口

可以通过包括 collectorAPI.h 并与 -lcollectorAPI（包含用于检查底层 libcollector.so API 函数是否存在的实际函数）相链接来访问收集器 API 的 C 和 C++ 接口。

如果没有活动的实验，API 调用将被忽略。

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 是 Oracle Solaris Studio 软件的安装目录。

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

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

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

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

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

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

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

如果要在多线程程序中使用 API 函数，应当确保它们只由一个线程调用。API 函数执行适用于进程（而不是单独的线程）的操作。如果每个线程都调用 API 函数，则记录的数据可能会与预期不同。例如，如果一个线程在其他线程到达程序中的同一点之前调用了 collector_pause() 或 collector_terminate_expt()，则会针对所有线程暂停或终止收集，从而丢失那些正在执行 API 调用之前代码的线程的数据。