pf2 0.5.1 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 29a7c92a2a313dec57af9a3427cd723224f64bf53cf74a488253741e1098c12d
-  data.tar.gz: 4958d188fdddec9fb8143a1b864e9c40d989bbb3360745eb0846687cefc97b9d
+  metadata.gz: 1aa1dd1d3caa1dd9327382e7de0a44b2c0ff4555a9dff8fdc7244f61c3a13405
+  data.tar.gz: c50895ea4d8285cc9bb223d575cbec7042aacd119a1390b836b818232ef7e214
 SHA512:
-  metadata.gz: 2a2a7ecd0a4cb0d84f022c3ec1e0844e2c537cfad88f91b0051609006d8c2f4d596f15a1fd259709c97c1ffccbae87e96758a4bcfb70293d88fb44d7888f4071
-  data.tar.gz: 28b108cd63c75d7ead6f34fdd88fdaa867a9601a0217899b024176a4e5508ef9dec7395bf7ae77513de6eb4cc765be90e010146bdd114b989b33359e4ac55068
+  metadata.gz: 1b5db496a58016e11203334b71e80e7a4c0d7d0dce6b2cb288884da4aecd8820d8915fd0b9f4ebd546802c314d621f69da23c474d254bff17ec3931cb8f7604b
+  data.tar.gz: 5e3a8fcf25be2dbf28cf8c36e03839cbeed13aa8d944e43991672a39f06fe16f6eae07aab5cd282c3237171bfff94b39a8abb176153a091452c3177266eb1364

data/CHANGELOG.md

@@ -1,5 +1,21 @@
 ## [Unreleased]
 
+## [0.6.0] - 2024-07-15
+
+### Changed
+
+- The default sampling interval is now 9 ms (was originally 49 ms).
+  - It is intentional that the default is not 10 (or 50) ms - this is to avoid lockstep sampling.
+- BREAKING: `Pf2::Reporter` has been moved to `Pf2::Reporter::FirefoxProfiler`.
+  - This is to make space for other planned reporters.
+
+
+## [0.5.2] - 2024-07-13
+
+### Fixed
+
+- Properly default to TimerThread scheduler on non-Linux environments.
+
 
 ## [0.5.1] - 2024-03-25
 

data/README.md

@@ -58,7 +58,7 @@ File.write("my_program.pf2profile", profile)
 Profiles can be visualized using the [Firefox Profiler](https://profiler.firefox.com/).
 
 ```console
-$ pf2 -o report.json my_program.pf2profile
+$ pf2 report -o report.json my_program.pf2profile
 ```
 
 ### Configuration
@@ -67,7 +67,7 @@ Pf2 accepts the following configuration keys:
 
 ```rb
 Pf2.start(
-  interval_ms: 49,        # Integer: The sampling interval in milliseconds (default: 49)
+  interval_ms: 9,        # Integer: The sampling interval in milliseconds (default: 9)
   time_mode: :cpu,        # `:cpu` or `:wall`: The sampling timer's mode
                           # (default: `:cpu` for SignalScheduler, `:wall` for TimerThreadScheduler)
   threads: [th1, th2],    # `Array<Thread>` | `:all`: A list of Ruby Threads to be tracked.
@@ -108,9 +108,9 @@ Schedulers determine when to execute sample collection, based on configuration (
 
 #### SignalScheduler (Linux-only)
 
-The first is the `SignalScheduler`, based on POSIX timers. Pf2 will use this scheduler when possible. SignalScheduler creates a POSIX timer for each Ruby Thread (the underlying pthread to be more accurate) using `timer_create(3)`. This leaves the actual time-keeping to the OS, which is capable of tracking accurate per-thread CPU time usage.
+The first is the `SignalScheduler`, based on POSIX timers. Pf2 will use this scheduler when possible. SignalScheduler creates a POSIX timer for each Ruby Thread (the underlying pthread to be more accurate) using `timer_create(2)`. This leaves the actual time-keeping to the OS, which is capable of tracking accurate per-thread CPU time usage.
 
-When the specified interval has arrived (the timer has _expired_), the OS delivers us a SIGALRM (note: Unlike `setitimer(2)`, `timer_create(3)` allows us to choose which signal to be delivered, and Pf2 uses SIGALRM regardless of time mode). This is why the scheduler is named SignalScheduler.
+When the specified interval has arrived (the timer has _expired_), the OS delivers us a SIGALRM (note: Unlike `setitimer(2)`, `timer_create(2)` allows us to choose which signal to be delivered, and Pf2 uses SIGALRM regardless of time mode). This is why the scheduler is named SignalScheduler.
 
 Signals are directed to Ruby Threads' underlying pthread, effectively "pausing" the Thread's activity. This routing is done using `SIGEV_THREAD_ID`, which is a Linux-only feature. Sample collection is done in the signal handler, which is expected to be more _accurate_, capturing the paused Thread's activity.
 

data/ext/pf2/src/lib.rs

@@ -10,6 +10,7 @@ mod profile_serializer;
 mod ringbuffer;
 mod sample;
 mod scheduler;
+mod serialization;
 mod session;
 #[cfg(target_os = "linux")]
 mod signal_scheduler;

data/ext/pf2/src/profile.rs

@@ -1,4 +1,4 @@
-use std::time::Instant;
+use std::time::{Instant, SystemTime};
 use std::{collections::HashSet, ptr::null_mut};
 
 use rb_sys::*;
@@ -15,7 +15,9 @@ const DEFAULT_RINGBUFFER_CAPACITY: usize = 320;
 
 #[derive(Debug)]
 pub struct Profile {
-    pub start_timestamp: Instant,
+    pub start_timestamp: SystemTime,
+    pub start_instant: Instant,
+    pub end_instant: Option<Instant>,
     pub samples: Vec<Sample>,
     pub temporary_sample_buffer: Ringbuffer,
     pub backtrace_state: BacktraceState,
@@ -35,7 +37,9 @@ impl Profile {
         };
 
         Self {
-            start_timestamp: Instant::now(),
+            start_timestamp: SystemTime::now(),
+            start_instant: Instant::now(),
+            end_instant: None,
             samples: vec![],
             temporary_sample_buffer: Ringbuffer::new(DEFAULT_RINGBUFFER_CAPACITY),
             backtrace_state,

data/ext/pf2/src/profile_serializer.rs

@@ -221,7 +221,7 @@ impl ProfileSerializer {
 
                     if merged_stack.is_empty() {
                         // This is the leaf node, record a Sample
-                        let elapsed_ns = (sample.timestamp - profile.start_timestamp).as_nanos();
+                        let elapsed_ns = (sample.timestamp - profile.start_instant).as_nanos();
                         thread_serializer.samples.push(ProfileSample {
                             elapsed_ns,
                             stack_tree_id: stack_tree.node_id,

data/ext/pf2/src/serialization/profile.rs

@@ -0,0 +1,46 @@
+#[derive(Clone, Deserialize, Serialize)]
+pub struct Profile {
+    pub samples: Vec<Sample>,
+    pub locations: Vec<Location>,
+    pub functions: Vec<Function>,
+    pub start_timestamp_ns: u128,
+    pub duration_ns: u128,
+}
+
+pub type LocationIndex = usize;
+pub type FunctionIndex = usize;
+
+/// Sample
+#[derive(Clone, Serialize, Deserialize)]
+pub struct Sample {
+    /// The stack leading to this sample.
+    /// The leaf node will be stored at `stack[0]`.
+    pub stack: Vec<LocationIndex>,
+    pub ruby_thread_id: Option<u64>,
+}
+
+/// Location represents a location (line) in the source code when a sample was captured.
+#[derive(Clone, PartialEq, Serialize, Deserialize)]
+pub struct Location {
+    pub function_index: FunctionIndex,
+    pub lineno: i32,
+    pub address: Option<usize>,
+}
+
+/// Function represents a Ruby method or a C function in the profile.
+#[derive(Clone, PartialEq, Serialize, Deserialize)]
+pub struct Function {
+    pub implementation: FunctionImplementation,
+    pub name: Option<String>, // unique key
+    pub filename: Option<String>,
+    /// The first line number in the method/function definition.
+    /// For the actual location (line) which was hit during sample capture, refer to `Location.lineno`.
+    pub start_lineno: Option<i32>,
+    pub start_address: Option<usize>,
+}
+
+#[derive(Clone, PartialEq, Serialize, Deserialize)]
+pub enum FunctionImplementation {
+    Ruby,
+    C,
+}

data/ext/pf2/src/serialization/serializer.rs

@@ -0,0 +1,146 @@
+use std::ffi::CStr;
+
+use rb_sys::*;
+
+use super::profile::{Function, FunctionImplementation, Location, LocationIndex, Profile, Sample};
+use crate::util::RTEST;
+
+pub struct ProfileSerializer2 {
+    profile: Profile,
+}
+
+impl ProfileSerializer2 {
+    pub fn new() -> ProfileSerializer2 {
+        ProfileSerializer2 {
+            profile: Profile {
+                start_timestamp_ns: 0,
+                duration_ns: 0,
+                samples: vec![],
+                locations: vec![],
+                functions: vec![],
+            },
+        }
+    }
+
+    pub fn serialize(&mut self, source: &crate::profile::Profile) -> String {
+        // Fill in meta fields
+        self.profile.start_timestamp_ns = source
+            .start_timestamp
+            .duration_since(std::time::UNIX_EPOCH)
+            .unwrap()
+            .as_nanos();
+        self.profile.duration_ns = source
+            .end_instant
+            .unwrap()
+            .duration_since(source.start_instant)
+            .as_nanos();
+
+        // Create a Sample for each sample collected
+        for sample in source.samples.iter() {
+            let mut stack: Vec<LocationIndex> = vec![];
+
+            // Iterate over the Ruby stack
+            let ruby_stack_depth = sample.line_count;
+            for i in 0..ruby_stack_depth {
+                let frame: VALUE = sample.frames[i as usize];
+                let lineno: i32 = sample.linenos[i as usize];
+
+                // Get the Location corresponding to the frame.
+                let location_index = self.process_ruby_frame(frame, lineno);
+
+                stack.push(location_index);
+            }
+
+            self.profile.samples.push(Sample {
+                stack,
+                ruby_thread_id: Some(sample.ruby_thread),
+            });
+        }
+
+        serde_json::to_string(&self.profile).unwrap()
+    }
+
+    /// Process a collected Ruby frame.
+    /// Calling this method will modify `self.profile` in place.
+    ///
+    /// Returns the index of the location in `locations`.
+    fn process_ruby_frame(&mut self, frame: VALUE, lineno: i32) -> LocationIndex {
+        // Build a Function corresponding to the frame, and get the index in `functions`
+        let function = Self::extract_function_from_frame(frame);
+        let function_index = match self
+            .profile
+            .functions
+            .iter_mut()
+            .position(|f| *f == function)
+        {
+            Some(index) => index,
+            None => {
+                self.profile.functions.push(function);
+                self.profile.functions.len() - 1
+            }
+        };
+
+        // Build a Location based on (1) the Function and (2) the actual line hit during sampling.
+        let location = Location {
+            function_index,
+            lineno,
+            address: None,
+        };
+        // Get the index of the location in `locations`
+        match self
+            .profile
+            .locations
+            .iter_mut()
+            .position(|l| *l == location)
+        {
+            Some(index) => index,
+            None => {
+                self.profile.locations.push(location);
+                self.profile.locations.len() - 1
+            }
+        }
+    }
+
+    fn extract_function_from_frame(frame: VALUE) -> Function {
+        unsafe {
+            let mut frame_full_label: VALUE = rb_profile_frame_full_label(frame);
+            let frame_full_label: Option<String> = if RTEST(frame_full_label) {
+                Some(
+                    CStr::from_ptr(rb_string_value_cstr(&mut frame_full_label))
+                        .to_str()
+                        .unwrap()
+                        .to_owned(),
+                )
+            } else {
+                None
+            };
+
+            let mut frame_path: VALUE = rb_profile_frame_path(frame);
+            let frame_path: Option<String> = if RTEST(frame_path) {
+                Some(
+                    CStr::from_ptr(rb_string_value_cstr(&mut frame_path))
+                        .to_str()
+                        .unwrap()
+                        .to_owned(),
+                )
+            } else {
+                None
+            };
+
+            let frame_first_lineno: VALUE = rb_profile_frame_first_lineno(frame);
+            let frame_first_lineno: Option<i32> = if RTEST(frame_first_lineno) {
+                Some(rb_num2int(frame_first_lineno).try_into().unwrap())
+            } else {
+                None
+            };
+
+            Function {
+                implementation: FunctionImplementation::Ruby,
+                name: frame_full_label,
+                filename: frame_path,
+                start_lineno: frame_first_lineno,
+                start_address: None,
+            }
+        }
+    }
+}

data/ext/pf2/src/serialization.rs

@@ -0,0 +1,2 @@
+pub mod profile;
+pub mod serializer;

data/ext/pf2/src/session/configuration.rs

@@ -6,9 +6,16 @@ use rb_sys::*;
 
 use crate::util::cstr;
 
+#[cfg(target_os = "linux")]
 pub const DEFAULT_SCHEDULER: Scheduler = Scheduler::Signal;
-pub const DEFAULT_INTERVAL: Duration = Duration::from_millis(49);
+#[cfg(target_os = "linux")]
 pub const DEFAULT_TIME_MODE: TimeMode = TimeMode::CpuTime;
+#[cfg(not(target_os = "linux"))]
+pub const DEFAULT_SCHEDULER: Scheduler = Scheduler::TimerThread;
+#[cfg(not(target_os = "linux"))]
+pub const DEFAULT_TIME_MODE: TimeMode = TimeMode::WallTime;
+
+pub const DEFAULT_INTERVAL: Duration = Duration::from_millis(9);
 
 #[derive(Clone, Debug)]
 pub struct Configuration {
@@ -16,6 +23,7 @@ pub struct Configuration {
     pub interval: Duration,
     pub time_mode: TimeMode,
     pub target_ruby_threads: Threads,
+    pub use_experimental_serializer: bool,
 }
 
 #[derive(Clone, Debug, PartialEq)]

data/ext/pf2/src/session/ruby_object.rs

@@ -1,7 +1,7 @@
 use std::ffi::{c_int, c_void};
 use std::mem;
 use std::mem::ManuallyDrop;
-use std::ptr::null_mut;
+use std::ptr::{addr_of, null_mut};
 
 use rb_sys::*;
 
@@ -43,7 +43,7 @@ impl SessionRubyObject {
     // Extract the SessionRubyObject struct from a Ruby object
     unsafe fn get_struct_from(obj: VALUE) -> ManuallyDrop<Box<Self>> {
         unsafe {
-            let ptr = rb_check_typeddata(obj, &RBDATA);
+            let ptr = rb_check_typeddata(obj, addr_of!(RBDATA));
             ManuallyDrop::new(Box::from_raw(ptr as *mut SessionRubyObject))
         }
     }
@@ -55,7 +55,11 @@ impl SessionRubyObject {
         let rb_mPf2: VALUE = rb_define_module(cstr!("Pf2"));
         let rb_cSession = rb_define_class_under(rb_mPf2, cstr!("Session"), rb_cObject);
         // Wrap the struct into a Ruby object
-        rb_data_typed_object_wrap(rb_cSession, Box::into_raw(obj) as *mut c_void, &RBDATA)
+        rb_data_typed_object_wrap(
+            rb_cSession,
+            Box::into_raw(obj) as *mut c_void,
+            addr_of!(RBDATA),
+        )
     }
 
     unsafe extern "C" fn dmark(ptr: *mut c_void) {

data/ext/pf2/src/session.rs

@@ -38,7 +38,7 @@ impl Session {
         unsafe {
             rb_scan_args(argc, argv, cstr!(":"), &kwargs);
         };
-        let mut kwargs_values: [VALUE; 4] = [Qnil.into(); 4];
+        let mut kwargs_values: [VALUE; 5] = [Qnil.into(); 5];
         unsafe {
             rb_get_kwargs(
                 kwargs,
@@ -47,10 +47,11 @@ impl Session {
                     rb_intern(cstr!("threads")),
                     rb_intern(cstr!("time_mode")),
                     rb_intern(cstr!("scheduler")),
+                    rb_intern(cstr!("use_experimental_serializer")),
                 ]
                 .as_mut_ptr(),
                 0,
-                4,
+                5,
                 kwargs_values.as_mut_ptr(),
             );
         };
@@ -59,12 +60,15 @@ impl Session {
         let threads = Self::parse_option_threads(kwargs_values[1]);
         let time_mode = Self::parse_option_time_mode(kwargs_values[2]);
         let scheduler = Self::parse_option_scheduler(kwargs_values[3]);
+        let use_experimental_serializer =
+            Self::parse_option_use_experimental_serializer(kwargs_values[4]);
 
         let configuration = Configuration {
             scheduler,
             interval,
             target_ruby_threads: threads.clone(),
             time_mode,
+            use_experimental_serializer,
         };
 
         match configuration.validate() {
@@ -93,12 +97,17 @@ impl Session {
             )),
         };
 
+        let running = Arc::new(AtomicBool::new(false));
+
         let new_thread_watcher = match threads {
             configuration::Threads::All => {
                 let scheduler = Arc::clone(&scheduler);
+                let running = Arc::clone(&running);
                 Some(NewThreadWatcher::watch(move |thread: VALUE| {
-                    log::debug!("New Ruby thread detected: {:?}", thread);
-                    scheduler.on_new_thread(thread);
+                    if running.load(Ordering::Relaxed) {
+                        log::debug!("New Ruby thread detected: {:?}", thread);
+                        scheduler.on_new_thread(thread);
+                    }
                 }))
             }
             configuration::Threads::Targeted(_) => None,
@@ -108,7 +117,7 @@ impl Session {
             configuration,
             scheduler,
             profile,
-            running: Arc::new(AtomicBool::new(false)),
+            running,
             new_thread_watcher,
         }
     }
@@ -122,10 +131,10 @@ impl Session {
         let interval_ms = unsafe { rb_num2long(value) };
         Duration::from_millis(interval_ms.try_into().unwrap_or_else(|_| {
             eprintln!(
-                "[Pf2] Warning: Specified interval ({}) is not valid. Using default value (49ms).",
+                "[Pf2] Warning: Specified interval ({}) is not valid. Using default value (9ms).",
                 interval_ms
             );
-            49
+            9
         }))
     }
 
@@ -202,6 +211,13 @@ impl Session {
         scheduler
     }
 
+    fn parse_option_use_experimental_serializer(value: VALUE) -> bool {
+        if value == Qundef as VALUE {
+            return false;
+        }
+        RTEST(value)
+    }
+
     pub fn start(&mut self) -> VALUE {
         self.running.store(true, Ordering::Relaxed);
         self.start_profile_buffer_flusher_thread();

data/ext/pf2/src/signal_scheduler.rs

@@ -5,6 +5,7 @@ use crate::profile_serializer::ProfileSerializer;
 use crate::ruby_internal_apis::rb_thread_getcpuclockid;
 use crate::sample::Sample;
 use crate::scheduler::Scheduler;
+use crate::serialization::serializer::ProfileSerializer2;
 use crate::session::configuration::{self, Configuration};
 
 use core::panic;
@@ -46,6 +47,7 @@ impl Scheduler for SignalScheduler {
         match self.profile.try_write() {
             Ok(mut profile) => {
                 profile.flush_temporary_sample_buffer();
+                profile.end_instant = Some(std::time::Instant::now());
             }
             Err(_) => {
                 println!("[pf2 ERROR] stop: Failed to acquire profile lock.");
@@ -56,7 +58,11 @@ impl Scheduler for SignalScheduler {
         let profile = self.profile.try_read().unwrap();
         log::debug!("Number of samples: {}", profile.samples.len());
 
-        let serialized = ProfileSerializer::serialize(&profile);
+        let serialized = if self.configuration.use_experimental_serializer {
+            ProfileSerializer2::new().serialize(&profile)
+        } else {
+            ProfileSerializer::serialize(&profile)
+        };
         let serialized = CString::new(serialized).unwrap();
         unsafe { rb_str_new_cstr(serialized.as_ptr()) }
     }
@@ -103,6 +109,7 @@ impl SignalScheduler {
         if err != 0 {
             panic!("sigaction failed: {}", err);
         }
+        log::debug!("Signal handler installed");
     }
 
     // Respond to the signal and collect a sample.

data/ext/pf2/src/timer_thread_scheduler.rs

@@ -12,6 +12,7 @@ use crate::profile::Profile;
 use crate::profile_serializer::ProfileSerializer;
 use crate::sample::Sample;
 use crate::scheduler::Scheduler;
+use crate::serialization::serializer::ProfileSerializer2;
 use crate::session::configuration::{self, Configuration};
 use crate::util::*;
 
@@ -61,6 +62,7 @@ impl Scheduler for TimerThreadScheduler {
         match self.profile.try_write() {
             Ok(mut profile) => {
                 profile.flush_temporary_sample_buffer();
+                profile.end_instant = Some(std::time::Instant::now());
             }
             Err(_) => {
                 println!("[pf2 ERROR] stop: Failed to acquire profile lock.");
@@ -71,7 +73,11 @@ impl Scheduler for TimerThreadScheduler {
         let profile = self.profile.try_read().unwrap();
         log::debug!("Number of samples: {}", profile.samples.len());
 
-        let serialized = ProfileSerializer::serialize(&profile);
+        let serialized = if self.configuration.use_experimental_serializer {
+            ProfileSerializer2::new().serialize(&profile)
+        } else {
+            ProfileSerializer::serialize(&profile)
+        };
         let serialized = CString::new(serialized).unwrap();
         unsafe { rb_str_new_cstr(serialized.as_ptr()) }
     }

data/lib/pf2/cli.rb

@@ -55,7 +55,7 @@ module Pf2
       option_parser.parse!(argv)
 
       profile = JSON.parse(File.read(argv[0]), symbolize_names: true, max_nesting: false)
-      report = JSON.generate(Pf2::Reporter.new(profile).emit)
+      report = JSON.generate(Pf2::Reporter::FirefoxProfiler.new(profile).emit)
 
       if options[:output_file]
         File.write(options[:output_file], report)