Add a range! macro to start/end ranges using a guard object.

CHANGELOG.md

@@ -6,6 +6,15 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](http://keepachangelog.com/)
 and this project adheres to [Semantic Versioning](http://semver.org/).
 
+## [1.3.0] - 2024-01-18
+
+There are no update steps from the previous version.
+
+### Added
+
+- [Feature](https://github.com/simbleau/nvtx/pull/19)
+  Added `range!` macro.
+
 ## [1.2.0] - 2023-07-25
 
 There are no update steps from the previous version.

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "nvtx"
-version = "1.2.0"
+version = "1.3.0"
 authors = ["Spencer Imbleau <spencer@imbleau.com>"]
 edition = "2021"
 description = "Rust bindings for the NVIDIA® Tools Extension SDK (NVTX)"

src/lib.rs

@@ -19,6 +19,13 @@
 //! ```
 //!
 //! ```
+//! use nvtx::range;
+//! let range = range!("Hello World!");
+//! // <-- Expensive algorithm here
+//! drop(range);
+//! ```
+//!
+//! ```
 //! use nvtx::{mark};
 //! mark!("Operation A");
 //! // <-- Expensive algorithm here
@@ -43,3 +50,14 @@ pub mod __private {
 
 mod macros;
 pub use macros::*;
+
+/// A guard object representing an open NVTX range. Construct it using the [`range!`] macro. When it
+/// goes out of scope it will call [`range_end!`].
+pub struct RangeGuard(#[doc(hidden)] pub i32);
+
+impl Drop for RangeGuard {
+    fn drop(&mut self) {
+        let id = self.0;
+        range_end!(id);
+    }
+}

src/macros.rs

@@ -107,6 +107,40 @@ macro_rules! range_end {
     };
 }
 
+/// Starts a range, returning a guard that will end the range when it is dropped.
+///
+/// This is a convenience for calling [`range_start!`] and [`range_end!`], in particular for cases
+/// where a function might exit in multiple places.
+///
+/// # Arguments
+///
+/// * `message` - The event message associated to this range event.
+///
+/// # Returns
+///
+/// * returns a [`RangeGuard`](crate::RangeGuard) which will end the range when it goes out of
+/// scope.
+///
+/// # Examples
+///
+/// ```
+/// # let some_condition = true;
+/// use nvtx::range;
+/// let _range = range!("Hello World!");
+///
+/// // The range will end regardless of which branch is taken.
+/// if some_condition {
+///     return;
+/// }
+/// ```
+#[macro_export]
+macro_rules! range {
+    ($($tt:tt)*) => {{
+        let id = $crate::range_start!($($tt)*);
+        $crate::RangeGuard(id)
+    }};
+}
+
 /// Annotate an OS thread with a name.
 ///
 /// # Examples