Merge pull request #70 from michaelwoerister/raii-recording

Add RAII-based API for recording events and bump version to 0.4.0

Author: wesleywiser

CHANGELOG.md

@@ -1,7 +1,8 @@
 # Changelog
 
-## Unreleased
+## [0.4.0] - 2019-10-24
 ### Added
+- `measureme`: Added RAII-based API for recording events ([GH-70])
 - `measureme`: Added support for compiling the library under wasm/wasi ([GH-43])
 - `mmview`: Added the `-t` flag to limit output to results on the specified thread id ([GH-49])
 - `summarize`: Added the `diff` sub command to compare two profiles ([GH-50])
@@ -22,7 +23,7 @@
 
 ## [0.2.0] - 2019-04-10
 
-
+[0.4.0]: https://github.com/rust-lang/measureme/releases/tag/0.4.0
 [0.3.0]: https://github.com/rust-lang/measureme/releases/tag/0.3.0
 [0.2.1]: https://github.com/rust-lang/measureme/releases/tag/0.2.1
 [0.2.0]: https://github.com/rust-lang/measureme/releases/tag/0.2.0
@@ -35,3 +36,4 @@
 [GH-56]: https://github.com/rust-lang/measureme/pull/56
 [GH-59]: https://github.com/rust-lang/measureme/pull/59
 [GH-60]: https://github.com/rust-lang/measureme/pull/60
+[GH-70]: https://github.com/rust-lang/measureme/pull/70

measureme/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "measureme"
-version = "0.3.0"
+version = "0.4.0"
 authors = ["Wesley Wiser <[email protected]>", "Michael Woerister <michaelwoerister@posteo>"]
 edition = "2018"
 description = "Support crate for rustc's self-profiling feature"

measureme/src/lib.rs

@@ -21,6 +21,10 @@
 //!   - `thread_id`: a `u64` id of the thread which is recording this event
 //!   - `timestamp_kind`: a [`TimestampKind`] which specifies how this event should be treated by `measureme` tooling
 //!
+//! Alternatively, events can also be recorded via the [`Profiler::start_recording_interval_event()`] method. This
+//! method records a "start" event and returns a `TimingGuard` object that will automatically record
+//! the corresponding "end" event when it is dropped.
+//!
 //! To create a [`StringId`], call one of the string allocation methods:
 //!   - [`Profiler::alloc_string()`]: allocates a string and returns the [`StringId`] that refers to it
 //!   - [`Profiler::alloc_string_with_reserved_id()`]: allocates a string using the specified [`StringId`].
@@ -41,6 +45,7 @@
 //! [`Profiler::alloc_string_with_reserved_id()`]: struct.Profiler.html#method.alloc_string_with_reserved_id
 //! [`Profiler::new()`]: struct.Profiler.html#method.new
 //! [`Profiler::record_event()`]: struct.Profiler.html#method.record_event
+//! [`Profiler::start_recording_interval_event()`]: struct.Profiler.html#method.start_recording_interval_event
 //! [`ProfilingData`]: struct.ProfilingData.html
 //! [`ProfilingData::iter()`]: struct.ProfilingData.html#method.iter
 //! [`ProfilingData::iter_matching_events()`]: struct.ProfilingData.html#method.iter_matching_events
@@ -69,7 +74,7 @@ pub use crate::event::Event;
 pub use crate::file_serialization_sink::FileSerializationSink;
 #[cfg(not(target_arch = "wasm32"))]
 pub use crate::mmap_serialization_sink::MmapSerializationSink;
-pub use crate::profiler::{Profiler, ProfilerFiles};
+pub use crate::profiler::{Profiler, ProfilerFiles, TimingGuard};
 pub use crate::profiling_data::{MatchingEvent, ProfilingData};
 pub use crate::raw_event::{RawEvent, Timestamp, TimestampKind};
 pub use crate::serialization::{Addr, SerializationSink};

measureme/src/profiler.rs

@@ -78,6 +78,8 @@ impl<S: SerializationSink> Profiler<S> {
         self.string_table.alloc(s)
     }
 
+    /// Records an event with the given parameters. The event time is computed
+    /// automatically.
     pub fn record_event(
         &self,
         event_kind: StringId,
@@ -90,17 +92,17 @@ impl<S: SerializationSink> Profiler<S> {
             + duration_since_start.subsec_nanos() as u64;
         let timestamp = Timestamp::new(nanos_since_start, timestamp_kind);
 
+        let raw_event = RawEvent {
+            event_kind,
+            id: event_id,
+            thread_id,
+            timestamp,
+        };
+
         self.event_sink
             .write_atomic(std::mem::size_of::<RawEvent>(), |bytes| {
                 debug_assert_eq!(bytes.len(), std::mem::size_of::<RawEvent>());
 
-                let raw_event = RawEvent {
-                    event_kind,
-                    id: event_id,
-                    thread_id,
-                    timestamp,
-                };
-
                 let raw_event_bytes: &[u8] = unsafe {
                     std::slice::from_raw_parts(
                         &raw_event as *const _ as *const u8,
@@ -111,4 +113,44 @@ impl<S: SerializationSink> Profiler<S> {
                 bytes.copy_from_slice(raw_event_bytes);
             });
     }
+
+    /// Creates a "start" event and returns a `TimingGuard` that will create
+    /// the corresponding "end" event when it is dropped.
+    pub fn start_recording_interval_event<'a>(
+        &'a self,
+        event_kind: StringId,
+        event_id: StringId,
+        thread_id: u64,
+    ) -> TimingGuard<'a, S> {
+        self.record_event(event_kind, event_id, thread_id, TimestampKind::Start);
+
+        TimingGuard {
+            profiler: self,
+            event_id,
+            event_kind,
+            thread_id,
+        }
+    }
+}
+
+/// When dropped, this `TimingGuard` will record an "end" event in the
+/// `Profiler` it was created by.
+#[must_use]
+pub struct TimingGuard<'a, S: SerializationSink> {
+    profiler: &'a Profiler<S>,
+    event_id: StringId,
+    event_kind: StringId,
+    thread_id: u64,
+}
+
+impl<'a, S: SerializationSink> Drop for TimingGuard<'a, S> {
+    #[inline]
+    fn drop(&mut self) {
+        self.profiler.record_event(
+            self.event_kind,
+            self.event_id,
+            self.thread_id,
+            TimestampKind::End
+        );
+    }
 }