Adding Basic Intel® ITT Instrumentation to Your Application

The Intel® GPA Platform Analyzer is an instrumentation-based tool. It obtains its data from gpa_trace files, which are generated by Intel® GPA while profiling an application that has been instrumented with ITT API calls.

To get started, you will need to use the following API calls:

• __itt_domain_create(): Creates a domain required in most Intel ITT API calls. You need to define at least one domain.
• __itt_string_handle_create(): Creates string handles for identifying your tasks. String handles are more efficient for identifying traces than strings.
• __itt_task_begin(): Marks the beginning of a task.
• __itt_task_end(): Marks the end of a task.

The following sample shows how these four basic Intel ITT API functions are used in a multi threaded application.

#include <windows.h>

#include <ittnotify.h>

// Forward declaration of a thread function.

DWORD WINAPI workerthread(LPVOID);

bool g_done = false;

// Create a domain that is visible globally: we will use it in our example.

__itt_domain* domain = __itt_domain_create(“Example.Domain.Global”);

// Create string handles which associates with the “main” task.

__itt_string_handle* handle_main = __itt_string_handle_create(“main”);

__itt_string_handle* handle_exe_name = __itt_string_handle_create(“ExeName”);

__itt_string_handle* handle_createthread = __itt_string_handle_create(“CreateThread”);

void main(int, char* argv[])

{

// Create a task associated with the “main” routine.

__itt_task_begin(domain, __itt_null, __itt_null, handle_main);

// Save the name of the app’s exe that we can show when analyzing traces.

__itt_metadata_str_add(domain, __itt_null, handle_exe_name, argv[0], 0);

// Now we’ll create 4 worker threads

for (int i = 0; i < 4; i++)

{

// We might be curious about the cost of CreateThread. We add tracing to do the measurement.

__itt_task_begin(domain, __itt_null, __itt_null, handle_createthread);

::CreateThread(NULL, 0, workerthread, (LPVOID)i, 0, NULL);

__itt_task_end(domain);

}

// Wait a while,…

::Sleep(5000);

g_done = true;

// Mark the end of the main task

__itt_task_end(domain);

}

// Create string handle for the work task.

__itt_string_handle* handle_work = __itt_string_handle_create(“work”);

DWORD WINAPI workerthread(LPVOID data)

{

// Set the name of this thread so it shows  up in the UI as something meaningful

char threadname[32];

wsprintf(threadname, “Worker Thread %d”, data);

__itt_thread_set_name(threadname);

// Each worker thread does some number of “work” tasks

while(!g_done)

{

__itt_task_begin(domain, __itt_null, __itt_null, handle_work);

::Sleep(150);

__itt_task_end(domain);

}

return 0;

}

See Also

__itt_domain_create
__itt_string_handle_create
__itt_task_begin
__itt_task_end

Adding Basic Intel® ITT Instrumentation to Your Application