src/itt-api-cpp-wrapper.html - external/github.com/intel/ittapi - Git at Google



 <!DOCTYPE html>
 <html class="writer-html5" lang="en" data-content_root="../">
 <head>
   <meta charset="utf-8" /><meta name="viewport" content="width=device-width, initial-scale=1" />

   <meta name="viewport" content="width=device-width, initial-scale=1.0" />
   <title>ITT API C++ Wrapper &mdash; ITT/JIT APIs Documentation  documentation</title>
       <link rel="stylesheet" type="text/css" href="../_static/pygments.css?v=80d5e7a1" />
       <link rel="stylesheet" type="text/css" href="../_static/css/theme.css?v=9edc463e" />


     <link rel="canonical" href="https://intel.github.io/ittapi/src/itt-api-cpp-wrapper.html" />
       <script src="../_static/jquery.js?v=5d32c60e"></script>
       <script src="../_static/_sphinx_javascript_frameworks_compat.js?v=2cd50e6c"></script>
       <script src="../_static/documentation_options.js?v=5929fcd5"></script>
       <script src="../_static/doctools.js?v=fd6eb6e6"></script>
       <script src="../_static/sphinx_highlight.js?v=6ffebe34"></script>
     <script src="../_static/js/theme.js"></script>
     <link rel="index" title="Index" href="../genindex.html" />
     <link rel="search" title="Search" href="../search.html" />
     <link rel="next" title="ITT API Reference Collector" href="ref_collector.html" />
     <link rel="prev" title="iJIT GetNewMethodID" href="jitapi/ijit_-getnewmethodid.html" />
 </head>

 <body class="wy-body-for-nav">
   <div class="wy-grid-for-nav">
     <nav data-toggle="wy-nav-shift" class="wy-nav-side">
       <div class="wy-side-scroll">
         <div class="wy-side-nav-search" >


           <a href="../index.html" class="icon icon-home">
             ITT/JIT APIs Documentation
           </a>
 <div role="search">
   <form id="rtd-search-form" class="wy-form" action="../search.html" method="get">
     <input type="text" name="q" placeholder="Search docs" aria-label="Search docs" />
     <input type="hidden" name="check_keywords" value="yes" />
     <input type="hidden" name="area" value="default" />
   </form>
 </div>
         </div><div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="Navigation menu">
               <p class="caption" role="heading"><span class="caption-text">Contents:</span></p>
 <ul class="current">
 <li class="toctree-l1"><a class="reference internal" href="overview.html">Overview</a></li>
 <li class="toctree-l1"><a class="reference internal" href="build.html">Build from Source Code</a></li>
 <li class="toctree-l1 current"><a class="reference internal" href="api-support.html">Use the ITT/JIT APIs</a><ul class="current">
 <li class="toctree-l2"><a class="reference internal" href="api-support.html#c-c-api-usage-and-reference">C/C++ API Usage and Reference:</a></li>
 <li class="toctree-l2 current"><a class="reference internal" href="api-support.html#other-language-api-bindings">Other Language API Bindings:</a><ul class="current">
 <li class="toctree-l3 current"><a class="current reference internal" href="#">ITT API C++ Wrapper</a><ul>
 <li class="toctree-l4"><a class="reference internal" href="#supported-apis">Supported APIs</a></li>
 <li class="toctree-l4"><a class="reference internal" href="#requirements">Requirements</a></li>
 <li class="toctree-l4"><a class="reference internal" href="#including-the-wrapper">Including the Wrapper</a></li>
 <li class="toctree-l4"><a class="reference internal" href="#example-task-instrumentation">Example: Task Instrumentation</a></li>
 <li class="toctree-l4"><a class="reference internal" href="#linking">Linking</a></li>
 <li class="toctree-l4"><a class="reference internal" href="#building-with-cmake">Building with CMake</a></li>
 <li class="toctree-l4"><a class="reference internal" href="#running-tests">Running Tests</a></li>
 <li class="toctree-l4"><a class="reference internal" href="#performance-tips">Performance Tips</a></li>
 <li class="toctree-l4"><a class="reference internal" href="#api-reference">API Reference</a></li>
 </ul>
 </li>
 <li class="toctree-l3"><a class="reference external" href="https://docs.rs/ittapi/latest/ittapi">Rust ITT API Bindings</a></li>
 <li class="toctree-l3"><a class="reference external" href="https://pypi.org/project/ittapi">Python ITT API Bindings</a></li>
 </ul>
 </li>
 </ul>
 </li>
 <li class="toctree-l1"><a class="reference internal" href="ref_collector.html">ITT API Reference Collector</a></li>
 <li class="toctree-l1"><a class="reference external" href="https://github.com/intel/ittapi">GitHub Project</a></li>
 </ul>

         </div>
       </div>
     </nav>

     <section data-toggle="wy-nav-shift" class="wy-nav-content-wrap"><nav class="wy-nav-top" aria-label="Mobile navigation menu" >
           <i data-toggle="wy-nav-top" class="fa fa-bars"></i>
           <a href="../index.html">ITT/JIT APIs Documentation</a>
       </nav>

       <div class="wy-nav-content">
         <div class="rst-content style-external-links">
           <div role="navigation" aria-label="Page navigation">
   <ul class="wy-breadcrumbs">
       <li><a href="../index.html" class="icon icon-home" aria-label="Home"></a></li>
           <li class="breadcrumb-item"><a href="api-support.html">Use the ITT/JIT APIs</a></li>
       <li class="breadcrumb-item active">ITT API C++ Wrapper</li>
       <li class="wy-breadcrumbs-aside">
             <a href="../_sources/src/itt-api-cpp-wrapper.rst.txt" rel="nofollow"> View page source</a>
       </li>
   </ul>
   <hr/>
 </div>
           <div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
            <div itemprop="articleBody">

   <section id="itt-api-c-wrapper">
 <span id="itt-api-cpp-wrapper"></span><h1>ITT API C++ Wrapper<a class="headerlink" href="#itt-api-c-wrapper" title="Link to this heading"></a></h1>
 <p>A modern, header-only C++ wrapper for the <a class="reference external" href="https://github.com/intel/ittapi">ITT API</a>
 instrumentation library. The wrapper provides RAII-based scoped helpers and type-safe
 C++ abstractions over the existing C API.</p>
 <section id="supported-apis">
 <h2>Supported APIs<a class="headerlink" href="#supported-apis" title="Link to this heading"></a></h2>
 <table class="docutils align-default">
 <colgroup>
 <col style="width: 30.0%" />
 <col style="width: 70.0%" />
 </colgroup>
 <thead>
 <tr class="row-odd"><th class="head"><p>API</p></th>
 <th class="head"><p>C++ Wrapper</p></th>
 </tr>
 </thead>
 <tbody>
 <tr class="row-even"><td><p>String Handle</p></td>
 <td><p><code class="docutils literal notranslate"><span class="pre">ittapi::StringHandle</span></code></p></td>
 </tr>
 <tr class="row-odd"><td><p>Domain</p></td>
 <td><p><code class="docutils literal notranslate"><span class="pre">ittapi::Domain</span></code></p></td>
 </tr>
 <tr class="row-even"><td><p>Task</p></td>
 <td><p><code class="docutils literal notranslate"><span class="pre">ittapi::ScopedTask</span></code>, <code class="docutils literal notranslate"><span class="pre">Domain::task_begin()</span></code> / <code class="docutils literal notranslate"><span class="pre">Domain::task_end()</span></code></p></td>
 </tr>
 <tr class="row-odd"><td><p>Region</p></td>
 <td><p><code class="docutils literal notranslate"><span class="pre">ittapi::ScopedRegion</span></code></p></td>
 </tr>
 <tr class="row-even"><td><p>Frame</p></td>
 <td><p><code class="docutils literal notranslate"><span class="pre">ittapi::ScopedFrame</span></code></p></td>
 </tr>
 <tr class="row-odd"><td><p>Collection Control</p></td>
 <td><p><code class="docutils literal notranslate"><span class="pre">ittapi::pause()</span></code>, <code class="docutils literal notranslate"><span class="pre">ittapi::resume()</span></code>, <code class="docutils literal notranslate"><span class="pre">ittapi::ScopedPause</span></code></p></td>
 </tr>
 <tr class="row-even"><td><p>Thread Naming</p></td>
 <td><p><code class="docutils literal notranslate"><span class="pre">ittapi::set_thread_name()</span></code></p></td>
 </tr>
 </tbody>
 </table>
 </section>
 <section id="requirements">
 <h2>Requirements<a class="headerlink" href="#requirements" title="Link to this heading"></a></h2>
 <ul class="simple">
 <li><p>C++17 or later</p></li>
 <li><p>The existing <code class="docutils literal notranslate"><span class="pre">ittnotify</span></code> static C-library</p></li>
 </ul>
 </section>
 <section id="including-the-wrapper">
 <h2>Including the Wrapper<a class="headerlink" href="#including-the-wrapper" title="Link to this heading"></a></h2>
 <p>Use the umbrella header to get the full API:</p>
 <div class="highlight-cpp notranslate"><div class="highlight"><pre><span></span><span class="cp">#include</span><span class="w"> </span><span class="cpf">&lt;ittapi.hpp&gt;</span>
 </pre></div>
 </div>
 <p>Or include individual headers:</p>
 <div class="highlight-cpp notranslate"><div class="highlight"><pre><span></span><span class="cp">#include</span><span class="w"> </span><span class="cpf">&lt;ittapi_domain.hpp&gt;</span>
 <span class="cp">#include</span><span class="w"> </span><span class="cpf">&lt;ittapi_task.hpp&gt;</span>
 <span class="cp">#include</span><span class="w"> </span><span class="cpf">&lt;ittapi_collection_control.hpp&gt;</span>
 </pre></div>
 </div>
 </section>
 <section id="example-task-instrumentation">
 <h2>Example: Task Instrumentation<a class="headerlink" href="#example-task-instrumentation" title="Link to this heading"></a></h2>
 <div class="highlight-cpp notranslate"><div class="highlight"><pre><span></span><span class="cp">#include</span><span class="w"> </span><span class="cpf">&lt;ittapi.hpp&gt;</span>

 <span class="cp">#include</span><span class="w"> </span><span class="cpf">&lt;chrono&gt;</span>
 <span class="cp">#include</span><span class="w"> </span><span class="cpf">&lt;thread&gt;</span>

 <span class="kt">int</span><span class="w"> </span><span class="nf">main</span><span class="p">()</span><span class="w"> </span><span class="p">{</span>
 <span class="w">    </span><span class="n">ittapi</span><span class="o">::</span><span class="n">set_thread_name</span><span class="p">(</span><span class="s">&quot;main&quot;</span><span class="p">);</span>
 <span class="w">    </span><span class="n">ittapi</span><span class="o">::</span><span class="n">Domain</span><span class="w"> </span><span class="n">domain</span><span class="p">{</span><span class="s">&quot;example.task&quot;</span><span class="p">};</span>
 <span class="w">    </span><span class="n">ittapi</span><span class="o">::</span><span class="n">StringHandle</span><span class="w"> </span><span class="n">task_name</span><span class="p">{</span><span class="s">&quot;process&quot;</span><span class="p">};</span>

 <span class="w">    </span><span class="n">ittapi</span><span class="o">::</span><span class="n">pause</span><span class="p">();</span>
 <span class="w">    </span><span class="n">ittapi</span><span class="o">::</span><span class="n">resume</span><span class="p">();</span>

 <span class="w">    </span><span class="p">{</span>
 <span class="w">        </span><span class="k">auto</span><span class="w"> </span><span class="n">task</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">domain</span><span class="p">.</span><span class="n">task</span><span class="p">(</span><span class="n">task_name</span><span class="p">);</span>
 <span class="w">        </span><span class="n">std</span><span class="o">::</span><span class="n">this_thread</span><span class="o">::</span><span class="n">sleep_for</span><span class="p">(</span><span class="n">std</span><span class="o">::</span><span class="n">chrono</span><span class="o">::</span><span class="n">milliseconds</span><span class="p">(</span><span class="mi">10</span><span class="p">));</span>
 <span class="w">    </span><span class="p">}</span>

 <span class="w">    </span><span class="k">return</span><span class="w"> </span><span class="mi">0</span><span class="p">;</span>
 <span class="p">}</span>
 </pre></div>
 </div>
 </section>
 <section id="linking">
 <h2>Linking<a class="headerlink" href="#linking" title="Link to this heading"></a></h2>
 <section id="cmake-consumer">
 <h3>CMake Consumer<a class="headerlink" href="#cmake-consumer" title="Link to this heading"></a></h3>
 <div class="highlight-cmake notranslate"><div class="highlight"><pre><span></span><span class="nb">find_package</span><span class="p">(</span><span class="s">ittapi</span><span class="w"> </span><span class="s">CONFIG</span><span class="w"> </span><span class="s">REQUIRED</span><span class="p">)</span>
 <span class="nb">target_link_libraries</span><span class="p">(</span><span class="s">my_app</span><span class="w"> </span><span class="s">PRIVATE</span><span class="w"> </span><span class="s">ittapi::cxx</span><span class="p">)</span>
 </pre></div>
 </div>
 <p>The <code class="docutils literal notranslate"><span class="pre">ittapi::cxx</span></code> target is an <code class="docutils literal notranslate"><span class="pre">INTERFACE</span></code> library that transitively links the
 existing <code class="docutils literal notranslate"><span class="pre">ittnotify</span></code> static library and adds the C++ wrapper include directories.</p>
 </section>
 <section id="manual-gcc-g-linux">
 <h3>Manual GCC/G++ (Linux)<a class="headerlink" href="#manual-gcc-g-linux" title="Link to this heading"></a></h3>
 <div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>g++<span class="w"> </span>-std<span class="o">=</span>c++17<span class="w"> </span>-O2<span class="w"> </span><span class="se">\</span>
 <span class="w">    </span>-I&lt;ittapi-install-prefix&gt;/include<span class="w"> </span><span class="se">\</span>
 <span class="w">    </span>app.cpp<span class="w"> </span><span class="se">\</span>
 <span class="w">    </span>&lt;ittapi-install-prefix&gt;/lib/libittnotify.a<span class="w"> </span><span class="se">\</span>
 <span class="w">    </span>-ldl<span class="w"> </span>-pthread<span class="w"> </span><span class="se">\</span>
 <span class="w">    </span>-o<span class="w"> </span>app
 </pre></div>
 </div>
 </section>
 </section>
 <section id="building-with-cmake">
 <h2>Building with CMake<a class="headerlink" href="#building-with-cmake" title="Link to this heading"></a></h2>
 <p>From the repository root:</p>
 <div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>cmake<span class="w"> </span>-B<span class="w"> </span>build<span class="w"> </span>-DCMAKE_BUILD_TYPE<span class="o">=</span>Release<span class="w"> </span>-DITT_API_CPP_SUPPORT<span class="o">=</span>ON
 cmake<span class="w"> </span>--build<span class="w"> </span>build
 </pre></div>
 </div>
 <p>The <code class="docutils literal notranslate"><span class="pre">ITT_API_CPP_SUPPORT</span></code> option is <code class="docutils literal notranslate"><span class="pre">OFF</span></code> by default.</p>
 <p>You can also build with the build script:</p>
 <div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>python<span class="w"> </span>buildall.py<span class="w"> </span>--cpp
 </pre></div>
 </div>
 </section>
 <section id="running-tests">
 <h2>Running Tests<a class="headerlink" href="#running-tests" title="Link to this heading"></a></h2>
 <p>Tests are registered inside the <code class="docutils literal notranslate"><span class="pre">cpp/</span></code> subdirectory. After building:</p>
 <div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>ctest<span class="w"> </span>--test-dir<span class="w"> </span>build/cpp<span class="w"> </span>--output-on-failure
 </pre></div>
 </div>
 </section>
 <section id="performance-tips">
 <h2>Performance Tips<a class="headerlink" href="#performance-tips" title="Link to this heading"></a></h2>
 <ul>
 <li><p><strong>Pre-create</strong> <code class="docutils literal notranslate"><span class="pre">StringHandle</span></code> <strong>objects</strong> for task/region names used in hot paths.
 The <code class="docutils literal notranslate"><span class="pre">StringHandle</span></code> overloads pass a raw pointer with no locking — this is the
 zero-overhead path.</p>
 <div class="highlight-cpp notranslate"><div class="highlight"><pre><span></span><span class="c1">// Do this once at startup:</span>
 <span class="n">ittapi</span><span class="o">::</span><span class="n">StringHandle</span><span class="w"> </span><span class="n">name</span><span class="p">{</span><span class="s">&quot;compute&quot;</span><span class="p">};</span>

 <span class="c1">// Then in hot code:</span>
 <span class="k">auto</span><span class="w"> </span><span class="n">task</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">domain</span><span class="p">.</span><span class="n">task</span><span class="p">(</span><span class="n">name</span><span class="p">);</span><span class="w">  </span><span class="c1">// no allocation, no lock</span>
 </pre></div>
 </div>
 </li>
 <li><p><strong>The</strong> <code class="docutils literal notranslate"><span class="pre">string_view</span></code> <strong>overloads</strong> are convenient but allocate a <code class="docutils literal notranslate"><span class="pre">std::string</span></code>
 on cache miss and acquire a lock in the C library. Use them for setup or infrequent
 tasks, not tight loops.</p></li>
 <li><p><strong>Create</strong> <code class="docutils literal notranslate"><span class="pre">Domain</span></code> <strong>objects once</strong> and reuse them. Domain creation is a global
 lookup — store them as class members or globals, not as function locals called
 repeatedly.</p></li>
 <li><p><strong>Use overlapped tasks</strong> (with IDs) only when you need tasks that end out of order.
 Stack-based tasks (without IDs) are simpler and carry less internal state.</p></li>
 </ul>
 </section>
 <section id="api-reference">
 <h2>API Reference<a class="headerlink" href="#api-reference" title="Link to this heading"></a></h2>
 <section id="free-functions">
 <h3>Free Functions<a class="headerlink" href="#free-functions" title="Link to this heading"></a></h3>
 <ul class="simple">
 <li><p><code class="docutils literal notranslate"><span class="pre">ittapi::pause()</span></code> — Pause collection.</p></li>
 <li><p><code class="docutils literal notranslate"><span class="pre">ittapi::resume()</span></code> — Resume collection.</p></li>
 <li><p><code class="docutils literal notranslate"><span class="pre">ittapi::set_thread_name(std::string_view</span> <span class="pre">name)</span></code> — Set the current thread’s name.</p></li>
 </ul>
 </section>
 <section id="classes">
 <h3>Classes<a class="headerlink" href="#classes" title="Link to this heading"></a></h3>
 <section id="ittapi-stringhandle">
 <h4>ittapi::StringHandle<a class="headerlink" href="#ittapi-stringhandle" title="Link to this heading"></a></h4>
 <p>Lightweight wrapper around <code class="docutils literal notranslate"><span class="pre">__itt_string_handle*</span></code>.</p>
 <div class="highlight-cpp notranslate"><div class="highlight"><pre><span></span><span class="n">ittapi</span><span class="o">::</span><span class="n">StringHandle</span><span class="w"> </span><span class="n">h</span><span class="p">{</span><span class="s">&quot;my_handle&quot;</span><span class="p">};</span>
 <span class="n">h</span><span class="p">.</span><span class="n">valid</span><span class="p">();</span><span class="w"> </span><span class="c1">// true if handle was created</span>
 <span class="n">h</span><span class="p">.</span><span class="n">get</span><span class="p">();</span><span class="w">   </span><span class="c1">// underlying __itt_string_handle*</span>
 </pre></div>
 </div>
 </section>
 <section id="ittapi-domain">
 <h4>ittapi::Domain<a class="headerlink" href="#ittapi-domain" title="Link to this heading"></a></h4>
 <p>Lightweight wrapper around <code class="docutils literal notranslate"><span class="pre">__itt_domain*</span></code> with convenience factories.</p>
 <div class="highlight-cpp notranslate"><div class="highlight"><pre><span></span><span class="n">ittapi</span><span class="o">::</span><span class="n">Domain</span><span class="w"> </span><span class="n">d</span><span class="p">{</span><span class="s">&quot;my.domain&quot;</span><span class="p">};</span>
 <span class="k">auto</span><span class="w"> </span><span class="n">task</span><span class="w">   </span><span class="o">=</span><span class="w"> </span><span class="n">d</span><span class="p">.</span><span class="n">task</span><span class="p">(</span><span class="s">&quot;task_name&quot;</span><span class="p">);</span><span class="w">     </span><span class="c1">// returns ScopedTask (RAII)</span>
 <span class="k">auto</span><span class="w"> </span><span class="n">region</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">d</span><span class="p">.</span><span class="n">region</span><span class="p">(</span><span class="s">&quot;region_name&quot;</span><span class="p">);</span><span class="w"> </span><span class="c1">// returns ScopedRegion</span>
 <span class="k">auto</span><span class="w"> </span><span class="n">frame</span><span class="w">  </span><span class="o">=</span><span class="w"> </span><span class="n">d</span><span class="p">.</span><span class="n">frame</span><span class="p">();</span><span class="w">               </span><span class="c1">// returns ScopedFrame</span>

 <span class="n">d</span><span class="p">.</span><span class="n">task_begin</span><span class="p">(</span><span class="s">&quot;work&quot;</span><span class="p">);</span><span class="w">                  </span><span class="c1">// manual task begin (simple stack-based)</span>
 <span class="n">d</span><span class="p">.</span><span class="n">task_end</span><span class="p">();</span><span class="w">                          </span><span class="c1">// manual task end</span>

 <span class="n">__itt_id</span><span class="w"> </span><span class="n">id</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">__itt_id_make</span><span class="p">(</span><span class="k">nullptr</span><span class="p">,</span><span class="w"> </span><span class="mi">1</span><span class="p">);</span>
 <span class="n">d</span><span class="p">.</span><span class="n">task_begin</span><span class="p">(</span><span class="s">&quot;overlapped&quot;</span><span class="p">,</span><span class="w"> </span><span class="n">id</span><span class="p">,</span><span class="w"> </span><span class="n">__itt_null</span><span class="p">);</span><span class="w">  </span><span class="c1">// manual task begin (overlapped)</span>
 <span class="n">d</span><span class="p">.</span><span class="n">task_end</span><span class="p">(</span><span class="n">id</span><span class="p">);</span><span class="w">                              </span><span class="c1">// manual task end by ID</span>
 </pre></div>
 </div>
 </section>
 <section id="ittapi-scopedtask">
 <h4>ittapi::ScopedTask<a class="headerlink" href="#ittapi-scopedtask" title="Link to this heading"></a></h4>
 <p>RAII wrapper for task begin/end. Use <code class="docutils literal notranslate"><span class="pre">domain.overlapped_task()</span></code> to create
 an overlapped task (tasks that can end in any order). Each overlapped task
 instance gets a unique <code class="docutils literal notranslate"><span class="pre">__itt_id</span></code> derived from its object address. The
 <code class="docutils literal notranslate"><span class="pre">id()</span></code> method returns this ID.</p>
 <div class="highlight-cpp notranslate"><div class="highlight"><pre><span></span><span class="c1">// Simple task</span>
 <span class="p">{</span>
 <span class="w">    </span><span class="k">auto</span><span class="w"> </span><span class="n">task</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">domain</span><span class="p">.</span><span class="n">task</span><span class="p">(</span><span class="s">&quot;work&quot;</span><span class="p">);</span>
 <span class="w">    </span><span class="c1">// ... do work ...</span>
 <span class="w">    </span><span class="n">task</span><span class="p">.</span><span class="n">end</span><span class="p">();</span><span class="w">     </span><span class="c1">// optional early end (idempotent)</span>
 <span class="p">}</span><span class="w">                   </span><span class="c1">// destructor ends task if still active</span>
 </pre></div>
 </div>
 <p>Overlapped tasks — use <code class="docutils literal notranslate"><span class="pre">overlapped_task()</span></code>, optionally pass a parent ID:</p>
 <div class="highlight-cpp notranslate"><div class="highlight"><pre><span></span><span class="p">{</span>
 <span class="w">    </span><span class="k">auto</span><span class="w"> </span><span class="n">parent</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">domain</span><span class="p">.</span><span class="n">overlapped_task</span><span class="p">(</span><span class="s">&quot;parent&quot;</span><span class="p">);</span><span class="w">               </span><span class="c1">// overlapped, no parent</span>
 <span class="w">    </span><span class="k">auto</span><span class="w"> </span><span class="n">child</span><span class="w">  </span><span class="o">=</span><span class="w"> </span><span class="n">domain</span><span class="p">.</span><span class="n">overlapped_task</span><span class="p">(</span><span class="s">&quot;child&quot;</span><span class="p">,</span><span class="w"> </span><span class="n">parent</span><span class="p">.</span><span class="n">id</span><span class="p">());</span><span class="w">   </span><span class="c1">// overlapped, child of parent</span>

 <span class="w">    </span><span class="n">parent</span><span class="p">.</span><span class="n">end</span><span class="p">();</span><span class="w">  </span><span class="c1">// end parent while child is still running</span>
 <span class="p">}</span><span class="w">                  </span><span class="c1">// child ends here via destructor</span>
 </pre></div>
 </div>
 <p>Overlapped tasks with explicit IDs (advanced):</p>
 <div class="highlight-cpp notranslate"><div class="highlight"><pre><span></span><span class="p">{</span>
 <span class="w">    </span><span class="n">__itt_id</span><span class="w"> </span><span class="n">parent_id</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">__itt_id_make</span><span class="p">(</span><span class="k">nullptr</span><span class="p">,</span><span class="w"> </span><span class="mi">1</span><span class="p">);</span>
 <span class="w">    </span><span class="k">auto</span><span class="w"> </span><span class="n">parent</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">domain</span><span class="p">.</span><span class="n">task</span><span class="p">(</span><span class="s">&quot;parent&quot;</span><span class="p">,</span><span class="w"> </span><span class="n">parent_id</span><span class="p">,</span><span class="w"> </span><span class="n">__itt_null</span><span class="p">);</span>

 <span class="w">    </span><span class="n">__itt_id</span><span class="w"> </span><span class="n">child_id</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">__itt_id_make</span><span class="p">(</span><span class="k">nullptr</span><span class="p">,</span><span class="w"> </span><span class="mi">2</span><span class="p">);</span>
 <span class="w">    </span><span class="k">auto</span><span class="w"> </span><span class="n">child</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">domain</span><span class="p">.</span><span class="n">task</span><span class="p">(</span><span class="s">&quot;child&quot;</span><span class="p">,</span><span class="w"> </span><span class="n">child_id</span><span class="p">,</span><span class="w"> </span><span class="n">parent_id</span><span class="p">);</span>

 <span class="w">    </span><span class="n">parent</span><span class="p">.</span><span class="n">end</span><span class="p">();</span><span class="w">  </span><span class="c1">// end parent while child is still running</span>
 <span class="p">}</span><span class="w">                  </span><span class="c1">// child ends here via destructor</span>
 </pre></div>
 </div>
 <p>For manual (non-RAII) control:</p>
 <div class="highlight-cpp notranslate"><div class="highlight"><pre><span></span><span class="n">domain</span><span class="p">.</span><span class="n">task_begin</span><span class="p">(</span><span class="s">&quot;work&quot;</span><span class="p">);</span>
 <span class="c1">// ... do work ...</span>
 <span class="n">domain</span><span class="p">.</span><span class="n">task_end</span><span class="p">();</span>

 <span class="c1">// Or with overlapped tasks:</span>
 <span class="n">__itt_id</span><span class="w"> </span><span class="n">id</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">__itt_id_make</span><span class="p">(</span><span class="k">nullptr</span><span class="p">,</span><span class="w"> </span><span class="mi">1</span><span class="p">);</span>
 <span class="n">domain</span><span class="p">.</span><span class="n">task_begin</span><span class="p">(</span><span class="s">&quot;overlapped_work&quot;</span><span class="p">,</span><span class="w"> </span><span class="n">id</span><span class="p">,</span><span class="w"> </span><span class="n">__itt_null</span><span class="p">);</span>
 <span class="c1">// ... do work ...</span>
 <span class="n">domain</span><span class="p">.</span><span class="n">task_end</span><span class="p">(</span><span class="n">id</span><span class="p">);</span>
 </pre></div>
 </div>
 </section>
 <section id="ittapi-scopedregion">
 <h4>ittapi::ScopedRegion<a class="headerlink" href="#ittapi-scopedregion" title="Link to this heading"></a></h4>
 <p>RAII wrapper for region begin/end.</p>
 </section>
 <section id="ittapi-scopedframe">
 <h4>ittapi::ScopedFrame<a class="headerlink" href="#ittapi-scopedframe" title="Link to this heading"></a></h4>
 <p>RAII wrapper for frame begin/end. Supports explicit timestamp submission.</p>
 <div class="highlight-cpp notranslate"><div class="highlight"><pre><span></span><span class="n">ittapi</span><span class="o">::</span><span class="n">ScopedFrame</span><span class="o">::</span><span class="n">submit</span><span class="p">(</span><span class="n">domain</span><span class="p">.</span><span class="n">get</span><span class="p">(),</span><span class="w"> </span><span class="n">begin_ts</span><span class="p">,</span><span class="w"> </span><span class="n">end_ts</span><span class="p">);</span>
 </pre></div>
 </div>
 </section>
 <section id="ittapi-scopedpause">
 <h4>ittapi::ScopedPause<a class="headerlink" href="#ittapi-scopedpause" title="Link to this heading"></a></h4>
 <p>RAII wrapper for pause/resume. Constructor pauses, destructor resumes.</p>
 <div class="highlight-cpp notranslate"><div class="highlight"><pre><span></span><span class="p">{</span>
 <span class="w">    </span><span class="n">ittapi</span><span class="o">::</span><span class="n">ScopedPause</span><span class="w"> </span><span class="n">sp</span><span class="p">;</span>
 <span class="w">    </span><span class="c1">// collection is paused</span>
 <span class="w">    </span><span class="n">sp</span><span class="p">.</span><span class="n">resume_now</span><span class="p">();</span><span class="w">  </span><span class="c1">// optional early resume</span>
 <span class="p">}</span>
 </pre></div>
 </div>
 </section>
 </section>
 </section>
 </section>


            </div>
           </div>
           <footer><div class="rst-footer-buttons" role="navigation" aria-label="Footer">
         <a href="jitapi/ijit_-getnewmethodid.html" class="btn btn-neutral float-left" title="iJIT GetNewMethodID" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a>
         <a href="ref_collector.html" class="btn btn-neutral float-right" title="ITT API Reference Collector" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right" aria-hidden="true"></span></a>
     </div>

   <hr/>

   <div role="contentinfo">
     <p>&#169; Copyright 2026 Intel Corporation.</p>
   </div>

   Built with <a href="https://www.sphinx-doc.org/">Sphinx</a> using a
     <a href="https://github.com/readthedocs/sphinx_rtd_theme">theme</a>
     provided by <a href="https://readthedocs.org">Read the Docs</a>.


 </footer>
         </div>
       </div>
     </section>
   </div>
   <script>
       jQuery(function () {
           SphinxRtdTheme.Navigation.enable(true);
       });
   </script>

 </body>
 </html>