sperf 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: aecc23432b8dba72018c524b1fb6653a0c83a44e9e8b2c9af17c87cde20b648b
-  data.tar.gz: fbdf1dddcb5b8fef86e358f315a801478bfcad7768d8f28cbcf82726c67d529c
+  metadata.gz: a2d6adf217328a161001097ef85fd62f9716a70089c254f6a831f2d8135d7a52
+  data.tar.gz: 92b0aefb1cd263fb86c84553b76cbf1f3124eff5c24e2ceb7d8e15e36f7d5012
 SHA512:
-  metadata.gz: ff265b78dd2e237dac4d07a32b7459e07e73d77504347556945878e4addc1ccf89c47c409824591ff800cbe5605a863ae536b200c7f7c5eca5d06bbbd4ca6c05
-  data.tar.gz: 950c3860737f37a9d57d15dae9db259635ebe94494096ad06c0489ab6c028827ea2b24d7e0046462e3b57ea546173993b2ed3e0c910bc677828b23b01ed718e9
+  metadata.gz: ee0ba192454f4794b1f9c064ea743978dde3f8eb5588c2ed590b0cb90604e26aa373223e4d7eaf3b8f3ed56b7a8564a79aef7cc40b9fd806b528ac8482a22dc2
+  data.tar.gz: e3519944bab031f83418893bdbf122ab0e308f1d72246dfca5315128365749c085fa3e1aa99f1fb75edd6d2fd2e7c3014fc86c996348420f69b32c80fb1a4b22

data/README.md

@@ -60,6 +60,8 @@ Run `sperf help` for full documentation (all options, output interpretation, dia
 
 ## Subcommands
 
+Inspired by Linux `perf` — familiar subcommand interface for profiling workflows.
+
 | Command | Description |
 |---------|-------------|
 | `sperf record` | Profile a command and save to file |
@@ -79,8 +81,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 +90,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 +115,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/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.0"
+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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: sperf
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 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