Collection Control API

Use Collection Control APIs in your code to manage how and when Intel® VTune™ Profiler collects data for your applications. By calling these APIs, you can pause, resume, or detach data collection to focus analysis on specific code regions, reduce profiling overhead, or exclude unimportant sections from your performance results.

Use This Primitive

To Do This

 
void __itt_pause(void)

Run the application without collecting data. VTune Profiler reduces the overhead of collection by collecting only critical information, like thread and process creation.

 
void __itt_resume(void)

Resume data collection.

 
void __itt_detach(void)

Detach data collection. VTune Profiler detaches all collectors from all processes. Your application continues to work but no data is collected for the running collection.

Pause data collection

When you pause the data collection in any thread, you pause the collection for the entire program and not just the active thread. Also, pausing a data collection can reduce the overhead from runtime analysis.

Unaffected APIs:

  • Domain API

  • String Handle API

  • Thread Naming API

Affected APIs (No Data Collection in Paused State):

  • Task API

  • Frame API

  • Event API

  • User-Defined Synchronization API

Note

The Pause/Resume API call frequency is about 1Hz for a reasonable rate. Since this operation pauses and resumes data collection in all processes in the analysis run with the corresponding collection state notification sent to the GUI, for small workloads, do not call this operation on a frequent basis. Use Frame APIs instead.

Usage Example: Focus on a Specific Code Section

In this code example, the pause/resume calls help to focus data collection from a specific section of code. The application run begins when the collection is paused.

int main(int argc, char* argv[])
{
  // Do initialization work here
  __itt_resume();
    // Do profiling work here
  __itt_pause();
  // Do finalization work here
  return 0;
}

Usage Example: Hide Sections of Code

This example shows how you use pause/resume calls to hide intensive work that may not need attention for a brief period.

int main(int argc, char* argv[])
{
  // Do work here
  __itt_pause();
  // Do uninteresting work here
  __itt_resume();
  // Do work here
  __itt_detach();
  // Do uninteresting work here
  return 0;
}