update the sample with more usage examples

Author: eparshut

cpp/README.md

@@ -124,7 +124,7 @@ Lightweight wrapper around `__itt_string_handle*`.
 ```cpp
 ittapi::StringHandle h{"my_handle"};
 h.valid();           // true if handle was created
-h.native_handle();   // underlying __itt_string_handle*
+h.get();   // underlying __itt_string_handle*
 ```
 
 #### `ittapi::Domain`
@@ -170,7 +170,7 @@ RAII wrapper for region begin/end.
 RAII wrapper for frame begin/end. Supports explicit timestamp submission.
 
 ```cpp
-ittapi::ScopedFrame::submit(domain.native_handle(), begin_ts, end_ts);
+ittapi::ScopedFrame::submit(domain.get(), begin_ts, end_ts);
 ```
 
 #### `ittapi::ScopedPause`

cpp/include/ittapi_domain.hpp

@@ -33,7 +33,7 @@ class Domain
     }
 #endif
 
-    __itt_domain* native_handle() const noexcept
+    __itt_domain* get() const noexcept
     {
         return m_domain;
     }
@@ -119,12 +119,12 @@ class Domain
 
     void task_begin(const StringHandle& name) const noexcept
     {
-        __itt_task_begin(m_domain, detail::make_null_id(), detail::make_null_id(), name.native_handle());
+        __itt_task_begin(m_domain, detail::make_null_id(), detail::make_null_id(), name.get());
     }
 
     void task_begin(const StringHandle& name, __itt_id taskid, __itt_id parentid) const noexcept
     {
-        __itt_task_begin(m_domain, taskid, parentid, name.native_handle());
+        __itt_task_begin(m_domain, taskid, parentid, name.get());
     }
 
     void task_end() const noexcept

cpp/include/ittapi_region.hpp

@@ -65,7 +65,7 @@ class ScopedRegion
         , m_id(detail::make_null_id())
         , m_active(true)
     {
-        __itt_region_begin(m_domain, m_id, detail::make_null_id(), name.native_handle());
+        __itt_region_begin(m_domain, m_id, detail::make_null_id(), name.get());
     }
 
     ScopedRegion(const __itt_domain* domain, const StringHandle& name,
@@ -74,7 +74,7 @@ class ScopedRegion
         , m_id(id)
         , m_active(true)
     {
-        __itt_region_begin(m_domain, m_id, parentid, name.native_handle());
+        __itt_region_begin(m_domain, m_id, parentid, name.get());
     }
 
     ScopedRegion(const ScopedRegion&) = delete;

cpp/include/ittapi_string_handle.hpp

@@ -29,7 +29,7 @@ class StringHandle
     }
 #endif
 
-    __itt_string_handle* native_handle() const noexcept
+    __itt_string_handle* get() const noexcept
     {
         return m_handle;
     }

cpp/include/ittapi_task.hpp

@@ -60,15 +60,15 @@ class ScopedTask
         : m_domain(domain)
         , m_active(true)
     {
-        __itt_task_begin(m_domain, detail::make_null_id(), detail::make_null_id(), name.native_handle());
+        __itt_task_begin(m_domain, detail::make_null_id(), detail::make_null_id(), name.get());
     }
 
     ScopedTask(const __itt_domain* domain, const StringHandle& name,
                __itt_id taskid, __itt_id parentid) noexcept
         : m_domain(domain)
         , m_active(true)
     {
-        __itt_task_begin(m_domain, taskid, parentid, name.native_handle());
+        __itt_task_begin(m_domain, taskid, parentid, name.get());
     }
 
     ScopedTask(const ScopedTask&) = delete;

cpp/samples/task_sample.cpp

@@ -8,25 +8,84 @@
 #include <chrono>
 #include <thread>
 
+static void simulate_work(int ms)
+{
+    std::this_thread::sleep_for(std::chrono::milliseconds(ms));
+}
+
 int main()
 {
+    // Thread naming
     ittapi::set_thread_name("main");
-    ittapi::Domain domain{"example.task"};
+
+    // Domain and string handle creation
+    ittapi::Domain domain{"example.app"};
     ittapi::StringHandle task_name{"process"};
 
+    // Collection control — pause/resume
     ittapi::pause();
     ittapi::resume();
 
-
+    // Scoped task with pre-created StringHandle (zero-overhead path)
     {
         auto task = domain.task(task_name);
-        std::this_thread::sleep_for(std::chrono::milliseconds(10));
+        simulate_work(10);
     }
 
-
+    // Scoped task with inline string (convenience path)
     {
         auto task = domain.task("startup");
-        std::this_thread::sleep_for(std::chrono::milliseconds(10));
+        simulate_work(10);
+    }
+
+    // Scoped task with early end
+    {
+        auto task = domain.task("partial_work");
+        simulate_work(5);
+        task.end();  // end early, destructor is a no-op
+    }
+
+    // Scoped task with IDs for parent-child relationships
+    {
+        __itt_id parent_id = __itt_id_make(nullptr, 1);
+        auto parent = domain.task("parent_task", parent_id, __itt_null);
+
+        __itt_id child_id = __itt_id_make(nullptr, 2);
+        auto child = domain.task("child_task", child_id, parent_id);
+        simulate_work(5);
+    }
+
+    // Manual task begin/end (non-RAII)
+    domain.task_begin("manual_work");
+    simulate_work(5);
+    domain.task_end();
+
+    // Scoped region
+    {
+        auto region = domain.region("init_phase");
+        simulate_work(10);
+    }
+
+    // Scoped frame
+    {
+        auto frame = domain.frame();
+        simulate_work(10);
+    }
+
+    // Frame submit with explicit timestamps
+    {
+        __itt_timestamp begin = __itt_get_timestamp();
+        simulate_work(10);
+        __itt_timestamp end = __itt_get_timestamp();
+        ittapi::ScopedFrame::submit(domain.get(), begin, end);
+    }
+
+    // Scoped pause — collection paused within scope
+    {
+        ittapi::ScopedPause sp;
+        simulate_work(10);  // not collected
+        sp.resume_now();    // resume early
+        simulate_work(10);  // collected
     }
 
     return 0;

cpp/tests/test_frame.cpp

@@ -46,7 +46,7 @@ static void test_submit()
 {
     ittapi::Domain d{"test.frame.submit"};
     // Just verify it compiles and runs without a collector
-    ittapi::ScopedFrame::submit(d.native_handle(), 0, 100);
+    ittapi::ScopedFrame::submit(d.get(), 0, 100);
 }
 
 int main()

cpp/tests/test_helpers.hpp

@@ -52,20 +52,20 @@ namespace test
 
 inline void check_domain_name(const Domain& domain, const char* expected)
 {
-    if (domain.native_handle() == nullptr)
+    if (domain.get() == nullptr)
     {
         return; // no collector attached — nothing to verify
     }
-    CHECK_STR_EQ(domain.native_handle()->nameA, expected);
+    CHECK_STR_EQ(domain.get()->nameA, expected);
 }
 
 inline void check_string_handle_name(const StringHandle& handle, const char* expected)
 {
-    if (handle.native_handle() == nullptr)
+    if (handle.get() == nullptr)
     {
         return; // no collector attached — nothing to verify
     }
-    CHECK_STR_EQ(handle.native_handle()->strA, expected);
+    CHECK_STR_EQ(handle.get()->strA, expected);
 }
 
 inline void check_id_fields(const __itt_id& id,

docs/src/itt-api-cpp-wrapper.rst

@@ -154,8 +154,8 @@ Lightweight wrapper around ``__itt_string_handle*``.
 .. code-block:: cpp
 
    ittapi::StringHandle h{"my_handle"};
-   h.valid();           // true if handle was created
-   h.native_handle();   // underlying __itt_string_handle*
+   h.valid(); // true if handle was created
+   h.get();   // underlying __itt_string_handle*
 
 ittapi::Domain
 """"""""""""""
@@ -205,7 +205,7 @@ RAII wrapper for frame begin/end. Supports explicit timestamp submission.
 
 .. code-block:: cpp
 
-   ittapi::ScopedFrame::submit(domain.native_handle(), begin_ts, end_ts);
+   ittapi::ScopedFrame::submit(domain.get(), begin_ts, end_ts);
 
 ittapi::ScopedPause
 """""""""""""""""""