You can use Quantify's API functions to fine-tune data collection. For example, to record only the cost of the last call to the testPutHash routine in the example testHash program, you can embed the quantify_stop_recording_system_calls and quantify_stop_recording_data functions in the program code:
ADD SAMPLE
After embedding Quantify API functions in your code, you must recompile the program.
Look at the program summary to see the results of the quantify_stop_recording_system_calls and quantify_stop_recording_data calls. Quantify reports only the Time in your code, the code executed by the testPutHash call.
The call graph for this run includes the calling functions of testPutHash. This is because Quantify distributes time to the calling functions, even if they contributed no time themselves.
The functions that are called after the call to testPutHash are also recorded, even though these functions contribute no time. Although Quantify does not record timing data after you call quantify_stop_collecting_data, it still tracks the function calls. This is so that if you decide to start recording data at a later point, Quantify can distribute that time correctly to the calling functions from that point on.
You can also run the testHash program under a debugger and place a breakpoint on the testPutHash line. When the program reaches the breakpoint, call the functions quantify_stop_recording_system_calls and quantify_clear_data from the debugger. Use next to step the program over the call to testPutHash and call quantify_stop_collecting_data or quantify_save_data and continue.
See "Calling API functions from your program" on page A-9.
API functions are useful when used with run-time options: The run-time options specify the initial recording state only; the API functions called during the execution of the program can change that state as desired.
You can call the API functions as often as you want. The overhead of using Quantify's data collection API functions is negligible. A common Quantify practice in X Windows applications or other programs that use an event-driven architecture is to place a call to quantify_start_recording_data at the beginning of a callback function, and a call to quantify_stop_recording_data at the end of the callback function. Then run the Quantify'd application with -record-data=no, or place a call to quantify_clear_data before the program enters the main event loop. In the final dataset, Quantify reports the accumulated times recorded for exactly the callback(s) of interest.
You can add annotation strings to saved data files in order to distinguish between different data files and to record special data-collection circumstances, such as high network traffic or the use of special data files.
Use the API function quantify_add_annotation to add an annotation string to the next binary data file saved using quantify_save_data, quantify_save_data_to_file, or program exit. You can add as many annotations to a dataset as you want. You can also add annotations to an existing binary data file using the qv option -add-annotation. For example:
% qv -add-annotation="Run to collect dynamic library data" \
testHash.pure.dynamic.5172.0.qv
Quantify automatically adds an annotation indicating the type of machine on which the data was collected. If a fatal signal is received without a user-defined signal handler, Quantify automatically saves the data to that point in the run and adds an annotation indicating the type of signal received.
To view the annotations in a data file, use the qv option -print-annotations. For example: