Getting started

So, let's begin!

1. Make sure you have python, cmake and compiler environment on your computer.

2. Clone/Download Intel® Single Event API (Intel® SEAPI) source code

3. Get to the Intel® SEAPI root folder and build everything up with: python ./buildall.py

4. Add mark up to your code:

   a) For pure C project use itt_notify: https://software.intel.com/en-us/node/544201

   b) For C++ application itt_notify.hpp is at your service (described below)

5. Link your project with ittnotify library from bin folder

6. See README.txt for details on profiling under different tools

C++ mark up:

ITT_FUNCTION_TASK() - put this macro at the very beginning of your function and the time of this function will be measured

ITT_ARG(name, value) - this macro can be used to add arguments of the function - numeric and string arguments are supported

ITT_SCOPE_TASK(name) - if you need to measure a scope of execution, you can measure it giving name, ITT_ARG will work as well

ITT_SCOPE_REGION(name) - region (or frame) can be used for 'meta' tasks, in some viewers they will have different from tasks representation

ITT_MARKER(name, scope) - an event without duration, usually drawn as vertical line, scopes are: scope_global (over whole timeline), scope_process (over current process), scope_thread (only in current thread lane) Exception is 'scope_task' - shown as task on separate lane that lasts until next 'Task' marker from this thread

ITT_COUNTER(name, value) - Allows to draw overtime graphs

Simple example:

#include "itt_notify.hpp"

ITT_DOMAIN("my_domain");

void MyFn(int a, std::string b)
{
    ITT_FUNCTION_TASK();
    ITT_ARG("a", a);
    ITT_ARG("b", b);

    for (size_t i = 0; i < 5; ++i)
    {
        ITT_SCOPE_TASK("Loop");
        ITT_ARG("i", i);

        ITT_COUNTER("i", i);
    }
    
    ITT_MARKER("broke out of loop", scope_thread);
}

More examples can be found here: https://github.com/01org/IntelSEAPI/blob/master/main.cpp

Java mark up:

void taskBegin(String name, long id, long parent) - To mark the start time of a task.

void taskEnd() - End of the task. Ends must form proper stack with Begins.

void marker(String text, Scope scope, long timestamp, long id) - An event without duration, usually drawn as vertical line, scopes are: Global (over whole timeline), Process (over current process), Thread (only in current thread lane) Exception is 'Task' - shown as task on separate lane that lasts until next 'Task' marker from this thread

id & parent arguments are optional everywhere, leave 0 unless you want to link events together

void counter(String name, double value, long timestamp) - Allows to draw overtime graphs

timestamp allows handling external source of events. When zero, the event takes the time of the call

void taskSubmit(String name, long timestamp, long dur, long id, long parent) - Allows streaming tasks from external source

void track(String group, String name) - All events (of current thread) after this call are attributed to pseudo process with name 'group' and pseudo thread named 'name'. 'group == null' leaves events attributed to calling process. But 'name' is mandatory.

void track() restores attribution to normal

Example can be found here: https://github.com/01org/IntelSEAPI/blob/master/java/IntelSEAPI.java

Python mark up:

def counter(self, name, value, timestamp = 0) - Allows to draw overtime graphs

def task(self, name, id = 0, parent = 0) - for 'with' statement - defines scope of the task

def marker(self, text, scope = scope_process, timestamp = 0, id = 0) - an event without duration, usually drawn as vertical line, scopes are: scope_global (over whole timeline), scope_process (over current process), scope_thread (only in current thread lane) Exception is 'scope_task' - shown as task on separate lane that lasts until next 'Task' marker from this thread

id & parent arguments allow linking events together

timestamp allows handling external source of events. When zero, the event takes the time of the call

def task_submit(self, name, timestamp, dur, id = 0, parent = 0) - Allows streaming tasks from external source

def track(self, group, name) - for 'with' statement. All events (of current thread) inside this scope are attributed to pseudo process with name 'group' and pseudo thread named 'name'. 'group == None' leaves events attributed to calling process. But 'name' is mandatory.

Example is here: https://github.com/01org/IntelSEAPI/blob/master/runtool/sea.py