pf2 0.8.0 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e5c67ca63f5a380dd45c2a95dc089f433ff9f8f82c6faf69b9cece4364e1c372
-  data.tar.gz: a07f99f52fd9ccff04d031f6a6d195f44d17c11a6fc885a47a92190503c0cac8
+  metadata.gz: 6a0dc2d338a482c56472ec6279cc4fd111c4263a540ab00872d57439a14244af
+  data.tar.gz: 56bdc8e81a1d4bccee07d7785eec713329c8ec4b9e659f2b494e12e8e016e60a
 SHA512:
-  metadata.gz: 1a3f015a08e3c16d44263d8fe413a755b0e3a3c151fbc0144eeb120670b76ac7bcfb297ce3a6284c283bac158b1c7d1892d48af867fc4e52a2126944e71c0f57
-  data.tar.gz: e4a3c4198895216ac1a2e706e3732d8c086683eeee3b08a484d28de367d28b3d43fc507909318713cd8e67429d6eb831fd9cff71060966c0383716a8699fb0f2
+  metadata.gz: 43449c0433cfdc390aecf5335f2a8631d11a0a41ac3afc6fc469909e5fd28c45bde16de8fbcff5229c16551d26a2b47210ff2342dea5b190a47ca128e9656c80
+  data.tar.gz: e6f5f2481932100cd82504dcb3b24e71b123b1263a2588b584cf5e72e53817f2004c7ffe6e96ff12f9815975ddfeac679219468a1af9223f6b5a367b3ec0b5e6

data/CHANGELOG.md

@@ -1,5 +1,16 @@
 ## [Unreleased]
 
+## [0.9.0] - 2025-03-22
+
+## Added
+
+- `pf2 annotate` command
+- A new sample collection backend implemented in C
+
+## Changed
+
+- Set SA_RESTART flag to reduce EINTRs in profiled code
+
 ## [0.8.0] - 2025-01-27
 
 ## Added

data/README.md

@@ -61,6 +61,12 @@ Profiles can be visualized using the [Firefox Profiler](https://profiler.firefox
 $ pf2 report -o report.json my_program.pf2profile
 ```
 
+Alternatively, `pf2 annotate` can be used to display hit counts side-by-side with source code.
+
+```console
+$ pf2 annotate my_program.pf2prof
+```
+
 ### Configuration
 
 Pf2 accepts the following configuration keys:
@@ -129,6 +135,11 @@ Future Plans
 - Implement a "tracing" scheduler, using the C TracePoint API
 - more
 
+Development
+--------
+
+See [doc/development.md](doc/development.md).
+
 
 License
 --------

data/Rakefile

@@ -4,8 +4,15 @@ require 'minitest/test_task'
 
 task default: %i[]
 
-Rake::ExtensionTask.new 'pf2' do |ext|
-  ext.lib_dir = 'lib/pf2'
+if ENV['PF2_PF2C'] == '1'
+  Rake::ExtensionTask.new 'pf2c' do |ext|
+    ext.name = 'pf2'
+    ext.lib_dir = 'lib/pf2'
+  end
+else
+  Rake::ExtensionTask.new 'pf2' do |ext|
+    ext.lib_dir = 'lib/pf2'
+  end
 end
 
 Minitest::TestTask.create(:test) do |t|

data/doc/development.md

@@ -0,0 +1,11 @@
+Pf2 Development
+===========
+
+Releasing
+--------
+
+- Update CHANGELOG.md
+- Update version in lib/pf2/version.rb
+- Run `bundle install` to update Gemfile.lock
+- Commit changes
+- Run `bundle exec rake release`

data/examples/mandelbrot.rb

@@ -0,0 +1,69 @@
+# mandelbrot
+#
+# Generate a Mandelbrot set image using multiple threads.
+
+require 'bundler/inline'
+
+gemfile do
+  source 'https://rubygems.org'
+  gem 'chunky_png'
+end
+
+require 'pf2'
+
+def mandelbrot_pixel(x, y, width, height, max_iter)
+  real_part = (x - width / 2.0) * 4.0 / width
+  imag_part = (y - height / 2.0) * 4.0 / height
+
+  c = Complex(real_part, imag_part)
+  z = 0
+  iter = 0
+
+  while iter < max_iter && z.magnitude <= 2
+    z = z * z + c
+    iter += 1
+  end
+
+  iter
+end
+
+def generate_mandelbrot_image(width, height, max_iter, num_threads)
+  image = ChunkyPNG::Image.new(width, height, ChunkyPNG::Color::TRANSPARENT)
+  threads = []
+  num_threads.times do |thread_id|
+    threads << Thread.new(thread_id) do |tid|
+      start_row = tid * (height / num_threads)
+      end_row = (tid + 1) * (height / num_threads)
+
+      (start_row...end_row).each do |y|
+        width.times do |x|
+          color_value = mandelbrot_pixel(x, y, width, height, max_iter)
+          color = ChunkyPNG::Color.grayscale(color_value * 255 / max_iter)
+          image[x, y] = color
+        end
+      end
+    end
+  end
+  threads.each(&:join)
+  image
+end
+
+# Parameters
+width = 800
+height = 800
+max_iter = 1000
+threads = 16
+
+puts "width: #{width}, height: #{height}, max_iter: #{max_iter}, threads: #{threads}"
+
+Pf2.start
+
+start_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+generate_mandelbrot_image(width, height, max_iter, threads)
+end_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+
+profile = Pf2.stop
+File.binwrite("mandelbrot.pf2prof", Marshal.dump(profile))
+
+elapsed = end_time - start_time
+puts "Complete in #{elapsed} seconds"

data/examples/mandelbrot_ractor.rb

@@ -0,0 +1,77 @@
+# mandelbrot_ractor
+#
+# This script demonstrates how to profile a Ruby program that uses Ractors.
+
+require 'bundler/inline'
+
+gemfile do
+  source 'https://rubygems.org'
+  gem 'chunky_png'
+end
+
+def mandelbrot_pixel(x, y, width, height, max_iter)
+  real_part = (x - width / 2.0) * 4.0 / width
+  imag_part = (y - height / 2.0) * 4.0 / height
+
+  c = Complex(real_part, imag_part)
+  z = 0
+  iter = 0
+
+  while iter < max_iter && z.magnitude <= 2
+    z = z * z + c
+    iter += 1
+  end
+
+  iter
+end
+
+def generate_mandelbrot_image(width, height, max_iter, num_ractors)
+  ractors = []
+  num_ractors.times do |ractor_id|
+    ractors << Ractor.new(width, height, max_iter, num_ractors, ractor_id) do |width, height, max_iter, num_ractors, rid|
+      image = ChunkyPNG::Image.new(width, height, ChunkyPNG::Color::TRANSPARENT)
+
+      start_row = rid * (height / num_ractors)
+      end_row = (rid + 1) * (height / num_ractors)
+
+      (start_row...end_row).each do |y|
+        width.times do |x|
+          color_value = mandelbrot_pixel(x, y, width, height, max_iter)
+          color = ChunkyPNG::Color.grayscale(color_value * 255 / max_iter)
+          image[x, y] = color
+        end
+      end
+
+      Ractor.yield image
+    end
+  end
+  image_parts = ractors.map(&:take)
+
+  # Merge image_parts into a single image
+  image = ChunkyPNG::Image.new(width, height, ChunkyPNG::Color::TRANSPARENT)
+  image_parts.each do |image_part|
+    image_part.height.times do |y|
+      image_part.width.times do |x|
+        if !image_part[x, y].nil?
+          image[x, y] = image_part[x, y]
+        end
+      end
+    end
+  end
+  image
+end
+
+# Parameters
+width = 800
+height = 800
+max_iter = 1000
+ractors = 4
+
+puts "width: #{width}, height: #{height}, max_iter: #{max_iter}, ractors: #{ractors}"
+
+start_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+generate_mandelbrot_image(width, height, max_iter, ractors)
+end_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+
+elapsed = end_time - start_time
+puts "Complete in #{elapsed} seconds"

data/ext/pf2/src/signal_scheduler.rs

@@ -103,7 +103,7 @@ impl SignalScheduler {
     fn install_signal_handler(&self) {
         let mut sa: libc::sigaction = unsafe { mem::zeroed() };
         sa.sa_sigaction = Self::signal_handler as usize;
-        sa.sa_flags = libc::SA_SIGINFO;
+        sa.sa_flags = libc::SA_SIGINFO | libc::SA_RESTART;
         let err = unsafe { libc::sigaction(libc::SIGALRM, &sa, null_mut()) };
         if err != 0 {
             panic!("sigaction failed: {}", err);

data/ext/pf2c/backtrace_state.c

@@ -0,0 +1,10 @@
+#include <stdio.h>
+#include "backtrace_state.h"
+
+struct backtrace_state *global_backtrace_state = NULL;
+
+void
+pf2_backtrace_print_error(void *data, const char *msg, int errnum)
+{
+    printf("libbacktrace error callback: %s (errnum %d)\n", msg, errnum);
+}

data/ext/pf2c/backtrace_state.h

@@ -0,0 +1,10 @@
+#ifndef PF2_BACKTRACE_H
+#define PF2_BACKTRACE_H
+
+#include <backtrace.h>
+
+extern struct backtrace_state *global_backtrace_state;
+
+void pf2_backtrace_print_error(void *data, const char *msg, int errnum);
+
+#endif // PF2_BACKTRACE_H

data/ext/pf2c/configuration.c

@@ -0,0 +1,90 @@
+#include <ruby.h>
+#include <stdlib.h>
+
+#include "configuration.h"
+
+static int extract_interval_ms(VALUE options_hash);
+static enum pf2_time_mode extract_time_mode(VALUE options_hash);
+
+struct pf2_configuration *
+pf2_configuration_new_from_options_hash(VALUE options_hash)
+{
+    struct pf2_configuration *config = malloc(sizeof(struct pf2_configuration));
+    if (!config) {
+        rb_raise(rb_eRuntimeError, "Failed to allocate configuration");
+    }
+
+    config->interval_ms = extract_interval_ms(options_hash);
+    config->time_mode = extract_time_mode(options_hash);
+
+    return config;
+}
+
+static int
+extract_interval_ms(VALUE options_hash)
+{
+    if (options_hash == Qnil) {
+        return PF2_DEFAULT_INTERVAL_MS;
+    }
+
+    VALUE interval_ms = rb_hash_aref(options_hash, ID2SYM(rb_intern("interval_ms")));
+    if (interval_ms == Qundef || interval_ms == Qnil) {
+        return PF2_DEFAULT_INTERVAL_MS;
+    }
+
+    return NUM2INT(interval_ms);
+}
+
+static enum pf2_time_mode
+extract_time_mode(VALUE options_hash)
+{
+    if (options_hash == Qnil) {
+        return PF2_DEFAULT_TIME_MODE;
+    }
+
+    VALUE time_mode = rb_hash_aref(options_hash, ID2SYM(rb_intern("time_mode")));
+    if (time_mode == Qundef || time_mode == Qnil) {
+        return PF2_DEFAULT_TIME_MODE;
+    }
+
+    if (time_mode == ID2SYM(rb_intern("cpu"))) {
+        return PF2_TIME_MODE_CPU_TIME;
+    } else if (time_mode == ID2SYM(rb_intern("wall"))) {
+        return PF2_TIME_MODE_WALL_TIME;
+    } else {
+        VALUE time_mode_str = rb_obj_as_string(time_mode);
+        rb_raise(rb_eArgError, "Invalid time mode: %s", StringValueCStr(time_mode_str));
+    }
+}
+
+void
+pf2_configuration_free(struct pf2_configuration *config)
+{
+    free(config);
+}
+
+VALUE
+pf2_configuration_to_ruby_hash(struct pf2_configuration *config)
+{
+    VALUE hash = rb_hash_new();
+
+    // interval_ms
+    rb_hash_aset(hash, ID2SYM(rb_intern("interval_ms")), INT2NUM(config->interval_ms));
+
+    // time_mode
+    VALUE time_mode_sym;
+    switch (config->time_mode) {
+    case PF2_TIME_MODE_CPU_TIME:
+        time_mode_sym = ID2SYM(rb_intern("cpu"));
+        break;
+    case PF2_TIME_MODE_WALL_TIME:
+        time_mode_sym = ID2SYM(rb_intern("wall"));
+        break;
+    default:
+        rb_raise(rb_eRuntimeError, "Invalid time mode");
+        break;
+    }
+    rb_hash_aset(hash, ID2SYM(rb_intern("time_mode")), time_mode_sym);
+
+    return hash;
+}

data/ext/pf2c/configuration.h

@@ -0,0 +1,23 @@
+#ifndef PF2_CONFIGURATION_H
+#define PF2_CONFIGURATION_H
+
+#include <ruby.h>
+
+enum pf2_time_mode {
+    PF2_TIME_MODE_CPU_TIME,
+    PF2_TIME_MODE_WALL_TIME,
+};
+
+struct pf2_configuration {
+    int interval_ms;
+    enum pf2_time_mode time_mode;
+};
+
+#define PF2_DEFAULT_INTERVAL_MS 9
+#define PF2_DEFAULT_TIME_MODE PF2_TIME_MODE_CPU_TIME
+
+struct pf2_configuration *pf2_configuration_new_from_options_hash(VALUE options_hash);
+void pf2_configuration_free(struct pf2_configuration *config);
+VALUE pf2_configuration_to_ruby_hash(struct pf2_configuration *config);
+
+#endif // PF2_CONFIGURATION_H

data/ext/pf2c/extconf.rb

@@ -0,0 +1,21 @@
+require 'mkmf'
+require 'mini_portile2'
+
+libbacktrace = MiniPortile.new('libbacktrace', '1.0.0')
+libbacktrace.source_directory = File.expand_path(File.join(File.dirname(__FILE__), '..', '..', 'vendor', 'libbacktrace'))
+libbacktrace.configure_options << 'CFLAGS=-fPIC'
+libbacktrace.cook
+libbacktrace.mkmf_config
+
+if !have_func('backtrace_full', 'backtrace.h')
+  raise 'libbacktrace has not been properly configured'
+end
+
+append_ldflags('-lrt') # for timer_create
+append_cflags('-fvisibility=hidden')
+append_cflags('-DPF2_DEBUG') # TODO: make this conditional
+
+if have_func('timer_create')
+  $srcs = Dir.glob("#{File.join(File.dirname(__FILE__), '*.c')}")
+  create_makefile 'pf2/pf2'
+end

data/ext/pf2c/pf2.c

@@ -0,0 +1,17 @@
+#include <ruby.h>
+
+#include "session.h"
+
+VALUE rb_mPf2c;
+
+RUBY_FUNC_EXPORTED void
+Init_pf2(void)
+{
+    rb_mPf2c = rb_define_module("Pf2c");
+    VALUE rb_mPf2c_cSession = rb_define_class_under(rb_mPf2c, "Session", rb_cObject);
+    rb_define_alloc_func(rb_mPf2c_cSession, pf2_session_alloc);
+    rb_define_method(rb_mPf2c_cSession, "initialize", rb_pf2_session_initialize, -1);
+    rb_define_method(rb_mPf2c_cSession, "start", rb_pf2_session_start, 0);
+    rb_define_method(rb_mPf2c_cSession, "stop", rb_pf2_session_stop, 0);
+    rb_define_method(rb_mPf2c_cSession, "configuration", rb_pf2_session_configuration, 0);
+}

data/ext/pf2c/pf2.h

@@ -0,0 +1,8 @@
+#ifndef PF2_H
+#define PF2_H
+
+#include <ruby.h>
+
+RUBY_FUNC_EXPORTED void Init_pf2(void);
+
+#endif // PF2_H

data/ext/pf2c/ringbuffer.c

@@ -0,0 +1,74 @@
+#include <stdbool.h>
+#include <stdlib.h>
+
+#include "ringbuffer.h"
+
+struct pf2_ringbuffer *
+pf2_ringbuffer_new(int size) {
+    if (size <= 0) { return NULL; }
+
+    struct pf2_ringbuffer *ringbuf = malloc(sizeof(struct pf2_ringbuffer));
+    if (!ringbuf) { goto err; }
+    ringbuf->size = size + 1; // One extra slot is required to distinguish full from empty
+    ringbuf->head = 0;
+    ringbuf->tail = 0;
+    ringbuf->samples = malloc(ringbuf->size * sizeof(struct pf2_sample));
+    if (!ringbuf->samples) { goto err_free_ringbuf; }
+    return ringbuf;
+
+err_free_ringbuf:
+    free(ringbuf);
+err:
+    return NULL;
+}
+
+void
+pf2_ringbuffer_free(struct pf2_ringbuffer *ringbuf) {
+    free(ringbuf->samples);
+    free(ringbuf);
+}
+
+// Returns 0 on success, 1 on failure (buffer full).
+bool
+pf2_ringbuffer_push(struct pf2_ringbuffer *ringbuf, struct pf2_sample *sample) {
+    // Tail is only modified by the producer thread (us), so relaxed ordering is sufficient
+    const int current_tail = atomic_load_explicit(&ringbuf->tail, memory_order_relaxed);
+    const int next_tail = (current_tail + 1) % ringbuf->size;
+
+    // Check head to see if buffer is full. If next_tail == head, the buffer is full.
+    // Use acquire ordering to synchronize with the head update in pf2_ringbuffer_pop().
+    // This ensures we see the latest head value.
+    if (next_tail == atomic_load_explicit(&ringbuf->head, memory_order_acquire)) {
+        return false;  // Buffer full
+    }
+
+    // Copy the sample from the provided input pointer to the buffer.
+    ringbuf->samples[current_tail] = *sample;
+
+    // Use release ordering when updating tail to ensure the sample write is visible
+    // to the consumer before they see the new tail value
+    atomic_store_explicit(&ringbuf->tail, next_tail, memory_order_release);
+    return true;
+}
+
+// Returns 0 on success, 1 on failure (buffer empty).
+bool
+pf2_ringbuffer_pop(struct pf2_ringbuffer *ringbuf, struct pf2_sample *out) {
+    // Head won't be modifed by the producer thread. It is safe to use relaxed ordering.
+    const int current_head = atomic_load_explicit(&ringbuf->head, memory_order_relaxed);
+
+    // Check tail to see if buffer is empty. If head == tail, the buffer is empty.
+    // Use acquire ordering to synchronize with the tail update in pf2_ringbuffer_push().
+    // This ensures we see the latest tail value.
+    if (current_head == atomic_load_explicit(&ringbuf->tail, memory_order_acquire)) {
+        return false;  // Buffer empty
+    }
+
+    // Copy the sample from the buffer to the provided output pointer.
+    *out = ringbuf->samples[current_head];
+
+    // Use release ordering when updating head to ensure the sample read is complete
+    // before the producer sees the new head value
+    atomic_store_explicit(&ringbuf->head, (current_head + 1) % ringbuf->size, memory_order_release);
+    return true;
+}

data/ext/pf2c/ringbuffer.h

@@ -0,0 +1,24 @@
+#ifndef PF2_RINGBUFFER_H
+#define PF2_RINGBUFFER_H
+
+#include <stdatomic.h>
+#include <stdbool.h>
+
+#include "sample.h"
+
+// A lock-free ringbuffer for storing pf2_sample structs.
+// Thread safe for single-producer single-consumer (SPSC) use.
+struct pf2_ringbuffer {
+    int size;
+    atomic_int head;
+    atomic_int tail;
+    struct pf2_sample *samples;
+};
+
+struct pf2_ringbuffer * pf2_ringbuffer_new(int size);
+void pf2_ringbuffer_free(struct pf2_ringbuffer *ringbuf);
+// async-signal-safe
+bool pf2_ringbuffer_push(struct pf2_ringbuffer *ringbuf, struct pf2_sample *sample);
+bool pf2_ringbuffer_pop(struct pf2_ringbuffer *ringbuf, struct pf2_sample *out);
+
+#endif // RINGBUFFER_H

data/ext/pf2c/sample.c

@@ -0,0 +1,70 @@
+#include <stdbool.h>
+#include <time.h>
+
+#include <backtrace.h>
+#include <ruby.h>
+#include <ruby/debug.h>
+
+#include "backtrace_state.h"
+#include "sample.h"
+
+const int PF2_SAMPLE_MAX_NATIVE_DEPTH = 300;
+
+static int capture_native_backtrace(struct pf2_sample *sample);
+static int backtrace_on_ok(void *data, uintptr_t pc);
+
+// Capture a sample from the current thread.
+bool
+pf2_sample_capture(struct pf2_sample *sample)
+{
+    // Record the current time
+    struct timespec now;
+    clock_gettime(CLOCK_MONOTONIC, &now);
+    sample->timestamp_ns = (uint64_t)now.tv_sec * 1000000000ULL + (uint64_t)now.tv_nsec;
+
+    // Obtain the current stack from Ruby
+    sample->depth = rb_profile_frames(0, 200, sample->cmes, sample->linenos);
+
+    // Capture C-level backtrace
+    sample->native_stack_depth = capture_native_backtrace(sample);
+
+    return true;
+}
+
+// Struct to be passed to backtrace_on_ok
+struct bt_data {
+    struct pf2_sample *pf2_sample;
+    int index;
+};
+
+static int
+capture_native_backtrace(struct pf2_sample *sample)
+{
+    struct backtrace_state *state = global_backtrace_state;
+    assert(state != NULL);
+
+    struct bt_data data;
+    data.pf2_sample = sample;
+    data.index = 0;
+
+    // Capture the current PC
+    // Skip the first 2 frames (capture_native_backtrace, sigprof_handler)
+    backtrace_simple(state, 2, backtrace_on_ok, pf2_backtrace_print_error, &data);
+
+    return data.index;
+}
+
+static int
+backtrace_on_ok(void *data, uintptr_t pc)
+{
+    struct bt_data *bt_data = (struct bt_data *)data;
+    struct pf2_sample *sample = bt_data->pf2_sample;
+
+    // Store the PC value
+    if (bt_data->index < PF2_SAMPLE_MAX_NATIVE_DEPTH) {
+        sample->native_stack[bt_data->index] = pc;
+        bt_data->index++;
+    }
+
+    return 0; // Continue backtrace
+}

data/ext/pf2c/sample.h

@@ -0,0 +1,22 @@
+#ifndef PF2_SAMPLE_H
+#define PF2_SAMPLE_H
+
+#include <ruby.h>
+
+extern const int PF2_SAMPLE_MAX_NATIVE_DEPTH;
+
+struct pf2_sample {
+    int depth;
+    VALUE cmes[200];
+    int linenos[200];
+
+    size_t native_stack_depth;
+    uintptr_t native_stack[200];
+
+    uint64_t consumed_time_ns;
+    uint64_t timestamp_ns;
+};
+
+bool pf2_sample_capture(struct pf2_sample *sample);
+
+#endif // PF2_SAMPLE_H