sperf 0.1.0 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: aecc23432b8dba72018c524b1fb6653a0c83a44e9e8b2c9af17c87cde20b648b
-  data.tar.gz: fbdf1dddcb5b8fef86e358f315a801478bfcad7768d8f28cbcf82726c67d529c
+  metadata.gz: 125090cb17cacbc9157402fcb9db54117011ccde812da775ea00b6c1f6bee535
+  data.tar.gz: 1430d997988a6538059a0c63be28d4f05f43681d1f2efbd84020490308a5c279
 SHA512:
-  metadata.gz: ff265b78dd2e237dac4d07a32b7459e07e73d77504347556945878e4addc1ccf89c47c409824591ff800cbe5605a863ae536b200c7f7c5eca5d06bbbd4ca6c05
-  data.tar.gz: 950c3860737f37a9d57d15dae9db259635ebe94494096ad06c0489ab6c028827ea2b24d7e0046462e3b57ea546173993b2ed3e0c910bc677828b23b01ed718e9
+  metadata.gz: 17a52cfc856ae47f254bf0df3450ff76cd471703c97e029907abbf639aa9dd8d6971ef8b18acf6a9784b87b295981533776c147b0fc31993e33dcf528cf15a3d
+  data.tar.gz: 6bbad7152c998859f4ec1f07d42eeca8824918ad635b0454fbe13635d9b913ad309b09f8e7c760f5cdd4cc1d32d1316ba50a5fb7c1863e7718cb1df01a2761ad

data/README.md

@@ -9,6 +9,7 @@ A safepoint-based sampling performance profiler for Ruby. Uses actual time delta
 - Requires Ruby >= 3.4.0
 - Output: pprof protobuf, collapsed stacks, or text report
 - Modes: CPU time (per-thread) and wall time (with GVL/GC tracking)
+- [Online manual](https://ko1.github.io/sperf/docs/manual/) | [GitHub](https://github.com/ko1/sperf)
 
 ## Quick Start
 
@@ -56,10 +57,12 @@ Profile without code changes (e.g., Rails):
 SPERF_ENABLED=1 SPERF_MODE=wall SPERF_OUTPUT=profile.pb.gz ruby app.rb
 ```
 
-Run `sperf help` for full documentation (all options, output interpretation, diagnostics guide).
+Run `sperf help` for full documentation, or see the [online manual](https://ko1.github.io/sperf/).
 
 ## Subcommands
 
+Inspired by Linux `perf` — familiar subcommand interface for profiling workflows.
+
 | Command | Description |
 |---------|-------------|
 | `sperf record` | Profile a command and save to file |
@@ -79,8 +82,8 @@ Ruby's sampling profilers collect stack traces at **safepoints**, not at the exa
 sperf uses **time deltas as sample weights**:
 
 ```
-Timer thread (pthread)           VM thread (postponed job)
-─────────────────────           ────────────────────────
+Timer (signal or thread)         VM thread (postponed job)
+────────────────────────         ────────────────────────
   every 1/frequency sec:          at next safepoint:
     rb_postponed_job_trigger()  →   sperf_sample_job()
                                       time_now = read_clock()
@@ -88,6 +91,9 @@ Timer thread (pthread)           VM thread (postponed job)
                                       record(backtrace, weight)
 ```
 
+On Linux, the timer uses `timer_create` + signal delivery (no extra thread).
+On other platforms, a dedicated pthread with `nanosleep` is used.
+
 If a safepoint is delayed, the sample carries proportionally more weight. The total weight equals the total time, accurately distributed across call stacks.
 
 ### Modes
@@ -110,6 +116,24 @@ sperf hooks GVL and GC events to attribute non-CPU time:
 | `[GC marking]` | Time in GC mark phase |
 | `[GC sweeping]` | Time in GC sweep phase |
 
+## Pros & Cons
+
+### Pros
+
+- **Safepoint-based, but accurate**: Unlike signal-based profilers (e.g., stackprof), sperf samples at safepoints. Safepoint sampling is safer — no async-signal-safety constraints, so backtraces and VM state (GC phase, GVL ownership) can be inspected reliably. The downside is less precise sampling timing, but sperf compensates by using actual time deltas as sample weights — so the profiling results faithfully reflect where time is actually spent.
+- **GVL & GC visibility** (wall mode): Attributes off-GVL time, GVL contention, and GC phases to the responsible call stacks with synthetic frames.
+- **Low overhead**: No extra thread on Linux (signal-based timer). Sampling overhead is ~1-5 us per sample.
+- **pprof compatible**: Output works with `go tool pprof`, speedscope, and other standard tools.
+- **No code changes required**: Profile any Ruby program via CLI (`sperf stat ruby app.rb`) or environment variables (`SPERF_ENABLED=1`).
+- **perf-like CLI**: Familiar subcommand interface — `record`, `stat`, `report`, `diff` — inspired by Linux perf.
+
+### Cons
+
+- **Method-level only**: Profiles at the method level, not the line level. You can see which method is slow, but not which line within it.
+- **Ruby >= 3.4.0**: Requires recent Ruby for the internal APIs used (postponed jobs, thread event hooks).
+- **POSIX only**: Linux, macOS, etc. No Windows support.
+- **Safepoint sampling**: Cannot sample inside C extensions or during long-running C calls that don't reach a safepoint. Time spent there is attributed to the next sample.
+
 ## Output Formats
 
 | Format | Extension | Use case |

data/exe/sperf

@@ -1,5 +1,13 @@
 #!/usr/bin/env ruby
 require "optparse"
+require "socket"
+
+def find_available_port
+  server = TCPServer.new("localhost", 0)
+  port = server.addr[1]
+  server.close
+  port
+end
 
 HELP_TEXT = <<'HELP'
 sperf - safepoint-based sampling performance profiler for Ruby
@@ -22,12 +30,16 @@ CLI USAGE
     -f, --frequency HZ      Sampling frequency in Hz (default: 1000)
     -m, --mode MODE         cpu or wall (default: cpu)
     --format FORMAT         pprof, collapsed, or text (default: auto from extension)
+    --signal VALUE          Timer signal (Linux only): signal number, or 'false'
+                            for nanosleep thread (default: auto)
     -v, --verbose           Print sampling statistics to stderr
 
   stat: Run command and print performance summary to stderr.
     Always uses wall mode. No file output by default.
     -o, --output PATH       Also save profile to file (default: none)
     -f, --frequency HZ      Sampling frequency in Hz (default: 1000)
+    --signal VALUE          Timer signal (Linux only): signal number, or 'false'
+                            for nanosleep thread (default: auto)
     -v, --verbose           Print additional sampling statistics
 
     Shows: user/sys/real time, time breakdown (CPU execution, GVL blocked,
@@ -230,6 +242,7 @@ ENVIRONMENT VARIABLES
     SPERF_MODE=cpu|wall   Profiling mode
     SPERF_FORMAT=fmt      pprof, collapsed, or text
     SPERF_VERBOSE=1       Print statistics
+    SPERF_SIGNAL=N|false  Timer signal number or 'false' for nanosleep (Linux only)
 
 TIPS
 
@@ -316,7 +329,7 @@ when "report"
   when :text
     exec("go", "tool", "pprof", "-text", report_file)
   else
-    exec("go", "tool", "pprof", "-http=:0", report_file)
+    exec("go", "tool", "pprof", "-http=localhost:#{find_available_port}", report_file)
   end
 when "diff"
   # sperf diff: compare two pprof profiles via go tool pprof -diff_base
@@ -374,7 +387,7 @@ when "diff"
   when :text
     exec("go", "tool", "pprof", "-text", "-diff_base=#{base_file}", target_file)
   else
-    exec("go", "tool", "pprof", "-http=:0", "-diff_base=#{base_file}", target_file)
+    exec("go", "tool", "pprof", "-http=localhost:#{find_available_port}", "-diff_base=#{base_file}", target_file)
   end
 when "record", "stat"
   # continue below
@@ -388,6 +401,7 @@ output = (subcommand == "stat") ? nil : "sperf.data"
 frequency = 1000
 mode = (subcommand == "stat") ? "wall" : "cpu"
 format = nil
+signal = nil
 verbose = false
 
 parser = OptionParser.new do |opts|
@@ -412,6 +426,10 @@ parser = OptionParser.new do |opts|
     end
   end
 
+  opts.on("--signal VALUE", "Timer signal (Linux only): signal number, or 'false' for nanosleep thread") do |v|
+    signal = (v == "false") ? "false" : v
+  end
+
   opts.on("-v", "--verbose", "Print sampling statistics to stderr") do
     verbose = true
   end
@@ -448,6 +466,7 @@ ENV["SPERF_FREQUENCY"] = frequency.to_s
 ENV["SPERF_MODE"] = mode
 ENV["SPERF_FORMAT"] = format if format
 ENV["SPERF_VERBOSE"] = "1" if verbose
+ENV["SPERF_SIGNAL"] = signal if signal
 
 if subcommand == "stat"
   ENV["SPERF_STAT"] = "1"

data/ext/sperf/sperf.c

@@ -6,6 +6,14 @@
 #include <string.h>
 #include <stdlib.h>
 #include <unistd.h>
+#include <signal.h>
+
+#ifdef __linux__
+#define SPERF_USE_TIMER_SIGNAL 1
+#define SPERF_TIMER_SIGNAL_DEFAULT (SIGRTMIN + 8)
+#else
+#define SPERF_USE_TIMER_SIGNAL 0
+#endif
 
 #define SPERF_MAX_STACK_DEPTH 512
 #define SPERF_INITIAL_SAMPLES 1024
@@ -49,6 +57,10 @@ typedef struct sperf_profiler {
     int mode; /* 0 = cpu, 1 = wall */
     volatile int running;
     pthread_t timer_thread;
+#if SPERF_USE_TIMER_SIGNAL
+    timer_t timer_id;
+    int timer_signal;     /* >0: use timer signal, 0: use nanosleep thread */
+#endif
     rb_postponed_job_handle_t pj_handle;
     sperf_sample_t *samples;
     size_t sample_count;
@@ -407,7 +419,15 @@ sperf_sample_job(void *arg)
         (ts_end.tv_nsec - ts_start.tv_nsec);
 }
 
-/* ---- Timer thread ---- */
+/* ---- Timer ---- */
+
+#if SPERF_USE_TIMER_SIGNAL
+static void
+sperf_signal_handler(int sig)
+{
+    rb_postponed_job_trigger(g_profiler.pj_handle);
+}
+#endif
 
 static void *
 sperf_timer_func(void *arg)
@@ -448,6 +468,9 @@ rb_sperf_start(int argc, VALUE *argv, VALUE self)
     VALUE opts;
     int frequency = 1000;
     int mode = 0; /* 0 = cpu, 1 = wall */
+#if SPERF_USE_TIMER_SIGNAL
+    int timer_signal = SPERF_TIMER_SIGNAL_DEFAULT;
+#endif
 
     rb_scan_args(argc, argv, ":", &opts);
     if (!NIL_P(opts)) {
@@ -469,6 +492,21 @@ rb_sperf_start(int argc, VALUE *argv, VALUE self)
                 rb_raise(rb_eArgError, "mode must be :cpu or :wall");
             }
         }
+#if SPERF_USE_TIMER_SIGNAL
+        VALUE vsig = rb_hash_aref(opts, ID2SYM(rb_intern("signal")));
+        if (!NIL_P(vsig)) {
+            if (RTEST(vsig)) {
+                timer_signal = NUM2INT(vsig);
+                if (timer_signal < SIGRTMIN || timer_signal > SIGRTMAX) {
+                    rb_raise(rb_eArgError, "signal must be between SIGRTMIN(%d) and SIGRTMAX(%d)",
+                             SIGRTMIN, SIGRTMAX);
+                }
+            } else {
+                /* signal: false or signal: 0 → use nanosleep thread */
+                timer_signal = 0;
+            }
+        }
+#endif
     }
 
     if (g_profiler.running) {
@@ -534,8 +572,43 @@ rb_sperf_start(int argc, VALUE *argv, VALUE self)
 
     g_profiler.running = 1;
 
-    if (pthread_create(&g_profiler.timer_thread, NULL, sperf_timer_func, &g_profiler) != 0) {
-        g_profiler.running = 0;
+#if SPERF_USE_TIMER_SIGNAL
+    g_profiler.timer_signal = timer_signal;
+
+    if (timer_signal > 0) {
+        struct sigaction sa;
+        struct sigevent sev;
+        struct itimerspec its;
+
+        memset(&sa, 0, sizeof(sa));
+        sa.sa_handler = sperf_signal_handler;
+        sa.sa_flags = SA_RESTART;
+        sigaction(g_profiler.timer_signal, &sa, NULL);
+
+        memset(&sev, 0, sizeof(sev));
+        sev.sigev_notify = SIGEV_SIGNAL;
+        sev.sigev_signo = g_profiler.timer_signal;
+        if (timer_create(CLOCK_MONOTONIC, &sev, &g_profiler.timer_id) != 0) {
+            g_profiler.running = 0;
+            signal(g_profiler.timer_signal, SIG_DFL);
+            goto timer_fail;
+        }
+
+        its.it_value.tv_sec = 0;
+        its.it_value.tv_nsec = 1000000000L / g_profiler.frequency;
+        its.it_interval = its.it_value;
+        timer_settime(g_profiler.timer_id, 0, &its, NULL);
+    } else
+#endif
+    {
+        if (pthread_create(&g_profiler.timer_thread, NULL, sperf_timer_func, &g_profiler) != 0) {
+            g_profiler.running = 0;
+            goto timer_fail;
+        }
+    }
+
+    if (0) {
+timer_fail:
         {
             VALUE cur = rb_thread_current();
             sperf_thread_data_t *td = (sperf_thread_data_t *)rb_internal_thread_specific_get(cur, g_profiler.ts_key);
@@ -550,7 +623,7 @@ rb_sperf_start(int argc, VALUE *argv, VALUE self)
         g_profiler.samples = NULL;
         free(g_profiler.frame_pool);
         g_profiler.frame_pool = NULL;
-        rb_raise(rb_eRuntimeError, "sperf: failed to create timer thread");
+        rb_raise(rb_eRuntimeError, "sperf: failed to create timer");
     }
 
     return Qtrue;
@@ -568,7 +641,15 @@ rb_sperf_stop(VALUE self)
     }
 
     g_profiler.running = 0;
-    pthread_join(g_profiler.timer_thread, NULL);
+#if SPERF_USE_TIMER_SIGNAL
+    if (g_profiler.timer_signal > 0) {
+        timer_delete(g_profiler.timer_id);
+        signal(g_profiler.timer_signal, SIG_DFL);
+    } else
+#endif
+    {
+        pthread_join(g_profiler.timer_thread, NULL);
+    }
 
     if (g_profiler.thread_hook) {
         rb_internal_thread_remove_event_hook(g_profiler.thread_hook);
@@ -657,9 +738,16 @@ sperf_after_fork_child(void)
 {
     if (!g_profiler.running) return;
 
-    /* Mark as not running — timer thread doesn't exist in child */
+    /* Mark as not running — timer doesn't exist in child */
     g_profiler.running = 0;
 
+#if SPERF_USE_TIMER_SIGNAL
+    /* timer_create timers are not inherited across fork; reset signal handler */
+    if (g_profiler.timer_signal > 0) {
+        signal(g_profiler.timer_signal, SIG_DFL);
+    }
+#endif
+
     /* Remove hooks so they don't fire with stale state */
     if (g_profiler.thread_hook) {
         rb_internal_thread_remove_event_hook(g_profiler.thread_hook);

data/lib/sperf/version.rb

@@ -0,0 +1,3 @@
+module Sperf
+  VERSION = "0.2.1"
+end

data/lib/sperf.rb

@@ -1,9 +1,9 @@
 require "sperf.so"
+require "sperf/version"
 require "zlib"
 require "stringio"
 
 module Sperf
-  VERSION = "0.1.0"
 
   @verbose = false
   @output = nil
@@ -17,13 +17,15 @@ module Sperf
   #   .collapsed → collapsed stacks (FlameGraph / speedscope compatible)
   #   .txt       → text report (human/AI readable flat + cumulative table)
   #   otherwise (.pb.gz etc) → pprof protobuf (gzip compressed)
-  def self.start(frequency: 1000, mode: :cpu, output: nil, verbose: false, format: nil, stat: false)
+  def self.start(frequency: 1000, mode: :cpu, output: nil, verbose: false, format: nil, stat: false, signal: nil)
     @verbose = verbose || ENV["SPERF_VERBOSE"] == "1"
     @output = output
     @format = format
     @stat = stat
     @stat_start_mono = Process.clock_gettime(Process::CLOCK_MONOTONIC) if @stat
-    _c_start(frequency: frequency, mode: mode)
+    c_opts = { frequency: frequency, mode: mode }
+    c_opts[:signal] = signal unless signal.nil?
+    _c_start(**c_opts)
 
     if block_given?
       begin
@@ -357,11 +359,18 @@ module Sperf
     _sperf_mode = _sperf_mode_str == "wall" ? :wall : :cpu
     _sperf_format = ENV["SPERF_FORMAT"] ? ENV["SPERF_FORMAT"].to_sym : nil
     _sperf_stat = ENV["SPERF_STAT"] == "1"
-    start(frequency: (ENV["SPERF_FREQUENCY"] || 1000).to_i, mode: _sperf_mode,
-          output: _sperf_stat ? ENV["SPERF_OUTPUT"] : (ENV["SPERF_OUTPUT"] || "sperf.data"),
-          verbose: ENV["SPERF_VERBOSE"] == "1",
-          format: _sperf_format,
-          stat: _sperf_stat)
+    _sperf_signal = case ENV["SPERF_SIGNAL"]
+                    when nil then nil
+                    when "false" then false
+                    else ENV["SPERF_SIGNAL"].to_i
+                    end
+    _sperf_start_opts = { frequency: (ENV["SPERF_FREQUENCY"] || 1000).to_i, mode: _sperf_mode,
+                          output: _sperf_stat ? ENV["SPERF_OUTPUT"] : (ENV["SPERF_OUTPUT"] || "sperf.data"),
+                          verbose: ENV["SPERF_VERBOSE"] == "1",
+                          format: _sperf_format,
+                          stat: _sperf_stat }
+    _sperf_start_opts[:signal] = _sperf_signal unless _sperf_signal.nil?
+    start(**_sperf_start_opts)
     at_exit { stop }
   end
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: sperf
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.1
 platform: ruby
 authors:
   - Koichi Sasada
@@ -53,6 +53,7 @@ files:
   - ext/sperf/extconf.rb
   - ext/sperf/sperf.c
   - lib/sperf.rb
+  - lib/sperf/version.rb
 homepage: "https://github.com/ko1/sperf"
 licenses:
   - MIT