Intel® VTune™ Amplifier XE and Intel® VTune™ Amplifier for Systems Help

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.

Parameters:

[in]

domain

The domain for this task

[in]

taskid

This parameter is reserved and should be __itt_null

[in]

parentid

The parent instance to which this task belongs, or __itt_null

[in]

name

The name of this task

void __itt_task_end (const __itt_domain *domain)

Traces the end of the current task.

[in]

domain

The domain for this task

Note

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.

Parameter

Description

__itt_domain

The domain of the task.

__itt_id taskid

This is a reserved parameter.

__itt_id parentid

This is a reserved parameter.

__itt_string_handle

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.a.
  5. Enable the Analyze user tasks, events, and counters option before profiling. For more information, see Tasks.

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);
     do_foo(1);
}

void DoWork() {
     __itt_task_begin(domain, __itt_null, __itt_null, shMySubtask);
     do_foo(1);
     __itt_task_end(domain);
}
void EndFrame() {
     do_foo(1);
     __itt_task_end(domain);
}

int main() {
    BeginFrame();
    DoWork();
    EndFrame();
    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());
}
#else
#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);
          if(cur_nsec>=0)
                break;
      }
}
#endif

See Also