rperf 0.6.0 → 0.8.0

data/ext/rperf/rperf.c

@@ -8,6 +8,7 @@
 #include <unistd.h>
 #include <signal.h>
 #include <stdatomic.h>
+#include <sched.h>
 #ifdef __linux__
 #include <sys/syscall.h>
 #endif
@@ -36,23 +37,19 @@
 #define RPERF_FRAME_TABLE_OLD_KEYS_INITIAL 16
 #define RPERF_AGG_TABLE_INITIAL 1024
 #define RPERF_STACK_POOL_INITIAL 4096
-
-/* Synthetic frame IDs (reserved in frame_table, 0-based) */
-#define RPERF_SYNTHETIC_GVL_BLOCKED 0
-#define RPERF_SYNTHETIC_GVL_WAIT    1
-#define RPERF_SYNTHETIC_GC_MARKING  2
-#define RPERF_SYNTHETIC_GC_SWEEPING 3
-#define RPERF_SYNTHETIC_COUNT       4
+#define RPERF_PAUSED(prof) ((prof)->profile_refcount == 0)
+
+/* VM state values (stored in samples, not as stack frames) */
+enum rperf_vm_state {
+    RPERF_VM_STATE_NORMAL       = 0,
+    RPERF_VM_STATE_GVL_BLOCKED  = 1,
+    RPERF_VM_STATE_GVL_WAIT     = 2,
+    RPERF_VM_STATE_GC_MARKING   = 3,
+    RPERF_VM_STATE_GC_SWEEPING  = 4,
+};
 
 /* ---- Data structures ---- */
 
-enum rperf_sample_type {
-    RPERF_SAMPLE_NORMAL      = 0,
-    RPERF_SAMPLE_GVL_BLOCKED = 1,  /* off-GVL: SUSPENDED → READY */
-    RPERF_SAMPLE_GVL_WAIT    = 2,  /* GVL wait: READY → RESUMED */
-    RPERF_SAMPLE_GC_MARKING  = 3,  /* GC marking phase */
-    RPERF_SAMPLE_GC_SWEEPING = 4,  /* GC sweeping phase */
-};
 
 enum rperf_gc_phase {
     RPERF_GC_NONE     = 0,
@@ -64,7 +61,7 @@ typedef struct rperf_sample {
     int depth;
     size_t frame_start; /* index into frame_pool */
     int64_t weight;
-    int type;           /* rperf_sample_type */
+    enum rperf_vm_state vm_state;
     int thread_seq;     /* thread sequence number (1-based) */
     int label_set_id;   /* label set ID (0 = no labels) */
 } rperf_sample_t;
@@ -86,7 +83,7 @@ typedef struct rperf_sample_buffer {
 
 typedef struct rperf_frame_table {
     _Atomic(VALUE *) keys;    /* unique VALUE array (GC mark target) */
-    size_t count;             /* = next frame_id (starts after RPERF_SYNTHETIC_COUNT) */
+    size_t count;             /* = next frame_id */
     size_t capacity;
     uint32_t *buckets;        /* open addressing: stores index into keys[] */
     size_t bucket_capacity;
@@ -102,9 +99,10 @@ typedef struct rperf_frame_table {
 
 typedef struct rperf_agg_entry {
     uint32_t frame_start;     /* offset into stack_pool */
-    int depth;                /* includes synthetic frame */
+    int depth;
     int thread_seq;
     int label_set_id;         /* label set ID (0 = no labels) */
+    enum rperf_vm_state vm_state;
     int64_t weight;           /* accumulated */
     uint32_t hash;            /* cached hash value */
     int used;                 /* 0 = empty, 1 = used */
@@ -144,6 +142,7 @@ typedef struct rperf_stats {
     size_t trigger_count;
     size_t sampling_count;
     int64_t sampling_total_ns;
+    size_t dropped_samples;     /* samples lost due to allocation failure */
 } rperf_stats_t;
 
 typedef struct rperf_profiler {
@@ -182,6 +181,12 @@ 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;
+    int worker_paused;  /* 1 when nanosleep worker is in paused cond_wait */
 } rperf_profiler_t;
 
 static rperf_profiler_t g_profiler;
@@ -215,8 +220,7 @@ rperf_profiler_mark(void *ptr)
         size_t ft_count = __atomic_load_n(&prof->frame_table.count, __ATOMIC_ACQUIRE);
         VALUE *ft_keys = atomic_load_explicit(&prof->frame_table.keys, memory_order_acquire);
         if (ft_keys && ft_count > 0) {
-            rb_gc_mark_locations(ft_keys + RPERF_SYNTHETIC_COUNT,
-                                ft_keys + ft_count);
+            rb_gc_mark_locations(ft_keys, ft_keys + ft_count);
         }
     }
 }
@@ -253,7 +257,7 @@ rperf_wall_time_ns(void)
 /* ---- Get current thread's time based on profiler mode ---- */
 
 static int64_t
-rperf_current_time_ns(rperf_profiler_t *prof, rperf_thread_data_t *td)
+rperf_current_time_ns(rperf_profiler_t *prof)
 {
     if (prof->mode == 0) {
         return rperf_cpu_time_ns();
@@ -296,6 +300,7 @@ static int
 rperf_ensure_sample_capacity(rperf_sample_buffer_t *buf)
 {
     if (buf->sample_count >= buf->sample_capacity) {
+        if (buf->sample_capacity > SIZE_MAX / 2) return -1;
         size_t new_cap = buf->sample_capacity * 2;
         rperf_sample_t *new_samples = (rperf_sample_t *)realloc(
             buf->samples,
@@ -314,6 +319,7 @@ static int
 rperf_ensure_frame_pool_capacity(rperf_sample_buffer_t *buf, int needed)
 {
     while (buf->frame_pool_count + (size_t)needed > buf->frame_pool_capacity) {
+        if (buf->frame_pool_capacity > SIZE_MAX / 2) return -1;
         size_t new_cap = buf->frame_pool_capacity * 2;
         VALUE *new_pool = (VALUE *)realloc(
             buf->frame_pool,
@@ -334,7 +340,7 @@ rperf_frame_table_init(rperf_frame_table_t *ft)
     VALUE *keys = (VALUE *)calloc(ft->capacity, sizeof(VALUE));
     if (!keys) return -1;
     atomic_store_explicit(&ft->keys, keys, memory_order_relaxed);
-    ft->count = RPERF_SYNTHETIC_COUNT; /* reserve slots for synthetic frames */
+    ft->count = 0;
     ft->bucket_capacity = RPERF_FRAME_TABLE_INITIAL * 2;
     ft->buckets = (uint32_t *)malloc(ft->bucket_capacity * sizeof(uint32_t));
     if (!ft->buckets) { free(keys); atomic_store_explicit(&ft->keys, NULL, memory_order_relaxed); return -1; }
@@ -366,6 +372,7 @@ rperf_frame_table_free(rperf_frame_table_t *ft)
 static void
 rperf_frame_table_rehash(rperf_frame_table_t *ft)
 {
+    if (ft->bucket_capacity > SIZE_MAX / 2) return;
     size_t new_cap = ft->bucket_capacity * 2;
     uint32_t *new_buckets = (uint32_t *)malloc(new_cap * sizeof(uint32_t));
     if (!new_buckets) return; /* keep using current buckets at higher load factor */
@@ -373,7 +380,7 @@ rperf_frame_table_rehash(rperf_frame_table_t *ft)
 
     VALUE *keys = atomic_load_explicit(&ft->keys, memory_order_relaxed);
     size_t i;
-    for (i = RPERF_SYNTHETIC_COUNT; i < ft->count; i++) {
+    for (i = 0; i < ft->count; i++) {
         uint32_t h = (uint32_t)(keys[i] >> 3); /* shift out tag bits */
         size_t idx = h % new_cap;
         while (new_buckets[idx] != RPERF_FRAME_TABLE_EMPTY)
@@ -394,11 +401,13 @@ rperf_frame_table_insert(rperf_frame_table_t *ft, VALUE fval)
     uint32_t h = (uint32_t)(fval >> 3);
     size_t idx = h % ft->bucket_capacity;
 
+    size_t probes = 0;
     while (1) {
         uint32_t slot = ft->buckets[idx];
         if (slot == RPERF_FRAME_TABLE_EMPTY) break;
         if (keys[slot] == fval) return slot;
         idx = (idx + 1) % ft->bucket_capacity;
+        if (++probes >= ft->bucket_capacity) return RPERF_FRAME_TABLE_EMPTY; /* table full */
     }
 
     /* Insert new entry.  Grow keys array if capacity is exhausted.
@@ -406,6 +415,7 @@ rperf_frame_table_insert(rperf_frame_table_t *ft, VALUE fval)
      * the old keys pointer.  Instead, allocate new, copy, swap pointer
      * atomically, and keep old array alive until stop. */
     if (ft->count >= ft->capacity) {
+        if (ft->capacity > SIZE_MAX / 2) return RPERF_FRAME_TABLE_EMPTY;
         size_t new_cap = ft->capacity * 2;
         VALUE *new_keys = (VALUE *)calloc(new_cap, sizeof(VALUE));
         if (!new_keys) return RPERF_FRAME_TABLE_EMPTY;
@@ -442,7 +452,7 @@ rperf_frame_table_insert(rperf_frame_table_t *ft, VALUE fval)
 /* ---- Aggregation table operations (all malloc-based, no GVL needed) ---- */
 
 static uint32_t
-rperf_fnv1a_u32(const uint32_t *data, int len, int thread_seq, int label_set_id)
+rperf_fnv1a_u32(const uint32_t *data, int len, int thread_seq, int label_set_id, enum rperf_vm_state vm_state)
 {
     uint32_t h = 2166136261u;
     int i;
@@ -454,6 +464,8 @@ rperf_fnv1a_u32(const uint32_t *data, int len, int thread_seq, int label_set_id)
     h *= 16777619u;
     h ^= (uint32_t)label_set_id;
     h *= 16777619u;
+    h ^= (uint32_t)vm_state;
+    h *= 16777619u;
     return h;
 }
 
@@ -482,6 +494,7 @@ rperf_agg_table_free(rperf_agg_table_t *at)
 static void
 rperf_agg_table_rehash(rperf_agg_table_t *at)
 {
+    if (at->bucket_capacity > SIZE_MAX / 2) return;
     size_t new_cap = at->bucket_capacity * 2;
     rperf_agg_entry_t *new_buckets = (rperf_agg_entry_t *)calloc(new_cap, sizeof(rperf_agg_entry_t));
     if (!new_buckets) return; /* keep using current buckets at higher load factor */
@@ -506,6 +519,7 @@ static int
 rperf_agg_ensure_stack_pool(rperf_agg_table_t *at, int needed)
 {
     while (at->stack_pool_count + (size_t)needed > at->stack_pool_capacity) {
+        if (at->stack_pool_capacity > SIZE_MAX / 2) return -1;
         size_t new_cap = at->stack_pool_capacity * 2;
         uint32_t *new_pool = (uint32_t *)realloc(at->stack_pool,
                                                   new_cap * sizeof(uint32_t));
@@ -520,15 +534,16 @@ rperf_agg_ensure_stack_pool(rperf_agg_table_t *at, int needed)
 static void
 rperf_agg_table_insert(rperf_agg_table_t *at, const uint32_t *frame_ids,
                        int depth, int thread_seq, int label_set_id,
-                       int64_t weight, uint32_t hash)
+                       enum rperf_vm_state vm_state, int64_t weight, uint32_t hash)
 {
     size_t idx = hash % at->bucket_capacity;
 
+    size_t probes = 0;
     while (1) {
         rperf_agg_entry_t *e = &at->buckets[idx];
         if (!e->used) break;
         if (e->hash == hash && e->depth == depth && e->thread_seq == thread_seq &&
-            e->label_set_id == label_set_id &&
+            e->label_set_id == label_set_id && e->vm_state == vm_state &&
             memcmp(at->stack_pool + e->frame_start, frame_ids,
                    depth * sizeof(uint32_t)) == 0) {
             /* Match — merge weight */
@@ -536,6 +551,7 @@ rperf_agg_table_insert(rperf_agg_table_t *at, const uint32_t *frame_ids,
             return;
         }
         idx = (idx + 1) % at->bucket_capacity;
+        if (++probes >= at->bucket_capacity) return; /* table full, drop sample */
     }
 
     /* New entry — append frame_ids to stack_pool */
@@ -546,6 +562,7 @@ rperf_agg_table_insert(rperf_agg_table_t *at, const uint32_t *frame_ids,
     e->depth = depth;
     e->thread_seq = thread_seq;
     e->label_set_id = label_set_id;
+    e->vm_state = vm_state;
     e->weight = weight;
     e->hash = hash;
     e->used = 1;
@@ -567,24 +584,16 @@ static void
 rperf_aggregate_buffer(rperf_profiler_t *prof, rperf_sample_buffer_t *buf)
 {
     size_t i;
-    uint32_t temp_ids[RPERF_MAX_STACK_DEPTH + 1];
+    uint32_t temp_ids[RPERF_MAX_STACK_DEPTH];
 
     for (i = 0; i < buf->sample_count; i++) {
         rperf_sample_t *s = &buf->samples[i];
-        int off = 0;
         uint32_t hash;
         int j;
 
-        /* Prepend synthetic frame if needed */
-        if (s->type == RPERF_SAMPLE_GVL_BLOCKED) {
-            temp_ids[off++] = RPERF_SYNTHETIC_GVL_BLOCKED;
-        } else if (s->type == RPERF_SAMPLE_GVL_WAIT) {
-            temp_ids[off++] = RPERF_SYNTHETIC_GVL_WAIT;
-        } else if (s->type == RPERF_SAMPLE_GC_MARKING) {
-            temp_ids[off++] = RPERF_SYNTHETIC_GC_MARKING;
-        } else if (s->type == RPERF_SAMPLE_GC_SWEEPING) {
-            temp_ids[off++] = RPERF_SYNTHETIC_GC_SWEEPING;
-        }
+        /* Clamp depth to temp_ids[] capacity */
+        if (s->depth > RPERF_MAX_STACK_DEPTH)
+            s->depth = RPERF_MAX_STACK_DEPTH;
 
         /* Convert VALUE frames to frame_ids */
         int overflow = 0;
@@ -592,15 +601,15 @@ rperf_aggregate_buffer(rperf_profiler_t *prof, rperf_sample_buffer_t *buf)
             VALUE fval = buf->frame_pool[s->frame_start + j];
             uint32_t fid = rperf_frame_table_insert(&prof->frame_table, fval);
             if (fid == RPERF_FRAME_TABLE_EMPTY) { overflow = 1; break; }
-            temp_ids[off + j] = fid;
+            temp_ids[j] = fid;
         }
         if (overflow) break; /* frame_table full, stop aggregating this buffer */
 
-        int total_depth = off + s->depth;
-        hash = rperf_fnv1a_u32(temp_ids, total_depth, s->thread_seq, s->label_set_id);
+        hash = rperf_fnv1a_u32(temp_ids, s->depth, s->thread_seq, s->label_set_id, s->vm_state);
 
-        rperf_agg_table_insert(&prof->agg_table, temp_ids, total_depth,
-                               s->thread_seq, s->label_set_id, s->weight, hash);
+        rperf_agg_table_insert(&prof->agg_table, temp_ids, s->depth,
+                               s->thread_seq, s->label_set_id, s->vm_state,
+                               s->weight, hash);
     }
 
     /* Reset buffer for reuse.
@@ -650,7 +659,7 @@ rperf_try_swap(rperf_profiler_t *prof)
 /* Write a sample into a specific buffer. No swap check. */
 static int
 rperf_write_sample(rperf_sample_buffer_t *buf, size_t frame_start, int depth,
-                   int64_t weight, int type, int thread_seq, int label_set_id)
+                   int64_t weight, enum rperf_vm_state vm_state, int thread_seq, int label_set_id)
 {
     if (weight <= 0) return 0;
     if (rperf_ensure_sample_capacity(buf) < 0) return -1;
@@ -659,7 +668,7 @@ rperf_write_sample(rperf_sample_buffer_t *buf, size_t frame_start, int depth,
     sample->depth = depth;
     sample->frame_start = frame_start;
     sample->weight = weight;
-    sample->type = type;
+    sample->vm_state = vm_state;
     sample->thread_seq = thread_seq;
     sample->label_set_id = label_set_id;
     buf->sample_count++;
@@ -668,10 +677,11 @@ rperf_write_sample(rperf_sample_buffer_t *buf, size_t frame_start, int depth,
 
 static void
 rperf_record_sample(rperf_profiler_t *prof, size_t frame_start, int depth,
-                    int64_t weight, int type, int thread_seq, int label_set_id)
+                    int64_t weight, enum rperf_vm_state vm_state, int thread_seq, int label_set_id)
 {
     rperf_sample_buffer_t *buf = &prof->buffers[atomic_load_explicit(&prof->active_idx, memory_order_relaxed)];
-    rperf_write_sample(buf, frame_start, depth, weight, type, thread_seq, label_set_id);
+    if (rperf_write_sample(buf, frame_start, depth, weight, vm_state, thread_seq, label_set_id) < 0)
+        prof->stats.dropped_samples++;
     rperf_try_swap(prof);
 }
 
@@ -683,7 +693,7 @@ rperf_thread_data_create(rperf_profiler_t *prof, VALUE thread)
 {
     rperf_thread_data_t *td = (rperf_thread_data_t *)calloc(1, sizeof(rperf_thread_data_t));
     if (!td) return NULL;
-    td->prev_time_ns = rperf_current_time_ns(prof, td);
+    td->prev_time_ns = rperf_current_time_ns(prof);
     td->prev_wall_ns = rperf_wall_time_ns();
     td->thread_seq = ++prof->next_thread_seq;
     rb_internal_thread_specific_set(thread, prof->ts_key, td);
@@ -706,7 +716,7 @@ rperf_handle_suspended(rperf_profiler_t *prof, VALUE thread, rperf_thread_data_t
         is_first = 1;
     }
 
-    int64_t time_now = rperf_current_time_ns(prof, td);
+    int64_t time_now = rperf_current_time_ns(prof);
     if (time_now < 0) return;
 
     /* Capture backtrace into active buffer's frame_pool */
@@ -718,10 +728,10 @@ 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);
+        rperf_record_sample(prof, frame_start, depth, weight, RPERF_VM_STATE_NORMAL, td->thread_seq, td->label_set_id);
     }
 
     /* Save timestamp for READY/RESUMED */
@@ -758,7 +768,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;
@@ -770,13 +780,15 @@ rperf_handle_resumed(rperf_profiler_t *prof, VALUE thread, rperf_thread_data_t *
         /* Write both samples into the same buf, then swap-check once */
         if (td->ready_at_ns > 0 && td->ready_at_ns > td->suspended_at_ns) {
             int64_t blocked_ns = td->ready_at_ns - td->suspended_at_ns;
-            rperf_write_sample(buf, frame_start, depth, blocked_ns,
-                               RPERF_SAMPLE_GVL_BLOCKED, td->thread_seq, td->label_set_id);
+            if (rperf_write_sample(buf, frame_start, depth, blocked_ns,
+                               RPERF_VM_STATE_GVL_BLOCKED, td->thread_seq, td->label_set_id) < 0)
+                prof->stats.dropped_samples++;
         }
         if (td->ready_at_ns > 0 && wall_now > td->ready_at_ns) {
             int64_t wait_ns = wall_now - td->ready_at_ns;
-            rperf_write_sample(buf, frame_start, depth, wait_ns,
-                               RPERF_SAMPLE_GVL_WAIT, td->thread_seq, td->label_set_id);
+            if (rperf_write_sample(buf, frame_start, depth, wait_ns,
+                               RPERF_VM_STATE_GVL_WAIT, td->thread_seq, td->label_set_id) < 0)
+                prof->stats.dropped_samples++;
         }
 
         rperf_try_swap(prof);
@@ -784,7 +796,7 @@ rperf_handle_resumed(rperf_profiler_t *prof, VALUE thread, rperf_thread_data_t *
 skip_gvl:
 
     /* Reset prev times to current — next timer sample measures from resume */
-    int64_t time_now = rperf_current_time_ns(prof, td);
+    int64_t time_now = rperf_current_time_ns(prof);
     if (time_now >= 0) td->prev_time_ns = time_now;
     td->prev_wall_ns = wall_now;
 
@@ -851,12 +863,13 @@ 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;
-        int type = (prof->gc.phase == RPERF_GC_SWEEPING)
-                   ? RPERF_SAMPLE_GC_SWEEPING
-                   : RPERF_SAMPLE_GC_MARKING;
+        enum rperf_vm_state vm_state = (prof->gc.phase == RPERF_GC_SWEEPING)
+                   ? RPERF_VM_STATE_GC_SWEEPING
+                   : RPERF_VM_STATE_GC_MARKING;
 
         /* Capture backtrace here (not at GC_ENTER) so that frame_start
          * always indexes into the current active buffer. The Ruby stack
@@ -875,7 +888,7 @@ rperf_gc_event_hook(rb_event_flag_t event, VALUE data, VALUE self, ID id, VALUE
         }
         buf->frame_pool_count += depth;
 
-        rperf_record_sample(prof, frame_start, depth, weight, type, prof->gc.thread_seq, prof->gc.label_set_id);
+        rperf_record_sample(prof, frame_start, depth, weight, vm_state, prof->gc.thread_seq, prof->gc.label_set_id);
         prof->gc.enter_ns = 0;
     }
 }
@@ -888,6 +901,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;
@@ -903,7 +917,7 @@ rperf_sample_job(void *arg)
         return; /* Skip first sample for this thread */
     }
 
-    int64_t time_now = rperf_current_time_ns(prof, td);
+    int64_t time_now = rperf_current_time_ns(prof);
     if (time_now < 0) return;
 
     int64_t weight = time_now - td->prev_time_ns;
@@ -922,7 +936,7 @@ rperf_sample_job(void *arg)
     if (depth <= 0) return;
     buf->frame_pool_count += depth;
 
-    rperf_record_sample(prof, frame_start, depth, weight, RPERF_SAMPLE_NORMAL, td->thread_seq, td->label_set_id);
+    rperf_record_sample(prof, frame_start, depth, weight, RPERF_VM_STATE_NORMAL, td->thread_seq, td->label_set_id);
 
     clock_gettime(CLOCK_THREAD_CPUTIME_ID, &ts_end);
     prof->stats.sampling_count++;
@@ -985,20 +999,34 @@ 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: mark as paused so disarm can confirm, then wait */
+            prof->worker_paused = 1;
+            CHECKED(pthread_cond_wait(&prof->worker_cond, &prof->worker_mutex));
+            prof->worker_paused = 0;
+            /* 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);
     }
@@ -1053,9 +1081,11 @@ rperf_build_aggregated_result(rperf_profiler_t *prof)
     rb_hash_aset(result, ID2SYM(rb_intern("trigger_count")), SIZET2NUM(prof->stats.trigger_count));
     rb_hash_aset(result, ID2SYM(rb_intern("sampling_count")), SIZET2NUM(prof->stats.sampling_count));
     rb_hash_aset(result, ID2SYM(rb_intern("sampling_time_ns")), LONG2NUM(prof->stats.sampling_total_ns));
+    if (prof->stats.dropped_samples > 0)
+        rb_hash_aset(result, ID2SYM(rb_intern("dropped_samples")), SIZET2NUM(prof->stats.dropped_samples));
     rb_hash_aset(result, ID2SYM(rb_intern("detected_thread_count")), INT2NUM(prof->next_thread_seq));
     rb_hash_aset(result, ID2SYM(rb_intern("unique_frames")),
-                 SIZET2NUM(prof->frame_table.count - RPERF_SYNTHETIC_COUNT));
+                 SIZET2NUM(prof->frame_table.count));
     rb_hash_aset(result, ID2SYM(rb_intern("unique_stacks")),
                  SIZET2NUM(prof->agg_table.count));
 
@@ -1074,11 +1104,7 @@ rperf_build_aggregated_result(rperf_profiler_t *prof)
     {
         rperf_frame_table_t *ft = &prof->frame_table;
         VALUE resolved_ary = rb_ary_new_capa((long)ft->count);
-        rb_ary_push(resolved_ary, rb_ary_new3(2, rb_str_new_lit("<GVL>"), rb_str_new_lit("[GVL blocked]")));
-        rb_ary_push(resolved_ary, rb_ary_new3(2, rb_str_new_lit("<GVL>"), rb_str_new_lit("[GVL wait]")));
-        rb_ary_push(resolved_ary, rb_ary_new3(2, rb_str_new_lit("<GC>"),  rb_str_new_lit("[GC marking]")));
-        rb_ary_push(resolved_ary, rb_ary_new3(2, rb_str_new_lit("<GC>"),  rb_str_new_lit("[GC sweeping]")));
-        for (i = RPERF_SYNTHETIC_COUNT; i < ft->count; i++) {
+        for (i = 0; i < ft->count; i++) {
             rb_ary_push(resolved_ary, rperf_resolve_frame(atomic_load_explicit(&ft->keys, memory_order_relaxed)[i]));
         }
 
@@ -1090,11 +1116,18 @@ rperf_build_aggregated_result(rperf_profiler_t *prof)
 
             VALUE frames = rb_ary_new_capa(e->depth);
             for (j = 0; j < e->depth; j++) {
+                if (e->frame_start + j >= at->stack_pool_count) break;
                 uint32_t fid = at->stack_pool[e->frame_start + j];
+                if (fid >= ft->count) break;
                 rb_ary_push(frames, RARRAY_AREF(resolved_ary, fid));
             }
 
-            VALUE sample = rb_ary_new3(4, frames, LONG2NUM(e->weight), INT2NUM(e->thread_seq), INT2NUM(e->label_set_id));
+            VALUE sample = rb_ary_new_capa(5);
+            rb_ary_push(sample, frames);
+            rb_ary_push(sample, LONG2NUM(e->weight));
+            rb_ary_push(sample, INT2NUM(e->thread_seq));
+            rb_ary_push(sample, INT2NUM(e->label_set_id));
+            rb_ary_push(sample, INT2NUM(e->vm_state));
             rb_ary_push(samples_ary, sample);
         }
     }
@@ -1110,14 +1143,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);
@@ -1138,6 +1172,7 @@ rb_rperf_start(VALUE self, VALUE vfreq, VALUE vmode, VALUE vagg, VALUE vsig)
     g_profiler.stats.sampling_count = 0;
     g_profiler.stats.sampling_total_ns = 0;
     g_profiler.stats.trigger_count = 0;
+    g_profiler.stats.dropped_samples = 0;
     atomic_store_explicit(&g_profiler.active_idx, 0, memory_order_relaxed);
     atomic_store_explicit(&g_profiler.swap_ready, 0, memory_order_relaxed);
     g_profiler.label_sets = Qnil;
@@ -1222,6 +1257,8 @@ 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;
+    g_profiler.worker_paused = 0;
 
 #if RPERF_USE_TIMER_SIGNAL
     g_profiler.timer_signal = timer_signal;
@@ -1269,7 +1306,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);
@@ -1320,9 +1362,7 @@ timer_fail:
 static VALUE
 rb_rperf_stop(VALUE self)
 {
-    VALUE result, samples_ary;
-    size_t i;
-    int j;
+    VALUE result;
 
     if (!g_profiler.running) {
         return Qnil;
@@ -1389,6 +1429,9 @@ rb_rperf_stop(VALUE self)
         rperf_agg_table_free(&g_profiler.agg_table);
     } else {
         /* Raw samples path (aggregate: false) */
+        VALUE samples_ary;
+        size_t i;
+        int j;
         rperf_sample_buffer_t *buf = &g_profiler.buffers[0];
 
         result = rb_hash_new();
@@ -1398,6 +1441,8 @@ rb_rperf_stop(VALUE self)
         rb_hash_aset(result, ID2SYM(rb_intern("trigger_count")), SIZET2NUM(g_profiler.stats.trigger_count));
         rb_hash_aset(result, ID2SYM(rb_intern("sampling_count")), SIZET2NUM(g_profiler.stats.sampling_count));
         rb_hash_aset(result, ID2SYM(rb_intern("sampling_time_ns")), LONG2NUM(g_profiler.stats.sampling_total_ns));
+        if (g_profiler.stats.dropped_samples > 0)
+            rb_hash_aset(result, ID2SYM(rb_intern("dropped_samples")), SIZET2NUM(g_profiler.stats.dropped_samples));
         rb_hash_aset(result, ID2SYM(rb_intern("detected_thread_count")), INT2NUM(g_profiler.next_thread_seq));
         {
             struct timespec stop_monotonic;
@@ -1414,29 +1459,20 @@ rb_rperf_stop(VALUE self)
         samples_ary = rb_ary_new_capa((long)buf->sample_count);
         for (i = 0; i < buf->sample_count; i++) {
             rperf_sample_t *s = &buf->samples[i];
-            VALUE frames = rb_ary_new_capa(s->depth + 1);
-
-            /* Prepend synthetic frame at leaf position (index 0) */
-            if (s->type == RPERF_SAMPLE_GVL_BLOCKED) {
-                VALUE syn = rb_ary_new3(2, rb_str_new_lit("<GVL>"), rb_str_new_lit("[GVL blocked]"));
-                rb_ary_push(frames, syn);
-            } else if (s->type == RPERF_SAMPLE_GVL_WAIT) {
-                VALUE syn = rb_ary_new3(2, rb_str_new_lit("<GVL>"), rb_str_new_lit("[GVL wait]"));
-                rb_ary_push(frames, syn);
-            } else if (s->type == RPERF_SAMPLE_GC_MARKING) {
-                VALUE syn = rb_ary_new3(2, rb_str_new_lit("<GC>"), rb_str_new_lit("[GC marking]"));
-                rb_ary_push(frames, syn);
-            } else if (s->type == RPERF_SAMPLE_GC_SWEEPING) {
-                VALUE syn = rb_ary_new3(2, rb_str_new_lit("<GC>"), rb_str_new_lit("[GC sweeping]"));
-                rb_ary_push(frames, syn);
-            }
+            VALUE frames = rb_ary_new_capa(s->depth);
 
             for (j = 0; j < s->depth; j++) {
+                if (s->frame_start + j >= buf->frame_pool_count) break;
                 VALUE fval = buf->frame_pool[s->frame_start + j];
                 rb_ary_push(frames, rperf_resolve_frame(fval));
             }
 
-            VALUE sample = rb_ary_new3(4, frames, LONG2NUM(s->weight), INT2NUM(s->thread_seq), INT2NUM(s->label_set_id));
+            VALUE sample = rb_ary_new_capa(5);
+            rb_ary_push(sample, frames);
+            rb_ary_push(sample, LONG2NUM(s->weight));
+            rb_ary_push(sample, INT2NUM(s->thread_seq));
+            rb_ary_push(sample, INT2NUM(s->label_set_id));
+            rb_ary_push(sample, INT2NUM(s->vm_state));
             rb_ary_push(samples_ary, sample);
         }
         rb_hash_aset(result, ID2SYM(rb_intern("raw_samples")), samples_ary);
@@ -1471,6 +1507,7 @@ rperf_clear_aggregated_data(rperf_profiler_t *prof)
     prof->stats.trigger_count = 0;
     prof->stats.sampling_count = 0;
     prof->stats.sampling_total_ns = 0;
+    prof->stats.dropped_samples = 0;
 
     /* Reset start timestamps so next snapshot's duration_ns covers
      * only the period since this clear. */
@@ -1558,6 +1595,103 @@ 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: wake the worker and wait until it enters paused state */
+    CHECKED(pthread_mutex_lock(&prof->worker_mutex));
+    while (!prof->worker_paused) {
+        CHECKED(pthread_cond_signal(&prof->worker_cond));
+        CHECKED(pthread_mutex_unlock(&prof->worker_mutex));
+        sched_yield();
+        CHECKED(pthread_mutex_lock(&prof->worker_mutex));
+    }
+    CHECKED(pthread_mutex_unlock(&prof->worker_mutex));
+}
+
+/* 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->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;
+    if (g_profiler.profile_refcount <= 0) 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
@@ -1568,6 +1702,14 @@ rperf_after_fork_child(void)
     /* Mark as not running — timer doesn't exist in child */
     g_profiler.running = 0;
 
+    /* Re-initialize mutex/condvar — they may have been locked by the parent's
+     * worker thread at fork time and are in an undefined state in the child.
+     * POSIX says only async-signal-safe functions should be called in atfork
+     * child handlers, but pthread_mutex_init is safe on Linux/glibc/musl and
+     * this is the standard pattern (e.g., Python, Go do the same). */
+    pthread_mutex_init(&g_profiler.worker_mutex, NULL);
+    pthread_cond_init(&g_profiler.worker_cond, NULL);
+
 #if RPERF_USE_TIMER_SIGNAL
     /* timer_create timers are not inherited across fork, but pending signals may be.
      * Block the signal, drain any pending instances, then restore old handler. */
@@ -1608,6 +1750,8 @@ rperf_after_fork_child(void)
     /* Reset stats */
     g_profiler.stats.sampling_count = 0;
     g_profiler.stats.sampling_total_ns = 0;
+    g_profiler.stats.dropped_samples = 0;
+    g_profiler.profile_refcount = 0;
     atomic_store_explicit(&g_profiler.swap_ready, 0, memory_order_relaxed);
 }
 
@@ -1617,13 +1761,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;