rperf 0.6.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 497392cfda8e82d1c37aadd0953b4c73b6bfb09870e6c612c1fd5fced0e3d24f
-  data.tar.gz: 6960be209fc3d4aac0f268378c5b7e1399027da0c5b7f498bcb4be0662012d62
+  metadata.gz: f19061984f2ea33bbcd569c43e8a7ece03071b8fbb442ebe108468eb07d96a14
+  data.tar.gz: 66bee438bd8459db8ce89129cef39bdaaba3ad82e348012c5d220fb5b6f3963f
 SHA512:
-  metadata.gz: '09fc32b7577ac9544a846c86c37a7ad11e9de00a27bbb0bbd25cbc2fcabe04e74741c64f9fb3cfe1a9663145e058215272a247766c7b8106218eda80cbcd838f'
-  data.tar.gz: 9d13e685c5a293c4d9033376509bf4b5c762a5f5155a2d5dd6e838d5a55dc79b9ef7d9521a5bcf65eac88a683f0e20cd7e5dac2680134aa565c709eb48452e40
+  metadata.gz: 3a9468eadacbb41afbc751bd767141a3db785a2eaa51e33549503fe160a8adb25f6612c0cc4c61381b8f8442836a970a23d29cda4fe696488ca85d2b048518a2
+  data.tar.gz: 5e8e6c6c24fbb264f352c98511481e5d448b6a07e390c72cc31beeab2aa03699cde22f2f04268531ab50572e7cfd54cab7235359915caa6c6b3c9eb40f26d4e9

data/docs/help.md

@@ -117,6 +117,7 @@ Rperf.save("profile.txt", data)
     output:     File path to write on stop (String or nil)
     verbose:    Print statistics to stderr (true/false, default: false)
     format:     :pprof, :collapsed, :text, or nil for auto-detect (Symbol or nil)
+    defer:      Start with timer paused; use Rperf.profile to activate (default: false)
 
 ### Rperf.stop return value
 
@@ -210,6 +211,33 @@ In pprof output, use labels for filtering and grouping:
     go tool pprof -tagroot=request profile.pb.gz
     go tool pprof -tagleaf=request profile.pb.gz
 
+### Rperf.start with defer: true
+
+With `defer: true`, the profiler infrastructure is set up but the sampling
+timer does not start. Use `Rperf.profile` to activate the timer for specific
+sections. Outside `profile` blocks, overhead is zero.
+
+### Rperf.profile(**labels, &block)
+
+Activates the sampling timer for the block duration and applies labels.
+Designed for use with `start(defer: true)` to profile only specific
+code paths.
+
+```ruby
+Rperf.start(defer: true, mode: :wall)
+
+Rperf.profile(endpoint: "/users") do
+  handle_request   # sampled with endpoint="/users"
+end
+# timer paused — zero overhead
+
+data = Rperf.stop
+```
+
+Nesting is supported: timer stays active until the outermost block exits.
+Also works with `start(defer: false)` — applies labels only (timer already
+running). Raises `RuntimeError` if not started, `ArgumentError` without block.
+
 ### Rperf.labels
 
 Returns the current thread's labels as a Hash. Empty hash if none set.
@@ -219,20 +247,20 @@ Returns the current thread's labels as a Hash. Empty hash if none set.
 Writes data to path. format: :pprof, :collapsed, or :text.
 nil auto-detects from extension.
 
-### Rperf::Middleware (Rack)
+### Rperf::RackMiddleware (Rack)
 
-Labels samples with the request endpoint. Requires `require "rperf/middleware"`.
+Labels samples with the request endpoint. Requires `require "rperf/rack"`.
 
 ```ruby
 # Rails
-Rails.application.config.middleware.use Rperf::Middleware
+Rails.application.config.middleware.use Rperf::RackMiddleware
 
 # Sinatra
-use Rperf::Middleware
+use Rperf::RackMiddleware
 ```
 
-The middleware only sets labels — start profiling separately.
-Option: `label_key:` (default: `:endpoint`).
+The middleware uses `Rperf.profile` to activate timer and set labels.
+Start profiling separately. Option: `label_key:` (default: `:endpoint`).
 
 ### Rperf::ActiveJobMiddleware
 

data/ext/rperf/rperf.c

@@ -36,6 +36,7 @@
 #define RPERF_FRAME_TABLE_OLD_KEYS_INITIAL 16
 #define RPERF_AGG_TABLE_INITIAL 1024
 #define RPERF_STACK_POOL_INITIAL 4096
+#define RPERF_PAUSED(prof) ((prof)->profile_refcount == 0)
 
 /* Synthetic frame IDs (reserved in frame_table, 0-based) */
 #define RPERF_SYNTHETIC_GVL_BLOCKED 0
@@ -182,6 +183,11 @@ typedef struct rperf_profiler {
     /* Label sets: Ruby Array of Hash objects, managed from Ruby side.
      * Index 0 is reserved (no labels). GC-marked via profiler_mark. */
     VALUE label_sets;  /* Ruby Array or Qnil */
+    /* Profile refcount: controls timer active/paused state.
+     * start(defer:false) sets to 1, start(defer:true) sets to 0.
+     * profile_inc/dec transitions 0↔1 arm/disarm the timer.
+     * Modified only under GVL, so plain int is safe. */
+    int profile_refcount;
 } rperf_profiler_t;
 
 static rperf_profiler_t g_profiler;
@@ -718,8 +724,8 @@ rperf_handle_suspended(rperf_profiler_t *prof, VALUE thread, rperf_thread_data_t
     if (depth <= 0) return;
     buf->frame_pool_count += depth;
 
-    /* Record normal sample (skip if first time — no prev_time) */
-    if (!is_first) {
+    /* Record normal sample (skip if first time — no prev_time, or if paused) */
+    if (!is_first && !RPERF_PAUSED(prof)) {
         int64_t weight = time_now - td->prev_time_ns;
         rperf_record_sample(prof, frame_start, depth, weight, RPERF_SAMPLE_NORMAL, td->thread_seq, td->label_set_id);
     }
@@ -758,7 +764,7 @@ rperf_handle_resumed(rperf_profiler_t *prof, VALUE thread, rperf_thread_data_t *
      * Both samples are written directly into the same buffer before calling
      * rperf_try_swap, so that a swap triggered by the first sample cannot
      * move the second into a different buffer with a stale frame_start. */
-    if (prof->mode == 1 && td->suspended_at_ns > 0) {
+    if (prof->mode == 1 && td->suspended_at_ns > 0 && !RPERF_PAUSED(prof)) {
         rperf_sample_buffer_t *buf = &prof->buffers[atomic_load_explicit(&prof->active_idx, memory_order_relaxed)];
         if (rperf_ensure_frame_pool_capacity(buf, RPERF_MAX_STACK_DEPTH) < 0) goto skip_gvl;
         size_t frame_start = buf->frame_pool_count;
@@ -851,6 +857,7 @@ rperf_gc_event_hook(rb_event_flag_t event, VALUE data, VALUE self, ID id, VALUE
     }
     else if (event & RUBY_INTERNAL_EVENT_GC_EXIT) {
         if (prof->gc.enter_ns <= 0) return;
+        if (RPERF_PAUSED(prof)) { prof->gc.enter_ns = 0; return; }
 
         int64_t wall_now = rperf_wall_time_ns();
         int64_t weight = wall_now - prof->gc.enter_ns;
@@ -888,6 +895,7 @@ rperf_sample_job(void *arg)
     rperf_profiler_t *prof = (rperf_profiler_t *)arg;
 
     if (!prof->running) return;
+    if (RPERF_PAUSED(prof)) return;
 
     /* Measure sampling overhead */
     struct timespec ts_start, ts_end;
@@ -985,20 +993,32 @@ rperf_worker_nanosleep_func(void *arg)
 
     CHECKED(pthread_mutex_lock(&prof->worker_mutex));
     while (prof->running) {
-        int ret = pthread_cond_timedwait(&prof->worker_cond, &prof->worker_mutex, &deadline);
-        if (ret != 0 && ret != ETIMEDOUT) {
-            fprintf(stderr, "rperf: pthread_cond_timedwait failed: %s\n", strerror(ret));
-            abort();
-        }
-        if (ret == ETIMEDOUT) {
-            prof->stats.trigger_count++;
-            rb_postponed_job_trigger(prof->pj_handle);
-            /* Advance deadline by interval */
+        if (RPERF_PAUSED(prof)) {
+            /* Paused: wait indefinitely until signaled (resume or stop) */
+            CHECKED(pthread_cond_wait(&prof->worker_cond, &prof->worker_mutex));
+            /* Reset deadline on wake to avoid burst of catch-up triggers */
+            clock_gettime(CLOCK_REALTIME, &deadline);
             deadline.tv_nsec += interval_ns;
             if (deadline.tv_nsec >= 1000000000L) {
                 deadline.tv_sec++;
                 deadline.tv_nsec -= 1000000000L;
             }
+        } else {
+            int ret = pthread_cond_timedwait(&prof->worker_cond, &prof->worker_mutex, &deadline);
+            if (ret != 0 && ret != ETIMEDOUT) {
+                fprintf(stderr, "rperf: pthread_cond_timedwait failed: %s\n", strerror(ret));
+                abort();
+            }
+            if (ret == ETIMEDOUT) {
+                prof->stats.trigger_count++;
+                rb_postponed_job_trigger(prof->pj_handle);
+                /* Advance deadline by interval */
+                deadline.tv_nsec += interval_ns;
+                if (deadline.tv_nsec >= 1000000000L) {
+                    deadline.tv_sec++;
+                    deadline.tv_nsec -= 1000000000L;
+                }
+            }
         }
         rperf_try_aggregate(prof);
     }
@@ -1110,14 +1130,15 @@ rperf_build_aggregated_result(rperf_profiler_t *prof)
 
 /* ---- Ruby API ---- */
 
-/* _c_start(frequency, mode, aggregate, signal)
+/* _c_start(frequency, mode, aggregate, signal, defer)
  *   frequency: Integer (Hz)
  *   mode:      0 = cpu, 1 = wall
  *   aggregate: 0 or 1
  *   signal:    Integer (RT signal number, 0 = nanosleep, -1 = default)
+ *   defer:     if truthy, start with timer paused (profile_refcount = 0)
  */
 static VALUE
-rb_rperf_start(VALUE self, VALUE vfreq, VALUE vmode, VALUE vagg, VALUE vsig)
+rb_rperf_start(VALUE self, VALUE vfreq, VALUE vmode, VALUE vagg, VALUE vsig, VALUE vdefer)
 {
     int frequency = NUM2INT(vfreq);
     int mode = NUM2INT(vmode);
@@ -1222,6 +1243,7 @@ rb_rperf_start(VALUE self, VALUE vfreq, VALUE vmode, VALUE vagg, VALUE vsig)
     clock_gettime(CLOCK_MONOTONIC, &g_profiler.start_monotonic);
 
     g_profiler.running = 1;
+    g_profiler.profile_refcount = RTEST(vdefer) ? 0 : 1;
 
 #if RPERF_USE_TIMER_SIGNAL
     g_profiler.timer_signal = timer_signal;
@@ -1269,7 +1291,12 @@ rb_rperf_start(VALUE self, VALUE vfreq, VALUE vmode, VALUE vagg, VALUE vsig)
         }
 
         its.it_value.tv_sec = 0;
-        its.it_value.tv_nsec = 1000000000L / g_profiler.frequency;
+        if (RPERF_PAUSED(&g_profiler)) {
+            /* defer mode: create timer but don't arm it */
+            its.it_value.tv_nsec = 0;
+        } else {
+            its.it_value.tv_nsec = 1000000000L / g_profiler.frequency;
+        }
         its.it_interval = its.it_value;
         if (timer_settime(g_profiler.timer_id, 0, &its, NULL) != 0) {
             timer_delete(g_profiler.timer_id);
@@ -1558,6 +1585,94 @@ rb_rperf_get_label_sets(VALUE self)
     return g_profiler.label_sets;
 }
 
+/* ---- Profile refcount API (timer pause/resume) ---- */
+
+/* Helper: arm the timer with the configured interval */
+static void
+rperf_arm_timer(rperf_profiler_t *prof)
+{
+#if RPERF_USE_TIMER_SIGNAL
+    if (prof->timer_signal > 0) {
+        struct itimerspec its;
+        its.it_value.tv_sec = 0;
+        its.it_value.tv_nsec = 1000000000L / prof->frequency;
+        its.it_interval = its.it_value;
+        timer_settime(prof->timer_id, 0, &its, NULL);
+        return;
+    }
+#endif
+    /* nanosleep mode: signal the worker to wake from cond_wait */
+    CHECKED(pthread_mutex_lock(&prof->worker_mutex));
+    CHECKED(pthread_cond_signal(&prof->worker_cond));
+    CHECKED(pthread_mutex_unlock(&prof->worker_mutex));
+}
+
+/* Helper: disarm the timer (stop firing) */
+static void
+rperf_disarm_timer(rperf_profiler_t *prof)
+{
+#if RPERF_USE_TIMER_SIGNAL
+    if (prof->timer_signal > 0) {
+        struct itimerspec its;
+        memset(&its, 0, sizeof(its));
+        timer_settime(prof->timer_id, 0, &its, NULL);
+        return;
+    }
+#endif
+    /* nanosleep mode: worker will see RPERF_PAUSED on next iteration */
+}
+
+/* Helper: reset prev_time_ns for all threads (called on resume to avoid
+ * inflated weight from pause duration).  Must be called with GVL held. */
+static void
+rperf_reset_thread_times(rperf_profiler_t *prof)
+{
+    VALUE threads = rb_funcall(rb_cThread, rb_intern("list"), 0);
+    long tc = RARRAY_LEN(threads);
+    for (long i = 0; i < tc; i++) {
+        VALUE thread = RARRAY_AREF(threads, i);
+        rperf_thread_data_t *td = (rperf_thread_data_t *)rb_internal_thread_specific_get(thread, prof->ts_key);
+        if (td) {
+            td->prev_time_ns = rperf_current_time_ns(prof, td);
+            td->prev_wall_ns = rperf_wall_time_ns();
+        }
+    }
+}
+
+/* _c_profile_inc() — increment profile refcount; resume timer on 0→1.
+ * Called with GVL held. */
+static VALUE
+rb_rperf_profile_inc(VALUE self)
+{
+    if (!g_profiler.running) return Qfalse;
+    g_profiler.profile_refcount++;
+    if (g_profiler.profile_refcount == 1) {
+        rperf_reset_thread_times(&g_profiler);
+        rperf_arm_timer(&g_profiler);
+    }
+    return Qtrue;
+}
+
+/* _c_profile_dec() — decrement profile refcount; pause timer on 1→0.
+ * Called with GVL held. */
+static VALUE
+rb_rperf_profile_dec(VALUE self)
+{
+    if (!g_profiler.running) return Qfalse;
+    g_profiler.profile_refcount--;
+    if (g_profiler.profile_refcount == 0) {
+        rperf_disarm_timer(&g_profiler);
+    }
+    return Qtrue;
+}
+
+/* _c_running?() — check if profiler is running. */
+static VALUE
+rb_rperf_running_p(VALUE self)
+{
+    return g_profiler.running ? Qtrue : Qfalse;
+}
+
 /* ---- Fork safety ---- */
 
 static void
@@ -1608,6 +1723,7 @@ rperf_after_fork_child(void)
     /* Reset stats */
     g_profiler.stats.sampling_count = 0;
     g_profiler.stats.sampling_total_ns = 0;
+    g_profiler.profile_refcount = 0;
     atomic_store_explicit(&g_profiler.swap_ready, 0, memory_order_relaxed);
 }
 
@@ -1617,13 +1733,16 @@ void
 Init_rperf(void)
 {
     VALUE mRperf = rb_define_module("Rperf");
-    rb_define_module_function(mRperf, "_c_start", rb_rperf_start, 4);
+    rb_define_module_function(mRperf, "_c_start", rb_rperf_start, 5);
     rb_define_module_function(mRperf, "_c_stop", rb_rperf_stop, 0);
     rb_define_module_function(mRperf, "_c_snapshot", rb_rperf_snapshot, 1);
     rb_define_module_function(mRperf, "_c_set_label", rb_rperf_set_label, 1);
     rb_define_module_function(mRperf, "_c_get_label", rb_rperf_get_label, 0);
     rb_define_module_function(mRperf, "_c_set_label_sets", rb_rperf_set_label_sets, 1);
     rb_define_module_function(mRperf, "_c_get_label_sets", rb_rperf_get_label_sets, 0);
+    rb_define_module_function(mRperf, "_c_profile_inc", rb_rperf_profile_inc, 0);
+    rb_define_module_function(mRperf, "_c_profile_dec", rb_rperf_profile_dec, 0);
+    rb_define_module_function(mRperf, "_c_running?", rb_rperf_running_p, 0);
 
     memset(&g_profiler, 0, sizeof(g_profiler));
     g_profiler.label_sets = Qnil;

data/lib/rperf/active_job.rb

@@ -5,7 +5,7 @@ module Rperf::ActiveJobMiddleware
 
   included do
     around_perform do |job, block|
-      Rperf.label(job: job.class.name) do
+      Rperf.profile(job: job.class.name) do
         block.call
       end
     end

data/lib/rperf/{middleware.rb → rack.rb}

@@ -1,6 +1,6 @@
 require "rperf"
 
-class Rperf::Middleware
+class Rperf::RackMiddleware
   def initialize(app, label_key: :endpoint)
     @app = app
     @label_key = label_key
@@ -8,7 +8,7 @@ class Rperf::Middleware
 
   def call(env)
     endpoint = "#{env["REQUEST_METHOD"]} #{env["PATH_INFO"]}"
-    Rperf.label(@label_key => endpoint) do
+    Rperf.profile(@label_key => endpoint) do
       @app.call(env)
     end
   end

data/lib/rperf/sidekiq.rb

@@ -2,7 +2,7 @@ require "rperf"
 
 class Rperf::SidekiqMiddleware
   def call(_worker, job, _queue)
-    Rperf.label(job: job["class"]) do
+    Rperf.profile(job: job["class"]) do
       yield
     end
   end

data/lib/rperf/version.rb

@@ -1,3 +1,3 @@
 module Rperf
-  VERSION = "0.6.0"
+  VERSION = "0.7.0"
 end

data/lib/rperf.rb

@@ -23,7 +23,7 @@ module Rperf
   #   .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, signal: nil, aggregate: true)
+  def self.start(frequency: 1000, mode: :cpu, output: nil, verbose: false, format: nil, stat: false, signal: nil, aggregate: true, defer: false)
     raise ArgumentError, "frequency must be a positive integer (got #{frequency.inspect})" unless frequency.is_a?(Integer) && frequency > 0
     raise ArgumentError, "frequency must be <= 10000 (10KHz), got #{frequency}" if frequency > 10_000
     raise ArgumentError, "mode must be :cpu or :wall, got #{mode.inspect}" unless %i[cpu wall].include?(mode)
@@ -44,7 +44,7 @@ module Rperf
     @stat_start_mono = Process.clock_gettime(Process::CLOCK_MONOTONIC) if @stat
     @label_set_table = nil
     @label_set_index = nil
-    _c_start(frequency, c_mode, aggregate, c_signal)
+    _c_start(frequency, c_mode, aggregate, c_signal, defer)
 
     if block_given?
       begin
@@ -148,6 +148,38 @@ module Rperf
     end
   end
 
+  # Profiles the given block: activates timer sampling for the duration
+  # and optionally applies labels. Use with start(defer: true) to profile
+  # only specific sections of code.
+  #
+  #   Rperf.start(defer: true, mode: :wall)
+  #   Rperf.profile(endpoint: "/users") { handle_request }
+  #   data = Rperf.stop
+  #
+  # Nesting is supported: timer stays active until the outermost profile exits.
+  # Requires a block. Raises if profiling is not started.
+  def self.profile(**kw, &block)
+    raise ArgumentError, "Rperf.profile requires a block" unless block
+    raise RuntimeError, "Rperf is not started" unless _c_running?
+
+    _init_label_sets unless @label_set_table
+
+    cur_id = _c_get_label
+    cur_labels = @label_set_table[cur_id] || {}
+    new_labels = cur_labels.merge(kw).reject { |_, v| v.nil? }
+    new_id = _intern_label_set(new_labels)
+    _c_set_label(new_id)
+
+    _c_profile_inc
+
+    begin
+      yield
+    ensure
+      _c_profile_dec
+      _c_set_label(cur_id)
+    end
+  end
+
   # Returns the current thread's labels as a Hash.
   # Returns an empty Hash if no labels are set or profiling is not running.
   def self.labels

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rperf
 version: !ruby/object:Gem::Version
-  version: 0.6.0
+  version: 0.7.0
 platform: ruby
 authors:
 - Koichi Sasada
@@ -53,7 +53,7 @@ files:
 - ext/rperf/rperf.c
 - lib/rperf.rb
 - lib/rperf/active_job.rb
-- lib/rperf/middleware.rb
+- lib/rperf/rack.rb
 - lib/rperf/sidekiq.rb
 - lib/rperf/version.rb
 homepage: https://github.com/ko1/rperf