User Guide

  • 2020
  • 06/18/2020
  • Public Content
Contents

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
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.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); 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

Product and Performance Information

1

Intel's compilers may or may not optimize to the same degree for non-Intel microprocessors for optimizations that are not unique to Intel microprocessors. These optimizations include SSE2, SSE3, and SSSE3 instruction sets and other optimizations. Intel does not guarantee the availability, functionality, or effectiveness of any optimization on microprocessors not manufactured by Intel. Microprocessor-dependent optimizations in this product are intended for use with Intel microprocessors. Certain optimizations not specific to Intel microarchitecture are reserved for Intel microprocessors. Please refer to the applicable product User and Reference Guides for more information regarding the specific instruction sets covered by this notice.

Notice revision #20110804