Task API

A task is a logical unit of work performed by a particular thread. Tasks can nest; thus, tasks typically correspond to functions, scopes, or a case block in a switch statement. You can use the Task API to assign tasks to threads.

Task API is a per-thread function that works in resumed state. This function does not work in paused state.

The Task API does not enable a thread to suspend the current task and switch to a different task (task switching), or move a task to a different thread (task stealing).

A task instance represents a piece of work performed by a particular thread for a period of time. The task is defined by the bracketing of __itt_task_begin() and __itt_task_end() on the same thread.

Use This Primitive

To Do This

void __itt_task_begin (const __itt_domain *domain,__itt_id taskid, __itt_id parentid, __itt_string_handle *name)

Create a task instance on a thread. This becomes the current task instance for that thread. A call to __itt_task_end() on the same thread ends the current task instance.




The domain for this task



This parameter is reserved and should be __itt_null



The parent instance to which this task belongs, or __itt_null



The name of this task

void __itt_task_end (const __itt_domain *domain)

Traces the end of the current task.



The domain for this task


To be able to see user tasks in your results, enable the Analyze user tasks checkbox in analysis settings.

ITTAPI__itt_task_* Function Parameters

The following table defines the parameters used in the Task API primitives.




The domain of the task.

__itt_id taskid

This is a reserved parameter.

__itt_id parentid

This is a reserved parameter.


The task string handle.

Enable Task APIs

The following steps are required to begin using task APIs:

  1. Include ittnotify.h header.
  2. Create domain and string handles for your tasks.
  3. Insert task begin and task end marks in your code.
  4. Link to libittnotify.lib (Windows*) or libittnotify.a (Linux*).
  5. Enable the Analyze user tasks, events, and counters option before profiling. For more information, see Task Analysis topic.

Usage Example

The following code snippet creates a domain and a couple of tasks at global scope.

#include "ittnotify.h"

void do_foo(double seconds);

__itt_domain* domain = __itt_domain_create("MyTraces.MyDomain");
__itt_string_handle* shMyTask = __itt_string_handle_create("My Task");
__itt_string_handle* shMySubtask = __itt_string_handle_create("My SubTask");

void BeginFrame() {
     __itt_task_begin(domain, __itt_null, __itt_null, shMyTask);

void DoWork() {
     __itt_task_begin(domain, __itt_null, __itt_null, shMySubtask);
void EndFrame() {

int main() {
    return 0;

#ifdef _WIN32
#include <ctime>

void do_foo(double seconds) {
    clock_t goal = (clock_t)((double)clock() + seconds * CLOCKS_PER_SEC);
    while (goal > clock());
#include <time.h>

#define NSEC 1000000000
#define TYPE long

void do_foo(double sec) {
      struct timespec start_time;
      struct timespec current_time;

      clock_gettime(CLOCK_REALTIME, &start_time);
      while(1) {
          clock_gettime(CLOCK_REALTIME, &current_time);
          TYPE cur_nsec=(long)((current_time.tv_sec-start_time.tv_sec-sec)*NSEC + current_time.tv_nsec - start_time.tv_nsec);
For more complete information about compiler optimizations, see our Optimization Notice.
Select sticky button color: 
Orange (only for download buttons)