gvltools 0.3.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5ffb320bec5fdc8a0d4940d8b370af1607a20383e1a9a8f939cc759588ca6627
-  data.tar.gz: 223bee0c124c17296b8386bbdda94406f91b84ad0adcf3acd09921424bb8eaf8
+  metadata.gz: 93f82e0950c9e2c02690e92984d20654d36dd91b3dffee80d0e85965a0bbc0b3
+  data.tar.gz: c6db2e33663b3c3fe290889eb91a71ac336d75a1005e90903b5c54e663446f70
 SHA512:
-  metadata.gz: 1c988c2e9d2c17925b178e4201f99530e75328cda648b3e3b50664e1d751ff5ad086139293a22dab5a54ae18e86bdd7d6e14064f4a4833eae18d3d948f134f20
-  data.tar.gz: 3b56ad91bf7784d0c61e4d321964eeaaae8ca97ec6c6c86c1934e8e95ad9d720b00933a7b0f7e91ec45e7ffd2a07665800c6f616250b7251318dc889a5ba94ca
+  metadata.gz: fcb609efc5575f85fd66fd57e223204a3206905b724940bf59dfc75e7421dab91faf0b9c7ed6e10083be728c17e5b083445ac59196fdfaa9ff629f4b05f53523
+  data.tar.gz: f71c390eaa0d6d72f8b06d58a70802f18ce7ec8347b84e42b4e5abcea5ec0c4a7bf598790080abd3b847e99537692caba4923651a2822d8cf1865a3588c5e962

data/.rubocop.yml

@@ -1,5 +1,4 @@
 AllCops:
-  TargetRubyVersion: 3.0
   NewCops: enable
   SuggestExtensions: false
 
@@ -25,6 +24,9 @@ Style/GlobalVars:
 Style/EmptyMethod:
   Enabled: false
 
+Naming/PredicateMethod:
+  Enabled: false
+
 Style/IfUnlessModifier:
   Enabled: false
 

data/.ruby-version

@@ -0,0 +1 @@
+3.3.0

data/CHANGELOG.md

@@ -1,5 +1,15 @@
 ## [Unreleased]
 
+## [0.5.0] - 2026-06-15
+
+- Fixed a `LocalTimer` deadlock with fiber schedulers by not allocating (and potentially triggering GC) during the `RESUMED` event (#34).
+- Store the `LocalTimer` counter in a thread instance variable instead of fiber-local storage, so it is shared across fibers of the same thread (#37).
+
+## [0.4.0] - 2024-01-19
+
+- Fixed compatibility with Ruby 3.3.0.
+- Added `GVLTools::LocalTimer.for(thread)` to access another thread counter (Ruby 3.3+ only).
+
 ## [0.3.0] - 2023-04-11
 
 - Automatically reset the `WaitingThreads` counter when enabling it (#7).

data/Gemfile

@@ -2,11 +2,10 @@
 
 source "https://rubygems.org"
 
-# Specify your gem's dependencies in gvltools.gemspec
 gemspec
 
-gem "rake", "~> 13.0"
+gem "rake"
+gem "rake-compiler"
 
 gem "minitest", "~> 5.0"
-
 gem "rubocop", "~> 1.21"

data/Gemfile.lock

@@ -1,48 +1,57 @@
 PATH
   remote: .
   specs:
-    gvltools (0.3.0)
+    gvltools (0.5.0)
 
 GEM
   remote: https://rubygems.org/
   specs:
-    ast (2.4.2)
-    minitest (5.15.0)
-    parallel (1.22.1)
-    parser (3.1.2.0)
+    ast (2.4.3)
+    json (2.19.8)
+    language_server-protocol (3.17.0.5)
+    lint_roller (1.1.0)
+    minitest (5.27.0)
+    parallel (2.1.0)
+    parser (3.3.11.1)
       ast (~> 2.4.1)
+      racc
+    prism (1.9.0)
+    racc (1.8.1)
     rainbow (3.1.1)
-    rake (13.0.6)
-    rake-compiler (1.2.0)
+    rake (13.4.2)
+    rake-compiler (1.3.1)
       rake
-    regexp_parser (2.5.0)
-    rexml (3.2.5)
-    rubocop (1.30.1)
-      parallel (~> 1.10)
-      parser (>= 3.1.0.0)
+    regexp_parser (2.12.0)
+    rubocop (1.87.0)
+      json (~> 2.3)
+      language_server-protocol (~> 3.17.0.2)
+      lint_roller (~> 1.1.0)
+      parallel (>= 1.10)
+      parser (>= 3.3.0.2)
       rainbow (>= 2.2.2, < 4.0)
-      regexp_parser (>= 1.8, < 3.0)
-      rexml (>= 3.2.5, < 4.0)
-      rubocop-ast (>= 1.18.0, < 2.0)
+      regexp_parser (>= 2.9.3, < 3.0)
+      rubocop-ast (>= 1.49.0, < 2.0)
       ruby-progressbar (~> 1.7)
-      unicode-display_width (>= 1.4.0, < 3.0)
-    rubocop-ast (1.18.0)
-      parser (>= 3.1.1.0)
-    ruby-progressbar (1.11.0)
-    unicode-display_width (2.1.0)
+      unicode-display_width (>= 2.4.0, < 4.0)
+    rubocop-ast (1.49.1)
+      parser (>= 3.3.7.2)
+      prism (~> 1.7)
+    ruby-progressbar (1.13.0)
+    unicode-display_width (3.2.0)
+      unicode-emoji (~> 4.1)
+    unicode-emoji (4.2.0)
 
 PLATFORMS
   aarch64-linux
-  arm64-darwin-21
-  arm64-darwin-22
+  arm64-darwin
   x86_64-linux
 
 DEPENDENCIES
   gvltools!
   minitest (~> 5.0)
-  rake (~> 13.0)
+  rake
   rake-compiler
   rubocop (~> 1.21)
 
 BUNDLED WITH
-   2.3.14
+   2.5.3

data/README.md

@@ -44,6 +44,8 @@ It is particularly useful to detect wether an application use too many threads,
 For instance as a Rack middleware:
 
 ```ruby
+# lib/gvl_instrumentation_middleware.rb
+
 class GVLInstrumentationMiddleware
   def initialize(app)
     @app = app
@@ -59,6 +61,35 @@ class GVLInstrumentationMiddleware
 end
 ```
 
+```ruby
+# config/initializers/gvl_instrumentation.rb
+
+GVLTools::LocalTimer.enable
+
+require "gvl_instrumentation_middleware"
+config.middleware.use GVLInstrumentationMiddleware
+```
+
+Starting from Ruby 3.3, a thread local timer can be accessed from another thread:
+
+```ruby
+def fibonacci(n)
+  if n < 2
+    n
+  else
+    fibonacci(n - 1) + fibonacci(n - 2)
+  end
+end
+
+GVLTools::LocalTimer.enable
+thread = Thread.new do
+  fibonacci(20)
+end
+thread.join(1)
+local_timer = GVLTools::LocalTimer.for(thread)
+local_timer.monotonic_time # => 127000
+```
+
 ### GlobalTimer
 
 `GlobalTimer` records the overall time spent waiting on the GVL by all threads combined.

data/ext/gvltools/extconf.rb

@@ -3,9 +3,10 @@
 require "mkmf"
 if RUBY_ENGINE == "ruby" &&
    have_header("stdatomic.h") &&
-   have_func("rb_internal_thread_add_event_hook", ["ruby/thread.h"])
+   have_func("rb_internal_thread_add_event_hook", ["ruby/thread.h"]) # 3.1+
 
   $CFLAGS << " -O3 -Wall "
+  have_func("rb_internal_thread_specific_get", "ruby/thread.h") # 3.3+
   create_makefile("gvltools/instrumentation")
 else
   File.write("Makefile", dummy_makefile($srcdir).join)

data/ext/gvltools/instrumentation.c

@@ -5,6 +5,8 @@
 
 typedef unsigned long long counter_t;
 
+VALUE rb_cLocalTimer = Qnil;
+
 // Metrics
 static rb_internal_thread_event_hook_t *gt_hook = NULL;
 
@@ -15,6 +17,46 @@ static unsigned int enabled_mask = 0;
 
 #define ENABLED(metric) (enabled_mask & (metric))
 
+typedef struct {
+    bool was_ready;
+    _Atomic counter_t timer_total;
+    _Atomic counter_t waiting_threads_ready_generation;
+    struct timespec timer_ready_at;
+} thread_local_state;
+
+#ifdef HAVE_RB_INTERNAL_THREAD_SPECIFIC_GET // 3.3+
+static int thread_storage_key = 0;
+static ID id_local_state;
+
+static size_t thread_local_state_memsize(const void *data) {
+    return sizeof(thread_local_state);
+}
+
+static const rb_data_type_t thread_local_state_type = {
+    .wrap_struct_name = "GVLTools::ThreadLocal",
+    .function = {
+        .dmark = NULL,
+        .dfree = RUBY_DEFAULT_FREE,
+        .dsize = thread_local_state_memsize,
+    },
+    .flags = RUBY_TYPED_FREE_IMMEDIATELY | RUBY_TYPED_WB_PROTECTED,
+};
+
+static inline thread_local_state *GT_LOCAL_STATE(VALUE thread, bool allocate) {
+    thread_local_state *state = rb_internal_thread_specific_get(thread, thread_storage_key);
+    if (!state && allocate) {
+        VALUE wrapper = TypedData_Make_Struct(rb_cLocalTimer, thread_local_state, &thread_local_state_type, state);
+        // Anchor to the thread object, not fiber-local storage, so it outlives the allocating fiber.
+        rb_ivar_set(thread, id_local_state, wrapper);
+        RB_GC_GUARD(wrapper);
+        rb_internal_thread_specific_set(thread, thread_storage_key, state);
+    }
+    return state;
+}
+
+#define GT_EVENT_LOCAL_STATE(event_data, allocate) GT_LOCAL_STATE(event_data->thread, allocate)
+#define GT_CURRENT_THREAD_LOCAL_STATE() GT_LOCAL_STATE(rb_thread_current(), true)
+#else
 #if __STDC_VERSION__ >= 201112
   #define THREAD_LOCAL_SPECIFIER _Thread_local
 #elif defined(__GNUC__) && !defined(RB_THREAD_LOCAL_SPECIFIER_IS_UNSUPPORTED)
@@ -22,11 +64,17 @@ static unsigned int enabled_mask = 0;
   #define THREAD_LOCAL_SPECIFIER __thread
 #endif
 
+static THREAD_LOCAL_SPECIFIER thread_local_state __thread_local_state = {0};
+#undef THREAD_LOCAL_SPECIFIER
+
+#define GT_LOCAL_STATE(thread) (&__thread_local_state)
+#define GT_EVENT_LOCAL_STATE(event_data, allocate) (&__thread_local_state)
+#define GT_CURRENT_THREAD_LOCAL_STATE() (&__thread_local_state)
+#endif
+
 // Common
 #define SECONDS_TO_NANOSECONDS (1000 * 1000 * 1000)
 
-static THREAD_LOCAL_SPECIFIER bool was_ready = 0;
-
 static inline void gt_gettime(struct timespec *time) {
     if (clock_gettime(CLOCK_MONOTONIC, time) == -1) {
         rb_sys_fail("clock_gettime");
@@ -50,9 +98,23 @@ static VALUE gt_enable_metric(VALUE module, VALUE metric) {
     if (!gt_hook) {
         gt_hook = rb_internal_thread_add_event_hook(
             gt_thread_callback,
-            RUBY_INTERNAL_THREAD_EVENT_EXITED | RUBY_INTERNAL_THREAD_EVENT_READY | RUBY_INTERNAL_THREAD_EVENT_RESUMED,
+            RUBY_INTERNAL_THREAD_EVENT_STARTED | RUBY_INTERNAL_THREAD_EVENT_EXITED | RUBY_INTERNAL_THREAD_EVENT_READY | RUBY_INTERNAL_THREAD_EVENT_RESUMED,
             NULL
         );
+
+#ifdef HAVE_RB_INTERNAL_THREAD_SPECIFIC_GET
+        // Eagerly allocate the per-thread state for every thread that already
+        // exists at enable time. Threads created later get their state allocated from the
+        // STARTED event (also GVL-held). This guarantees the RESUMED event always finds an
+        // existing state and never has to allocate. Allocating from RESUMED is
+        // illegal because it doesn't necessarily run with the GVL.
+        VALUE threads = rb_funcall(rb_const_get(rb_cObject, rb_intern("Thread")), rb_intern("list"), 0);
+        long count = RARRAY_LEN(threads);
+        for (long i = 0; i < count; i++) {
+            GT_LOCAL_STATE(RARRAY_AREF(threads, i), true);
+        }
+        RB_GC_GUARD(threads);
+#endif
     }
     return Qtrue;
 }
@@ -70,8 +132,6 @@ static VALUE gt_disable_metric(VALUE module, VALUE metric) {
 
 // GVLTools::LocalTimer and GVLTools::GlobalTimer
 static _Atomic counter_t global_timer_total = 0;
-static THREAD_LOCAL_SPECIFIER counter_t local_timer_total = 0;
-static THREAD_LOCAL_SPECIFIER struct timespec timer_ready_at = {0};
 
 static VALUE global_timer_monotonic_time(VALUE module) {
     return ULL2NUM(global_timer_total);
@@ -82,19 +142,38 @@ static VALUE global_timer_reset(VALUE module) {
     return Qtrue;
 }
 
-static VALUE local_timer_monotonic_time(VALUE module) {
-    return ULL2NUM(local_timer_total);
+static VALUE local_timer_m_monotonic_time(VALUE module) {
+    return ULL2NUM(GT_CURRENT_THREAD_LOCAL_STATE()->timer_total);
+}
+
+static VALUE local_timer_m_reset(VALUE module) {
+    GT_CURRENT_THREAD_LOCAL_STATE()->timer_total = 0;
+    return Qtrue;
+}
+
+#ifdef HAVE_RB_INTERNAL_THREAD_SPECIFIC_GET
+static VALUE local_timer_for(VALUE module, VALUE thread) {
+    GT_LOCAL_STATE(thread, true);
+    return rb_ivar_get(thread, id_local_state);
+}
+
+static VALUE local_timer_monotonic_time(VALUE timer) {
+    thread_local_state *state;
+    TypedData_Get_Struct(timer, thread_local_state, &thread_local_state_type, state);
+    return ULL2NUM(state->timer_total);
 }
 
-static VALUE local_timer_reset(VALUE module) {
-    local_timer_total = 0;
+static VALUE local_timer_reset(VALUE timer) {
+    thread_local_state *state;
+    TypedData_Get_Struct(timer, thread_local_state, &thread_local_state_type, state);
+    state->timer_total = 0;
     return Qtrue;
 }
+#endif
 
 // Thread counts
 static _Atomic counter_t waiting_threads_total = 0;
 static _Atomic counter_t waiting_threads_current_generation = 1;
-static THREAD_LOCAL_SPECIFIER counter_t waiting_threads_ready_generation = 0;
 
 static VALUE waiting_threads_count(VALUE module) {
     return ULL2NUM(waiting_threads_total);
@@ -107,38 +186,51 @@ static VALUE waiting_threads_reset(VALUE module) {
 }
 
 // General callback
-static void gt_reset_thread_local_state(void) {
-    // MRI can re-use native threads, so we need to reset thread local state,
-    // otherwise it will leak from one Ruby thread from another.
-    was_ready = false;
-    local_timer_total = 0;
-}
-
 static void gt_thread_callback(rb_event_flag_t event, const rb_internal_thread_event_data_t *event_data, void *user_data) {
     switch(event) {
-        case RUBY_INTERNAL_THREAD_EVENT_STARTED:
+        case RUBY_INTERNAL_THREAD_EVENT_STARTED: {
+            // The STARTED event is triggered from the parent thread with the GVL held
+            // so we can allocate the struct.
+            GT_EVENT_LOCAL_STATE(event_data, true);
+        }
+        break;
         case RUBY_INTERNAL_THREAD_EVENT_EXITED: {
-            gt_reset_thread_local_state();
+#ifndef HAVE_RB_INTERNAL_THREAD_SPECIFIC_GET
+            thread_local_state *state = GT_EVENT_LOCAL_STATE(event_data, false);
+            if (state) {
+                // MRI can re-use native threads, so we need to reset thread local state,
+                // otherwise it will leak from one Ruby thread from another.
+                state->was_ready = false;
+                state->timer_total = 0;
+            }
+#endif
         }
         break;
         case RUBY_INTERNAL_THREAD_EVENT_READY: {
-            if (!was_ready) was_ready = true;
+            thread_local_state *state = GT_EVENT_LOCAL_STATE(event_data, false);
+            if (!state) {
+                break;
+            }
+            state->was_ready = true;
 
             if (ENABLED(WAITING_THREADS)) {
-                waiting_threads_ready_generation = waiting_threads_current_generation;
+                state->waiting_threads_ready_generation = waiting_threads_current_generation;
                 waiting_threads_total++;
             }
 
             if (ENABLED(TIMER_GLOBAL | TIMER_LOCAL)) {
-                gt_gettime(&timer_ready_at);
+                gt_gettime(&state->timer_ready_at);
             }
         }
         break;
-        case RUBY_INTERNAL_THREAD_EVENT_RESUMED: {
-            if (!was_ready) break; // In case we registered the hook while some threads were already waiting on the GVL
+        case RUBY_INTERNAL_THREAD_EVENT_RESUMED: { // Must not allocate
+            thread_local_state *state = GT_EVENT_LOCAL_STATE(event_data, false);
+            if (!state || !state->was_ready)  {
+                break; // In case we registered the hook while some threads were already waiting on the GVL
+            }
 
             if (ENABLED(WAITING_THREADS)) {
-                if (waiting_threads_ready_generation == waiting_threads_current_generation) {
+                if (state->waiting_threads_ready_generation == waiting_threads_current_generation) {
                     waiting_threads_total--;
                 }
             }
@@ -146,10 +238,10 @@ static void gt_thread_callback(rb_event_flag_t event, const rb_internal_thread_e
             if (ENABLED(TIMER_GLOBAL | TIMER_LOCAL)) {
                 struct timespec current_time;
                 gt_gettime(&current_time);
-                counter_t diff = gt_time_diff_ns(timer_ready_at, current_time);
+                counter_t diff = gt_time_diff_ns(state->timer_ready_at, current_time);
 
                 if (ENABLED(TIMER_LOCAL)) {
-                    local_timer_total += diff;
+                    state->timer_total += diff;
                 }
 
                 if (ENABLED(TIMER_GLOBAL)) {
@@ -162,6 +254,11 @@ static void gt_thread_callback(rb_event_flag_t event, const rb_internal_thread_e
 }
 
 void Init_instrumentation(void) {
+#ifdef HAVE_RB_INTERNAL_THREAD_SPECIFIC_GET // 3.3+
+    thread_storage_key = rb_internal_thread_specific_key_create();
+    id_local_state = rb_intern("__gvltools_local_state");
+#endif
+
     VALUE rb_mGVLTools = rb_const_get(rb_cObject, rb_intern("GVLTools"));
 
     VALUE rb_mNative = rb_const_get(rb_mGVLTools, rb_intern("Native"));
@@ -173,9 +270,16 @@ void Init_instrumentation(void) {
     rb_define_singleton_method(rb_mGlobalTimer, "reset", global_timer_reset, 0);
     rb_define_singleton_method(rb_mGlobalTimer, "monotonic_time", global_timer_monotonic_time, 0);
 
-    VALUE rb_mLocalTimer = rb_const_get(rb_mGVLTools, rb_intern("LocalTimer"));
-    rb_define_singleton_method(rb_mLocalTimer, "reset", local_timer_reset, 0);
-    rb_define_singleton_method(rb_mLocalTimer, "monotonic_time", local_timer_monotonic_time, 0);
+    rb_global_variable(&rb_cLocalTimer);
+    rb_cLocalTimer = rb_const_get(rb_mGVLTools, rb_intern("LocalTimer"));
+    rb_undef_alloc_func(rb_cLocalTimer);
+    rb_define_singleton_method(rb_cLocalTimer, "reset", local_timer_m_reset, 0);
+    rb_define_singleton_method(rb_cLocalTimer, "monotonic_time", local_timer_m_monotonic_time, 0);
+#ifdef HAVE_RB_INTERNAL_THREAD_SPECIFIC_GET
+    rb_define_singleton_method(rb_cLocalTimer, "for", local_timer_for, 1);
+    rb_define_method(rb_cLocalTimer, "reset", local_timer_reset, 0);
+    rb_define_method(rb_cLocalTimer, "monotonic_time", local_timer_monotonic_time, 0);
+#endif
 
     VALUE rb_mWaitingThreads = rb_const_get(rb_mGVLTools, rb_intern("WaitingThreads"));
     rb_define_singleton_method(rb_mWaitingThreads, "_reset", waiting_threads_reset, 0);

data/gvltools.gemspec

@@ -30,6 +30,4 @@ Gem::Specification.new do |spec|
   spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
   spec.require_paths = ["lib"]
   spec.extensions = ["ext/gvltools/extconf.rb"]
-
-  spec.add_development_dependency "rake-compiler"
 end

data/lib/gvltools/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module GVLTools
-  VERSION = "0.3.0"
+  VERSION = "0.5.0"
 end

data/lib/gvltools.rb

@@ -70,7 +70,7 @@ module GVLTools
     end
   end
 
-  module LocalTimer
+  class LocalTimer
     extend AbstractInstrumenter
 
     class << self

metadata

@@ -1,30 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: gvltools
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Jean Boussier
-autorequire:
 bindir: exe
 cert_chain: []
-date: 2023-04-11 00:00:00.000000000 Z
-dependencies:
-- !ruby/object:Gem::Dependency
-  name: rake-compiler
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-description:
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
 email:
 - jean.boussier@gmail.com
 executables: []
@@ -33,6 +17,7 @@ extensions:
 extra_rdoc_files: []
 files:
 - ".rubocop.yml"
+- ".ruby-version"
 - CHANGELOG.md
 - Gemfile
 - Gemfile.lock
@@ -52,7 +37,6 @@ metadata:
   homepage_uri: https://github.com/Shopify/gvltools
   source_code_uri: https://github.com/Shopify/gvltools
   changelog_uri: https://github.com/Shopify/gvltools/blob/master/CHANGELOG.md
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -67,8 +51,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.10
-signing_key:
+rubygems_version: 4.0.10
 specification_version: 4
 summary: Set of GVL instrumentation tools
 test_files: []