ittapi

https://docs.rs/ittapi/
Admin
This library allows Rust programs to use Intel® Instrumentation and Tracing Technology (ITT) APIs,...
Tokens:49,417
Snippets:573
Trust Score:9.1
Update:3 months ago
Show doc for...
Tokens:
Raw
### Example Search Queries

Source: https://docs.rs/ittapi/0.5.0/ittapi/jit/struct.MethodLoad.html?search=

Illustrative examples of search queries that can be performed.

```rust
std::vec
```

```rust
u32 -> bool
```

```rust
Option<T>, (T -> U) -> Option<U>
```

--------------------------------

### Starting an Event

Source: https://docs.rs/ittapi/0.5.0/src/ittapi/event.rs.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Shows how to initiate an event using the `start` method. This method returns a `StartedEvent` guard, which ensures the event is properly ended when it goes out of scope. Panics if the ITT library fails to start the event.

```rust
let _started_event = event.start();
```

--------------------------------

### Event Usage Example

Source: https://docs.rs/ittapi/0.5.0/ittapi/struct.Event.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Demonstrates the basic usage of the Event struct, including creating an event and starting a span for work.

```APIDOC
## Event Usage Example

### Description
This example shows how to instantiate an `Event` and use its `start` method to create a span for a block of work. The event is automatically stopped when the `span` goes out of scope.

### Code
```rust
let event = ittapi::Event::new("foo");
{
  let span = event.start();
  // do some work...
  // ...the event is stopped when `span` is dropped
}
```
```

--------------------------------

### Starting a Task

Source: https://docs.rs/ittapi/0.5.0/ittapi/struct.Task.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Starts a new task on the current thread. It requires a reference to a Domain and a value that can be converted into a StringHandle.

```rust
pub fn begin(domain: &'a Domain, name: impl Into<StringHandle>) -> Self
```

--------------------------------

### Task::begin

Source: https://docs.rs/ittapi/0.5.0/ittapi/struct.Task.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Starts a new task on the current thread, allowing for measurement of work performed.

```APIDOC
## Task::begin

### Description
Start a task on the current thread.

### Method
`pub fn begin(domain: &'a Domain, name: impl Into<StringHandle>) -> Self`

### Parameters
* `domain`: A reference to the `Domain` the task belongs to.
* `name`: The name of the task, which can be a `StringHandle` or any type that can be converted into one.
```

--------------------------------

### Event::start

Source: https://docs.rs/ittapi/0.5.0/ittapi/struct.Event.html?search=

Starts the event, returning a StartedEvent. This method will panic if the ITT library is unable to start the event.

```APIDOC
## Event::start

### Description
Starts the event and returns a `StartedEvent` guard. The event is automatically stopped when the `StartedEvent` guard is dropped.

### Method
`&self.start() -> StartedEvent`

### Panics
This will panic if the ITT library cannot start the event.

### Example
```rust
let event = ittapi::Event::new("foo");
{
  let span = event.start();
  // do some work...
  // ...the event is stopped when `span` is dropped
}
```
```

--------------------------------

### Task::begin

Source: https://docs.rs/ittapi/0.5.0/ittapi/struct.Task.html?search=

Starts a new task on the current thread, associating it with a domain and a name. The name can be provided as an owned StringHandle or a string slice.

```APIDOC
## Task::begin

### Description
Starts a task on the current thread.

### Signature
`pub fn begin(domain: &'a Domain, name: impl Into<StringHandle>) -> Self`

### Parameters
* **domain**: A reference to the `Domain` the task belongs to.
* **name**: The name of the task, which can be converted into a `StringHandle`.
```

--------------------------------

### Creating and Using an Event

Source: https://docs.rs/ittapi/0.5.0/src/ittapi/event.rs.html?search=u32+-%3E+bool

Demonstrates how to create a new event with a given name and use a span to automatically start and stop the event.

```rust
let event = ittapi::Event::new("foo");
{
  let span = event.start();
  // do some work...
  // ...the event is stopped when `span` is dropped
}

```

--------------------------------

### Event::start Function

Source: https://docs.rs/ittapi/0.5.0/ittapi/struct.Event.html?search=u32+-%3E+bool

Starts the event and returns a `StartedEvent` span. This method will panic if the ITT library fails to start the event.

```rust
pub fn start(&self) -> StartedEvent
```

--------------------------------

### Initialize and use Jit for Method Load

Source: https://docs.rs/ittapi/0.5.0/src/ittapi/jit.rs.html?search=

Demonstrates creating a Jit instance, getting a MethodId, building MethodLoad event data, and notifying the event. Assumes single-threaded access.

```rust
use anyhow::Context;
use std::{ffi::CString, os, ptr};

// Assume MethodId, MethodLoadBuilder, MethodLoad, and ittapi_sys are defined elsewhere
// For demonstration purposes, let's mock them:
struct MethodId(u32);
impl MethodId {
    fn new() -> Self { MethodId(0) } // Mock ID
}
struct MethodLoadBuilder;
impl MethodLoadBuilder {
    fn new() -> Self { MethodLoadBuilder }
    fn build(&self, _method_id: MethodId) -> anyhow::Result<EventType> {
        // Mock implementation
        Ok(EventType::MethodLoadFinished(MethodLoad(0)))
    }
}
struct MethodLoad(u32);

struct Jit {
    shutdown_complete: bool,
}

enum EventType {
    MethodLoadFinished(MethodLoad),
    Shutdown,
}
impl EventType {
    fn tag(&self) -> u32 { 0 } // Mock tag
    fn data(&mut self) -> *mut os::raw::c_void { ptr::null_mut() } // Mock data
}

mod ittapi_sys {
    pub const iJIT_jvm_event_iJVM_EVENT_TYPE_METHOD_LOAD_FINISHED: u32 = 1;
    pub const iJIT_jvm_event_iJVM_EVENT_TYPE_SHUTDOWN: u32 = 2;
    pub fn iJIT_GetNewMethodID() -> u32 { 123 }
    pub fn iJIT_NotifyEvent(_tag: u32, _data: *mut std::os::raw::c_void) -> i32 { 1 }
}

impl Jit {
    pub fn new() -> Self { Jit { shutdown_complete: false } }
    pub fn get_method_id(&self) -> MethodId {
        MethodId(unsafe { ittapi_sys::iJIT_GetNewMethodID() })
    }
    pub fn notify_event(&self, mut event: EventType) -> anyhow::Result<()> {
        let tag = event.tag();
        let data = event.data();
        let res = unsafe { ittapi_sys::iJIT_NotifyEvent(tag, data) };
        match event {
            EventType::MethodLoadFinished(_) => Ok(()),
            EventType::Shutdown => {
                if res == 1 { Ok(()) } else { anyhow::bail!("error") }
            }
        }
    }
    pub fn load_method(&self, builder: MethodLoadBuilder) -> anyhow::Result<()> {
        let method_id = self.get_method_id();
        let method_load = builder.build(method_id)?;
        self.notify_event(method_load)
    }
    pub fn shutdown(&mut self) -> anyhow::Result<()> {
        if self.shutdown_complete { return Ok(()); }
        let res = self.notify_event(EventType::Shutdown);
        if res.is_ok() { self.shutdown_complete = true; }
        res
    }
}

fn main() -> anyhow::Result<()> {
    let jit = Jit::new();
    let builder = MethodLoadBuilder;
    jit.load_method(builder)?;
    println!("Method loaded successfully.");
    Ok(())
}

```

--------------------------------

### Task::begin

Source: https://docs.rs/ittapi/0.5.0/ittapi/struct.Task.html?search=std%3A%3Avec

Starts a new task on the current thread, allowing for measurement of work units. It can be initialized with a pre-defined StringHandle for efficiency or a string reference for convenience.

```APIDOC
## Task::begin

### Description
Starts a task on the current thread.

### Method
`pub fn begin(domain: &'a Domain, name: impl Into<StringHandle>) -> Self`

### Parameters
* **domain** (`&'a Domain`) - The domain to which the task belongs.
* **name** (`impl Into<StringHandle>`) - The name of the task, which can be provided as a StringHandle or a type that can be converted into one.

### Returns
`Self` - An instance of the Task struct representing the started task.
```

--------------------------------

### Event::start

Source: https://docs.rs/ittapi/0.5.0/ittapi/struct.Event.html?search=std%3A%3Avec

Starts an event, returning a `StartedEvent` guard. The event is automatically stopped when this guard is dropped.

```APIDOC
## Event::start

### Description
Starts the event. The returned `StartedEvent` acts as a guard, and the event will be automatically stopped when this guard goes out of scope.

### Method
`pub fn start(&self) -> StartedEvent`

### Return Value
Returns a `StartedEvent` object which manages the event's lifecycle.

### Panics
This will panic if the ITT library cannot start the event.
```

--------------------------------

### Event::start

Source: https://docs.rs/ittapi/0.5.0/ittapi/struct.Event.html?search=u32+-%3E+bool

Starts an event, returning a `StartedEvent` guard. The event is automatically stopped when the guard is dropped.

```APIDOC
## Event::start

### Description
Starts the event and returns a `StartedEvent` guard. The event is automatically stopped when this guard is dropped.

### Method
`pub fn start(&self) -> StartedEvent`

### Panics
This will panic if the ITT library cannot start the event.

### Example
```rust
let event = ittapi::Event::new("work_event");
{
  let span = event.start();
  // do some work...
  // ...the event is stopped when `span` is dropped
}
```
```

--------------------------------

### Start an Event

Source: https://docs.rs/ittapi/0.5.0/src/ittapi/event.rs.html?search=

Starts an ITT event, returning a `StartedEvent` guard. This function will panic if the ITT library fails to start the event. The event is automatically ended when the `StartedEvent` guard is dropped.

```rust
pub fn start(&self) -> StartedEvent {
    if let Some(start_fn) = unsafe { ittapi_sys::__itt_event_start_ptr__3_0 } {
        let result = unsafe { start_fn(self.0) };
        assert!(result == 0, "unable to start event");
    }
    StartedEvent { event: self.0 }
}
```

--------------------------------

### Event::start

Source: https://docs.rs/ittapi/0.5.0/ittapi/struct.Event.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Starts the event, returning a StartedEvent guard. The event is automatically stopped when the guard is dropped. Panics if the ITT library fails to start the event.

```APIDOC
## Event::start

### Description
Starts the event and returns a guard that manages its lifecycle. The event is automatically stopped when this guard is dropped.

### Signature
`pub fn start(&self) -> StartedEvent`

### Panics
This will panic if the ITT library cannot start the event.
```

--------------------------------

### Task::begin

Source: https://docs.rs/ittapi/0.5.0/src/ittapi/task.rs.html

Starts a new task on the current thread within a specified domain. Tasks represent logical units of work and can be identified by a string name or a pre-initialized StringHandle.

```APIDOC
## Task::begin

### Description
Starts a task on the current thread within a specified domain. The task can be identified by a string reference or a `StringHandle`.

### Method

```rust
pub fn begin<'a>(domain: &'a Domain, name: impl Into<StringHandle>) -> Self
```

### Parameters

- **domain** (`&'a Domain`): A reference to the `Domain` to which this task belongs.
- **name** (`impl Into<StringHandle>`): The name of the task, which can be provided as a string slice or a `StringHandle`.

### Returns

- `Self`: An instance of `Task` representing the newly started task.
```

--------------------------------

### Event::start

Source: https://docs.rs/ittapi/0.5.0/ittapi/struct.Event.html

Starts the event, returning a `StartedEvent` guard. The event is automatically stopped when this guard goes out of scope.

```APIDOC
## pub fn start(&self) -> StartedEvent

### Description
Starts the event and returns a `StartedEvent` object. This object acts as a guard; when it is dropped, the event is automatically stopped, recording its duration.

### Returns
A `StartedEvent` object that manages the event's lifecycle.

### Panics
This will panic if the ITT library cannot start the event.
```

--------------------------------

### StartedEvent

Source: https://docs.rs/ittapi/0.5.0/ittapi/struct.StartedEvent.html?search=u32+-%3E+bool

Represents a started event, allowing for automatic cleanup when it goes out of scope.

```APIDOC
## Struct StartedEvent

### Description
Contains the information about a started event. Allows for the drop implementation to end the event when it goes out of scope.

### Methods
#### `fn end(self)`
End the event.
```

--------------------------------

### Task Begin Function

Source: https://docs.rs/ittapi/0.5.0/src/ittapi/task.rs.html?search=

Starts a task on the current thread. It uses the `__itt_task_begin_ptr__3_0` function pointer to initiate the task. Note that `taskid` and `parentid` are currently unimplemented.

```rust
pub fn begin(domain: &'a Domain, name: impl Into<StringHandle>) -> Self {
    if let Some(create_fn) = unsafe { ittapi_sys::__itt_task_begin_ptr__3_0 } {
        // Currently the `taskid` and `parentid` parameters are unimplemented (TODO).
        unsafe { create_fn(domain.as_ptr(), ITT_NULL, ITT_NULL, name.into().as_ptr()) };
    }
    Self(domain)
}
```

--------------------------------

### Task::begin

Source: https://docs.rs/ittapi/0.5.0/ittapi/struct.Task.html

Starts a new task on the current thread. Tasks can be measured using pre-initialized string handles for efficiency or string references for convenience. Tasks are automatically ended when they are dropped.

```APIDOC
## Task::begin

### Description
Starts a task on the current thread.

### Method
```
pub fn begin(domain: &'a Domain, name: impl Into<StringHandle>) -> Self
```

### Parameters
* **domain** (`&'a Domain`) - The domain to associate the task with.
* **name** (`impl Into<StringHandle>`) - The name of the task.

### Returns
A new `Task` instance representing the started task.
```

--------------------------------

### Event Tracking

Source: https://docs.rs/ittapi/0.5.0/src/ittapi/lib.rs.html?search=

APIs for creating and managing instrumentation events, including started events.

```APIDOC
## Event

### Description
Represents an instrumentation event. This is a basic event type.

### Method
`Event::new(domain: &Domain, name: &str) -> Event`

### Endpoint
N/A (Struct and Constructor)

### Parameters
* **domain** (`&Domain`) - Required - The domain to which this event belongs.
* **name** (str) - Required - The name of the event.

### Request Example
```rust
let my_domain = ittapi::Domain::new("MyDomain");
let my_event = ittapi::Event::new(&my_domain, "MyEvent");
```

### Response
An `Event` object.

## StartedEvent

### Description
Represents an instrumentation event that has been started. Typically used for timing or tracking the duration of an operation.

### Method
`StartedEvent::new(domain: &Domain, name: &str) -> StartedEvent`

### Endpoint
N/A (Struct and Constructor)

### Parameters
* **domain** (`&Domain`) - Required - The domain to which this event belongs.
* **name** (str) - Required - The name of the event.

### Request Example
```rust
let my_domain = ittapi::Domain::new("MyDomain");
let started_event = ittapi::StartedEvent::new(&my_domain, "MyOperation");
// ... perform operation ...
// The event is implicitly ended when `started_event` goes out of scope.
```

### Response
A `StartedEvent` object.
```

--------------------------------

### MethodLoadBuilder::new

Source: https://docs.rs/ittapi/0.5.0/ittapi/jit/struct.MethodLoadBuilder.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Creates a new MethodLoadBuilder. `addr` is the pointer to the start of the code region, and `len` is the size of this code region in bytes.

```APIDOC
## MethodLoadBuilder::new

### Description
Creates a new `MethodLoadBuilder` from scratch.
`addr` is the pointer to the start of the code region, `len` is the size of this code region in bytes.

### Signature
`pub fn new(method_name: String, addr: *const u8, len: usize) -> Self`
```

--------------------------------

### Event::new

Source: https://docs.rs/ittapi/0.5.0/ittapi/struct.Event.html?search=std%3A%3Avec

Creates a new event with a given name. This method is essential for initializing an event before it can be started.

```APIDOC
## Event::new

### Description
Creates the event with the specified name.

### Method
`pub fn new(name: &str) -> Self`

### Parameters
* **name** (`&str`) - The name of the event.

### Panics
Panics if the name contains a `0` byte or if its size will not fit in a 32-bit representation.
```

--------------------------------

### Task::begin and Task::end

Source: https://docs.rs/ittapi/0.5.0/src/ittapi/task.rs.html?search=std%3A%3Avec

This section describes how to start and end a task using the Task API. Tasks represent logical units of work and can be measured using either a pre-initialized StringHandle or a string reference.

```APIDOC
## Task API

### Description

The `Task` struct represents a logical unit of work performed by a particular thread. It provides methods to begin and end a task, allowing for measurement and profiling of code segments.

### Methods

#### `Task::begin(domain: &'a Domain, name: impl Into<StringHandle>) -> Self`

Starts a task on the current thread.

- **domain** (&'a Domain): A reference to the domain the task belongs to.
- **name** (impl Into<StringHandle>): The name of the task, which can be provided as a `StringHandle` or a type that can be converted into one.

Returns a `Task` instance representing the started task.

#### `Task::end(self)`

Finishes the currently running task. This method is typically called implicitly when the `Task` instance is dropped, but can also be called explicitly.

### Usage Examples

```rust
# use ittapi::{Domain, StringHandle, Task};
# let _env_path = scoped_env::ScopedEnv::set("INTEL_LIBITTNOTIFY64", "<some path>");
// Measure a task using a pre-initialized string handle (most efficient).
{
    let domain = Domain::new("domain");
    let name = StringHandle::new("task");
    let task = Task::begin(&domain, name);
    let _ = 2 + 2;
    task.end(); // Task ended here.
    let _ = 3 + 3;
}

// Measure a task using a string reference (most convenient).
{
    let domain = Domain::new("domain");
    let _task = Task::begin(&domain, "task");
    let _ = 2 + 2;
    // Task ended here, when dropped.
}
```

### Drop Implementation

The `Task` struct implements the `Drop` trait, which automatically calls the task ending function when the `Task` instance goes out of scope. This ensures that tasks are properly terminated even if errors occur.
```

--------------------------------

### MethodLoadBuilder::new

Source: https://docs.rs/ittapi/0.5.0/ittapi/jit/struct.MethodLoadBuilder.html?search=

Creates a new MethodLoadBuilder. Requires the method name, the starting address of the code region, and the size of the code region in bytes.

```APIDOC
## MethodLoadBuilder::new

### Description
Creates a new `MethodLoadBuilder` from scratch.
`addr` is the pointer to the start of the code region, `len` is the size of this code region in bytes.

### Signature
```rust
pub fn new(method_name: String, addr: *const u8, len: usize) -> Self
```
```

--------------------------------

### MethodLoadBuilder::new

Source: https://docs.rs/ittapi/0.5.0/src/ittapi/jit.rs.html

Creates a new `MethodLoadBuilder` instance. Requires the method name, the starting address of the code, and the size of the code region in bytes.

```rust
pub fn new(method_name: String, addr: *const u8, len: usize) -> Self {
    Self {
        method_name,
        addr,
        len,
        class_file_name: None,
        source_file_name: None,
    }
}
```

--------------------------------

### Task Sanity Test

Source: https://docs.rs/ittapi/0.5.0/src/ittapi/task.rs.html?search=u32+-%3E+bool

A basic test case to verify the functionality of `Task::begin`. It creates a domain and a string handle, then starts a task. This test ensures that the task can be initiated without immediate errors.

```rust
# use super::*;
# use crate::domain::Domain;
# use crate::string::StringHandle;
#[test]
fn sanity() {
    let domain = Domain::new("domain");
    let name = StringHandle::new("task");
    let _task = Task::begin(&domain, name);
}
```

--------------------------------

### Create and Use an Event Span

Source: https://docs.rs/ittapi/0.5.0/ittapi/struct.Event.html?search=

Demonstrates creating a new event with a name and using its `start()` method to create a timing span. The event is automatically stopped when the `span` variable goes out of scope.

```rust
let event = ittapi::Event::new("foo");
{
  let span = event.start();
  // do some work...
  // ...the event is stopped when `span` is dropped
}
```

--------------------------------

### MethodLoadBuilder::new

Source: https://docs.rs/ittapi/0.5.0/ittapi/jit/struct.MethodLoadBuilder.html?search=u32+-%3E+bool

Creates a new MethodLoadBuilder. Requires the method name, a pointer to the start of the code region, and the size of the code region in bytes.

```APIDOC
## MethodLoadBuilder::new

### Description
Creates a new `MethodLoadBuilder` from scratch.
`addr` is the pointer to the start of the code region, `len` is the size of this code region in bytes.

### Signature
`pub fn new(method_name: String, addr: *const u8, len: usize) -> Self`

### Parameters
* `method_name` (String) - The name of the method.
* `addr` (*const u8) - A pointer to the start of the code region.
* `len` (usize) - The size of the code region in bytes.
```

--------------------------------

### Task::begin

Source: https://docs.rs/ittapi/0.5.0/src/ittapi/task.rs.html?search=u32+-%3E+bool

Starts a new task on the current thread within a specified domain. Tasks can be named using a StringHandle or a string slice. The task is automatically ended when the returned Task object is dropped.

```APIDOC
## Task::begin

### Description
Starts a task on the current thread within a specified domain. The task can be identified by a `StringHandle` or a string slice. The task will be automatically ended when the returned `Task` object is dropped.

### Method
`pub fn begin<'a>(domain: &'a Domain, name: impl Into<StringHandle>) -> Self`

### Parameters
* `domain` (*&'a Domain*) - The domain to which the task belongs.
* `name` (*impl Into<StringHandle>*) - The name of the task, which can be provided as a `StringHandle` or a string slice.

### Returns
* `Self` - A `Task` object representing the started task. This object must be kept alive for the duration of the task, and its `Drop` implementation will handle ending the task.
```

--------------------------------

### Event::start

Source: https://docs.rs/ittapi/0.5.0/src/ittapi/event.rs.html?search=

Starts an event, creating a span of time during which the event is active. The event is automatically stopped when the returned `StartedEvent` goes out of scope.

```APIDOC
## Event::start

### Description
Starts an event, creating a span of time during which the event is active. The event is automatically stopped when the returned `StartedEvent` goes out of scope.

### Signature
`pub fn start(&self) -> StartedEvent`

### Panics

This will panic if the ITT library cannot start the event.
```

--------------------------------

### Manual Event Ending (for demonstration)

Source: https://docs.rs/ittapi/0.5.0/src/ittapi/event.rs.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Demonstrates manually ending a started event using the `end` method on `StartedEvent`. Note that the `Drop` implementation typically handles this automatically.

```rust
let s1 = event.start();
let s2 = event.start();
s2.end();
s1.end();
```

--------------------------------

### Event::new

Source: https://docs.rs/ittapi/0.5.0/src/ittapi/event.rs.html

Creates a new event with the given name. This function is used to initialize an event that can later be started and stopped. It includes panics for invalid names or sizes.

```APIDOC
## Event::new

### Description

Create the event with a given name. This function will panic if the name contains a null byte or if its length cannot be represented as a 32-bit integer.

### Signature

```rust
pub fn new(name: &str) -> Self
```

### Parameters

- **name** (string) - Required - The name of the event.

### Panics

- Panics if the name contains a `0` byte.
- Panics if the name's length cannot fit into a 32-bit representation.
```

--------------------------------

### Initialize and Use Jit for Method Loading

Source: https://docs.rs/ittapi/0.5.0/src/ittapi/jit.rs.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Demonstrates how to create a `Jit` instance, obtain a method ID, build method load information, and notify VTune about a newly jitted method. Ensure proper error handling.

```rust
use anyhow::Context;
use std::{ffi::CString, os, ptr};

// Assume MethodLoadBuilder, MethodId, EventType, and ittapi_sys are defined elsewhere
// For demonstration purposes, let's mock them briefly:
struct MethodId(u32);
impl MethodId {
    fn new() -> Self { MethodId(0) } // Mock
}
struct MethodLoad(u32);
impl MethodLoad {
    fn new(_method_id: MethodId, _name: CString, _code_start: *const u8, _code_size: usize) -> Self { MethodLoad(0) } // Mock
}
struct MethodLoadBuilder { name: String, code_start: *const u8, code_size: usize } // Mock
impl MethodLoadBuilder {
    fn build(&self, _method_id: MethodId) -> anyhow::Result<EventType> { Ok(EventType::MethodLoadFinished(MethodLoad::new(MethodId::new(), CString::new("").unwrap(), ptr::null(), 0)))
    }
}
enum EventType { MethodLoadFinished(MethodLoad), Shutdown } // Mock
impl EventType {
    fn tag(&self) -> u32 { 0 } // Mock
    fn data(&mut self) -> *mut os::raw::c_void { ptr::null_mut() } // Mock
}
mod ittapi_sys { pub const iJIT_jvm_event_iJVM_EVENT_TYPE_METHOD_LOAD_FINISHED: u32 = 0; pub const iJIT_jvm_event_iJVM_EVENT_TYPE_SHUTDOWN: u32 = 1; pub fn iJIT_GetNewMethodID() -> u32 { 0 } pub fn iJIT_NotifyEvent(_tag: u32, _data: *mut os::raw::c_void) -> i32 { 1 } } // Mock

// Actual Jit struct and impl from the source
#[derive(Default)]
pub struct Jit {
    shutdown_complete: bool,
}

impl Jit {
    #[allow(clippy::unused_self)]
    #[must_use]
    pub fn get_method_id(&self) -> MethodId {
        MethodId(unsafe { ittapi_sys::iJIT_GetNewMethodID() })
    }

    #[allow(clippy::unused_self)]
    pub fn notify_event(&self, mut event: EventType) -> anyhow::Result<()> {
        let tag = event.tag();
        let data = event.data();
        log::trace!("notify_event: tag={{:?}}", tag);
        let res = unsafe { ittapi_sys::iJIT_NotifyEvent(tag, data) };
        match event {
            EventType::MethodLoadFinished(_) => {
                Ok(())
            }
            EventType::Shutdown => {
                if res == 1 {
                    Ok(())
                } else {
                    anyhow::bail!("error when notifying event with tag {tag}: return code = {res}");
                }
            }
        }
    }

    pub fn load_method(&self, builder: MethodLoadBuilder) -> anyhow::Result<()> {
        let method_id = self.get_method_id();
        let method_load = builder.build(method_id)?;
        self.notify_event(method_load)
    }

    pub fn shutdown(&mut self) -> anyhow::Result<()> {
        if self.shutdown_complete {
            return Ok(());
        }
        let res = self.notify_event(EventType::Shutdown);
        if res.is_ok() {
            self.shutdown_complete = true;
        }
        res
    }
}

impl Drop for Jit {
    fn drop(&mut self) {
        if !self.shutdown_complete {
            if let Err(err) = self.shutdown() {
                log::error!("Error when shutting down VTune: {}", err);
            }
        }
    }
}

// Example usage:
fn main() -> anyhow::Result<()> {
    let jit = Jit::default();
    let builder = MethodLoadBuilder { name: "my_function".to_string(), code_start: ptr::null(), code_size: 100 };
    jit.load_method(builder)?;
    println!("Method loaded successfully.");
    // jit.shutdown()?; // shutdown is called automatically when Jit goes out of scope
    Ok(())
}

```

--------------------------------

### Initialize and Use Jit Structure

Source: https://docs.rs/ittapi/0.5.0/src/ittapi/jit.rs.html

Demonstrates how to create a new `Jit` instance and use its methods to load a method and shut down profiling. Ensure proper error handling.

```rust
use anyhow::Context;
use std::{ffi::CString, os, ptr};

// Assuming MethodLoadBuilder and MethodId are defined elsewhere
// For demonstration purposes, let's define dummy versions:
struct MethodId(u32);
impl MethodId {
    fn new() -> Self { MethodId(0) } // Dummy implementation
}

struct MethodLoad(u32);
impl MethodLoad {
    fn new(id: MethodId) -> Self { MethodLoad(id.0) } // Dummy implementation
}

struct MethodLoadBuilder;
impl MethodLoadBuilder {
    fn build(&self, method_id: MethodId) -> anyhow::Result<MethodLoad> {
        Ok(MethodLoad::new(method_id))
    }
}

// Mock ittapi_sys for compilation
mod ittapi_sys {
    pub use super::super::ittapi_sys::*; // Assuming this is how it's structured
    pub type iJIT_jvm_event = i32;
    pub const iJVM_EVENT_TYPE_METHOD_LOAD_FINISHED: iJIT_jvm_event = 1;
    pub const iJVM_EVENT_TYPE_SHUTDOWN: iJIT_jvm_event = 2;
    pub fn iJIT_GetNewMethodID() -> u32 { 0 }
    pub fn iJIT_NotifyEvent(_tag: iJIT_jvm_event, _data: *mut std::os::raw::c_void) -> i32 { 1 }
}

// Mock log for compilation
mod log {
    pub fn trace(msg: &str) {
        println!("TRACE: {}", msg);
    }
    pub fn error(msg: &str) {
        eprintln!("ERROR: {}", msg);
    }
}

// Actual Jit struct and impl from the source
pub struct Jit {
    shutdown_complete: bool,
}

impl Jit {
    #[allow(clippy::unused_self)]
    #[must_use]
    pub fn get_method_id(&self) -> MethodId {
        MethodId(unsafe { ittapi_sys::iJIT_GetNewMethodID() })
    }

    #[allow(clippy::unused_self)]
    pub fn notify_event(&self, mut event: EventType) -> anyhow::Result<()> {
        let tag = event.tag();
        let data = event.data();
        log::trace!("notify_event: tag={:?}", tag);
        let res = unsafe { ittapi_sys::iJIT_NotifyEvent(tag, data) };
        match event {
            EventType::MethodLoadFinished(_) => {
                Ok(())
            }
            EventType::Shutdown => {
                if res == 1 {
                    Ok(())
                } else {
                    anyhow::bail!("error when notifying event with tag {tag}: return code = {res}");
                }
            }
        }
    }

    pub fn load_method(&self, builder: MethodLoadBuilder) -> anyhow::Result<()> {
        let method_id = self.get_method_id();
        let method_load = builder.build(method_id)?;
        self.notify_event(method_load)
    }

    pub fn shutdown(&mut self) -> anyhow::Result<()> {
        if self.shutdown_complete {
            return Ok(());
        }
        let res = self.notify_event(EventType::Shutdown);
        if res.is_ok() {
            self.shutdown_complete = true;
        }
        res
    }
}

impl Drop for Jit {
    fn drop(&mut self) {
        if !self.shutdown_complete {
            if let Err(err) = self.shutdown() {
                log::error!("Error when shutting down VTune: {}", err);
            }
        }
    }
}

pub enum EventType {
    MethodLoadFinished(MethodLoad),
    Shutdown,
}

impl EventType {
    fn tag(&self) -> ittapi_sys::iJIT_jvm_event {
        match self {
            EventType::MethodLoadFinished(_) => {
                ittapi_sys::iJIT_jvm_event_iJVM_EVENT_TYPE_METHOD_LOAD_FINISHED
            }
            EventType::Shutdown => ittapi_sys::iJIT_jvm_event_iJVM_EVENT_TYPE_SHUTDOWN,
        }
    }

    fn data(&mut self) -> *mut os::raw::c_void {
        match self {
            EventType::MethodLoadFinished(method_load) => ptr::addr_of_mut!(method_load.0).cast(),
            EventType::Shutdown => ptr::null_mut(),
        }
    }
}

fn main() -> anyhow::Result<()> {
    let jit = Jit { shutdown_complete: false };
    let builder = MethodLoadBuilder;
    jit.load_method(builder)?;
    jit.shutdown()?;
    Ok(())
}

```

--------------------------------

### Initialize and use Jit for method loading

Source: https://docs.rs/ittapi/0.5.0/src/ittapi/jit.rs.html?search=std%3A%3Avec

Demonstrates how to create a `Jit` instance, obtain a `MethodId`, build `MethodLoad` event data, and notify VTune about a newly jitted method. Ensure proper error handling.

```rust
use anyhow::Context;
use std::{ffi::CString, os, ptr};

// Assume MethodId, MethodLoadBuilder, MethodLoad, EventType, and ittapi_sys are defined elsewhere

// Placeholder for MethodId
#[derive(Debug)]
struct MethodId(u32);
impl MethodId {
    fn new() -> Self {
        MethodId(0) // Dummy value
    }
}

// Placeholder for MethodLoadBuilder
struct MethodLoadBuilder {
    name: String,
    // other fields...
}

impl MethodLoadBuilder {
    fn new(name: &str) -> Self {
        MethodLoadBuilder { name: name.to_string() }
    }

    fn build(&self, method_id: MethodId) -> anyhow::Result<EventType> {
        // Dummy implementation
        Ok(EventType::MethodLoadFinished(MethodLoad(method_id)))
    }
}

// Placeholder for MethodLoad
struct MethodLoad(MethodId);

// Placeholder for EventType
enum EventType {
    MethodLoadFinished(MethodLoad),
    Shutdown,
}

impl EventType {
    fn tag(&self) -> u32 { // Dummy tag type
        match self {
            EventType::MethodLoadFinished(_) => 1,
            EventType::Shutdown => 2,
        }
    }

    fn data(&mut self) -> *mut os::raw::c_void {
        match self {
            EventType::MethodLoadFinished(method_load) => {
                // In a real scenario, this would point to actual data
                let dummy_ptr: *mut os::raw::c_void = std::ptr::null_mut();
                dummy_ptr
            }
            EventType::Shutdown => std::ptr::null_mut(),
        }
    }
}

// Placeholder for Jit struct and its methods
struct Jit {
    shutdown_complete: bool,
}

impl Jit {
    fn new() -> Self {
        Jit { shutdown_complete: false }
    }

    fn get_method_id(&self) -> MethodId {
        // In a real scenario, this would call ittapi_sys::iJIT_GetNewMethodID()
        MethodId::new()
    }

    fn notify_event(&self, mut event: EventType) -> anyhow::Result<()> {
        let tag = event.tag();
        let data = event.data();
        log::trace!("notify_event: tag={:?}", tag);
        // In a real scenario, this would call ittapi_sys::iJIT_NotifyEvent(tag, data)
        let res = 1; // Simulate success
        match event {
            EventType::MethodLoadFinished(_) => Ok(()),
            EventType::Shutdown => {
                if res == 1 {
                    Ok(())
                } else {
                    anyhow::bail!("error when notifying event with tag {tag}: return code = {res}");
                }
            }
        }
    }

    pub fn load_method(&self, builder: MethodLoadBuilder) -> anyhow::Result<()> {
        let method_id = self.get_method_id();
        let method_load = builder.build(method_id)?;
        self.notify_event(method_load)
    }

    pub fn shutdown(&mut self) -> anyhow::Result<()> {
        if self.shutdown_complete {
            return Ok(());
        }
        let res = self.notify_event(EventType::Shutdown);
        if res.is_ok() {
            self.shutdown_complete = true;
        }
        res
    }
}

fn main() -> anyhow::Result<()> {
    let jit = Jit::new();
    let builder = MethodLoadBuilder::new("my_function");
    jit.load_method(builder).context("Failed to load method")?;
    println!("Method loaded successfully.");
    Ok(())
}

```

--------------------------------

### Create a New Domain

Source: https://docs.rs/ittapi/0.5.0/ittapi/struct.Domain.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Demonstrates how to create a new domain with a given name. Note that the domain will be invalid if the `ittnotify` library is not initialized.

```rust
let domain = Domain::new("test-domain");
```

--------------------------------

### Task::end

Source: https://docs.rs/ittapi/0.5.0/ittapi/struct.Task.html?search=std%3A%3Avec

Finishes a previously started task. This method should be called when the unit of work is complete.

```APIDOC
## Task::end

### Description
Finishes the task.

### Method
`pub fn end(self)`

### Parameters
* **self** (`Self`) - The Task instance to be ended.

### Returns
`()` - This method does not return a value.
```

--------------------------------

### Create and Use StringHandle

Source: https://docs.rs/ittapi/0.5.0/src/ittapi/string.rs.html?search=std%3A%3Avec

Demonstrates creating a StringHandle using its `new` method and the `From<&str>` trait. It also shows how to compare handles and checks for the presence of the profiling environment variable.

```rust
use crate::util::access_sys_fn;
use std::ffi::CString;

#[derive(PartialEq, Eq, Debug)]
pub struct StringHandle(*mut ittapi_sys::__itt_string_handle);
impl StringHandle {
    /// Create a new string handle; repeated calls with the same `name` will return the same handle.
    ///
    /// ```
    /// # use ittapi::StringHandle;
    /// let a = StringHandle::new("test");
    /// let b: StringHandle = "test".into();
    /// assert_eq!(a, b);
    /// ```
    ///
    /// # Panics
    ///
    /// Panics if the string contains a `0` byte.
    #[must_use]
    pub fn new(name: &str) -> Self {
        #[cfg(unix)]
        let create_fn = access_sys_fn!(__itt_string_handle_create_ptr__3_0);
        #[cfg(windows)]
        let create_fn = access_sys_fn!(__itt_string_handle_createA_ptr__3_0);
        let c_string =
            CString::new(name).expect("unable to create a CString; does it contain a 0 byte?");
        let handle = unsafe { create_fn(c_string.as_ptr()) };
        Self(handle)
    }

    /// Use the `__itt_string_handle` pointer internally.
    pub(crate) fn as_ptr(&self) -> *mut ittapi_sys::__itt_string_handle {
        self.0
    }
}

implement From<&str> for StringHandle {
    fn from(name: &str) -> Self {
        Self::new(name)
    }
}

mod tests {
    #[test]
    fn construct_string_handle() {
        let sh = super::StringHandle::new("test2");
        // `ittapi` profiling is only enabled when the `INTEL_LIBITTNOTIFY64` environment variable
        // is set, which points to the profiling collector. If set, the string handle is actually
        // allocated; if not set, no allocation is performed (this is a general `ittapi` property:
        // no allocation without a profiling collector). Note that string handles are thus invalid
        // in the latter case--no collector--but the API safely does not provide any way to observe
        // this.
        if std::env::var("INTEL_LIBITTNOTIFY64").is_ok() {
            assert!(!sh.as_ptr().is_null());
        } else {
            assert!(sh.as_ptr().is_null());
        }
    }
}
```

--------------------------------

### Create a new Domain

Source: https://docs.rs/ittapi/0.5.0/src/ittapi/domain.rs.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Creates a new domain with a given name. Ensure the ittnotify library is initialized for the domain to be valid. Panics if the name contains a null byte.

```Rust
use ittapi::Domain;

let domain = Domain::new("test-domain");

```

--------------------------------

### Create a new domain

Source: https://docs.rs/ittapi/0.5.0/src/ittapi/domain.rs.html

Creates a new trace domain with a given name. Ensure the ittnotify library is initialized for the domain to be valid. Panics if the name contains a null byte.

```rust
use crate::util::access_sys_fn;
use std::ffi::CString;

pub struct Domain(*mut ittapi_sys::__itt_domain);
impl Domain {
    #[must_use]
    pub fn new(name: &str) -> Self {
        #[cfg(unix)]
        let create_fn = access_sys_fn!(__itt_domain_create_ptr__3_0);
        #[cfg(windows)]
        let create_fn = access_sys_fn!(__itt_domain_createA_ptr__3_0);
        let c_string =
            CString::new(name).expect("unable to create a CString; does it contain a 0 byte?");
        let domain = unsafe { create_fn(c_string.as_ptr()) };
        Self(domain)
    }

    pub(crate) fn as_ptr(&self) -> *const ittapi_sys::__itt_domain {
        self.0.cast_const()
    }
}

unsafe impl Sync for Domain {}

```

--------------------------------

### Task Sanity Test

Source: https://docs.rs/ittapi/0.5.0/src/ittapi/task.rs.html?search=

A basic test case to ensure that a `Task` can be created and started without immediate errors.

```rust
let domain = Domain::new("domain");
let name = StringHandle::new("task");
let _task = Task::begin(&domain, name);

```

--------------------------------

### Task::end

Source: https://docs.rs/ittapi/0.5.0/ittapi/struct.Task.html?search=

Explicitly finishes a task that was previously started with `Task::begin`. This method consumes the `Task` instance.

```APIDOC
## Task::end

### Description
Finishes the task.

### Signature
`pub fn end(self)`

### Parameters
* **self**: The `Task` instance to end. This consumes the task.
```

--------------------------------

### ittapi Library Introduction

Source: https://docs.rs/ittapi/0.5.0/src/ittapi/lib.rs.html

This snippet provides the main library documentation for ittapi, explaining its purpose and dependencies.

```rust
1//! This library allows Rust programs to use Intel&reg; Instrumentation and Tracing Technology (ITT)
2//! APIs. These APIs are declared by a static library, [`ittnotify`], and dynamically used by
3//! performance collection tools (e.g., `libittnotify_collector.so`, VTune Profiler).
4//!
5//! [`ittnotify`]: https://github.com/intel/ittapi
6#![deny(missing_docs)]
7#![deny(clippy::all)]
8#![warn(clippy::pedantic)]
9#![warn(clippy::cargo)]
10#![allow(clippy::return_self_not_must_use, clippy::module_name_repetitions)]
11
12mod collection_control;
13mod domain;
14mod event;
15pub mod jit;
16mod region;
17mod string;
18mod task;
19mod util;
20
21pub use collection_control::{detach, pause, resume};
22pub use domain::Domain;
23pub use event::{Event, StartedEvent};
24pub use region::{MarkedRegion, Region};
25pub use string::StringHandle;
26pub use task::Task;

```

--------------------------------

### StartedEvent::end

Source: https://docs.rs/ittapi/0.5.0/ittapi/struct.StartedEvent.html?search=std%3A%3Avec

The `end` function is used to explicitly end the started event. This method consumes the `StartedEvent` instance.

```APIDOC
## StartedEvent::end

### Description
End the event.

### Method
`pub fn end(self)`

### Parameters
None

### Returns
None
```

--------------------------------

### resume()

Source: https://docs.rs/ittapi/0.5.0/src/ittapi/collection_control.rs.html?search=std%3A%3Avec

Resumes data collection for VTune Profiler, allowing all data to be collected again.

```APIDOC
## resume()

### Description
Resumes data collection for VTune Profiler, enabling the collection of all data types.

### Example
See [pause#example].
```

--------------------------------

### Get Event Tag

Source: https://docs.rs/ittapi/0.5.0/src/ittapi/jit.rs.html?search=u32+-%3E+bool

Returns the C-style event tag corresponding to the EventType. This tag is used by the underlying ITT library.

```rust
fn tag(&self) -> ittapi_sys::iJIT_jvm_event {
    match self {
        EventType::MethodLoadFinished(_) => {
            ittapi_sys::iJIT_jvm_event_iJVM_EVENT_TYPE_METHOD_LOAD_FINISHED
        }
        EventType::Shutdown => ittapi_sys::iJIT_jvm_event_iJVM_EVENT_TYPE_SHUTDOWN,
    }
}
```

--------------------------------

### resume()

Source: https://docs.rs/ittapi/0.5.0/src/ittapi/collection_control.rs.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Resumes data collection for VTune Profiler, allowing all data to be collected again.

```APIDOC
## resume()

### Description
Resumes data collection for VTune Profiler, allowing all data to be collected again.

### Method
`pub fn resume()`

### Example
See [pause#example].
```

--------------------------------

### Get Method ID

Source: https://docs.rs/ittapi/0.5.0/ittapi/jit/struct.Jit.html

Obtains a new MethodId for use in MethodLoad events. This is useful for tracking individual JIT-compiled methods.

```rust
pub fn get_method_id(&self) -> MethodId
```

--------------------------------

### resume()

Source: https://docs.rs/ittapi/0.5.0/src/ittapi/collection_control.rs.html?search=u32+-%3E+bool

Resumes data collection for VTune Profiler, allowing all data to be collected again.

```APIDOC
## resume()

### Description
Resumes data collection for VTune Profiler, allowing all data to be collected again.

### Method
```rust
pub fn resume()
```

### Example
See [pause#example].
```

--------------------------------

### Basic Event Sanity Test

Source: https://docs.rs/ittapi/0.5.0/src/ittapi/event.rs.html?search=

A simple test to verify that an event can be created and started, and that its associated `StartedEvent` guard is dropped correctly.

```rust
let event = Event::new("test");
let _started_event = event.start();
// Dropping `started_event` ends the event.
```

--------------------------------

### Get a New Method ID

Source: https://docs.rs/ittapi/0.5.0/src/ittapi/jit.rs.html?search=u32+-%3E+bool

Obtains a unique identifier for a JIT-compiled method. This ID is used when reporting method load events.

```rust
let method_id = jit.get_method_id();
```

--------------------------------

### Domain::new

Source: https://docs.rs/ittapi/0.5.0/ittapi/struct.Domain.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Creates a new domain with the specified name. Panics if the name contains a null byte. Note that the domain will be invalid if the `ittnotify` library is not initialized.

```APIDOC
## Domain::new

### Description
Creates a new domain with the specified name. Panics if the name contains a null byte. Note that the domain will be invalid if the `ittnotify` library is not initialized.

### Signature
`pub fn new(name: &str) -> Self`

### Parameters
#### Path Parameters
- **name** (string) - Required - The name of the domain.

### Panics
Panics if the domain name contains a `0` byte.
```

--------------------------------

### Resume Data Collection

Source: https://docs.rs/ittapi/0.5.0/src/ittapi/collection_control.rs.html?search=

Resumes data collection after it has been paused. This allows VTune Profiler to collect all data again. See the example for `pause()` for usage.

```Rust
ittapi::resume();
```

--------------------------------

### Event Creation with Platform-Specific Functions

Source: https://docs.rs/ittapi/0.5.0/src/ittapi/event.rs.html?search=u32+-%3E+bool

Shows how to create an event using platform-specific system calls for event creation, handling potential errors during string conversion or size fitting.

```rust
if let Some(create_fn) = create_fn {
    let c_string = CString::new(name).expect("unable to create a CString; does it contain a 0 byte?");
    let size = name.len().try_into().expect("unable to fit the name length into an i32");
    let event = unsafe { create_fn(c_string.as_ptr(), size) };
    Self(event)
} else {
    Self(-1)
}

```
Tokens:
Raw