add range start/end macros

examples/arbitrary_range/main.rs

@@ -0,0 +1,19 @@
+use std::thread::{self, sleep};
+use std::time::Duration;
+
+use nvtx::{range_end, range_start};
+
+/// Create an arbitrary concurrency range on the NVTX layer. </br>
+/// This program should be ran from a profiling application like NVIDIA Nsight
+/// Systems!
+fn main() {
+    let id = thread::spawn(|| {
+        let id = range_start!("My Range");
+        sleep(Duration::from_millis(100)); // Expensive operation here
+        id
+    })
+    .join()
+    .unwrap();
+
+    range_end!(id);
+}

nvtx-sys/export.c

@@ -39,6 +39,16 @@ int ffi_range_pop()
     return nvtxRangePop();
 }
 
+int ffi_range_start(const char *message)
+{
+    return nvtxRangeStartA(message);
+}
+
+void ffi_range_end(int id)
+{
+    return nvtxRangeEnd(id);
+}
+
 void ffi_mark(const char *message)
 {
     return nvtxMarkA(message);

src/bindings.rs

@@ -26,6 +26,30 @@ pub fn _range_pop() -> i32 {
     unsafe { ffi_range_pop() }
 }
 
+#[doc(hidden)]
+pub fn _range_start<M: Display>(message: M) -> i32 {
+    #[link(name = "nvtx")]
+    extern "C" {
+        fn ffi_range_start(
+            message: *const ::core::ffi::c_char,
+        ) -> ::core::ffi::c_int;
+    }
+    let message: CString = CString::new(message.to_string())
+        .expect("message contains null terminator");
+    // SAFETY: calling foreign function is unsafe
+    unsafe { ffi_range_start(message.as_ptr()) }
+}
+
+#[doc(hidden)]
+pub fn _range_end(id: i32) -> i32 {
+    #[link(name = "nvtx")]
+    extern "C" {
+        fn ffi_range_end(id: ::core::ffi::c_int) -> ::core::ffi::c_int;
+    }
+    // SAFETY: calling foreign function is unsafe
+    unsafe { ffi_range_end(id) }
+}
+
 #[doc(hidden)]
 pub fn _mark<M: Display>(message: M) {
     #[link(name = "nvtx")]

src/macros.rs

@@ -63,6 +63,50 @@ macro_rules! range_pop {
     };
 }
 
+/// Starts a range that can occur on a different thread than the end.
+///
+/// # Arguments
+///
+/// * `message` - The event message associated to this range event.
+///
+/// # Returns
+///
+/// * returns the `id` of the range.
+///
+/// # Examples
+///
+/// ```
+/// use nvtx::{range_end, range_start};
+/// let id = range_start!("Hello World!");
+/// range_end!(id);
+/// ```
+#[macro_export]
+macro_rules! range_start{
+    ($($tt:tt)*) => {
+        $crate::__private::_range_start(::core::format_args!($($tt)*))
+    };
+}
+
+/// Ends a range that can occur on a different thread than the start.
+///
+/// # Arguments
+///
+/// * `id` - The event id associated to this range event.
+///
+/// # Examples
+///
+/// ```
+/// use nvtx::{range_end, range_start};
+/// let id = range_start!("Hello World!");
+/// range_end!(id);
+/// ```
+#[macro_export]
+macro_rules! range_end {
+    ($tt:tt) => {
+        $crate::__private::_range_end($tt)
+    };
+}
+
 /// Annotate an OS thread with a name.
 ///
 /// # Examples