gvltools 0.2.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ed2a6e0154120c8b048e3b92db8e6f6c4a87d2b653b105b90a06a171ca61895b
-  data.tar.gz: a976aab0ebf0da04af47d53587c144b7e89eeeef8f078c5b115d037db0fe3f6b
+  metadata.gz: 5b6af92049391130d2248c5d14ec3c93e859f4ab92d6af9842e2a88c289b3e50
+  data.tar.gz: 4681a32780409d180b6727a791cdc122a9a03d21eba7f28f2070c8de6e52ddb1
 SHA512:
-  metadata.gz: baca86f153a68a90ca36213775bd22d5263325e98fdf3cd3332c4b3db953014c7c9a8e14c9ddee27ad0b19de5300065fd77d79d795d7ad8f931d45838f797921
-  data.tar.gz: be738a183964c4b6e0ef4f9ff5b9aac5e1a9b983d3fffe38034a338416260dc8be5fd95fcc23fe35697c2cc9d79ab8b1e8689deb3907e07468fe8e9985247911
+  metadata.gz: 005a90c02765c716c97f9165f777dd6b26b3853037e6c64f13e3255278db5a7c5d378855850758a7e391d9957389d18db7edb24a3658a46a5ec6105668238fa7
+  data.tar.gz: e16793a8f452f958cd0dde468c5aff337a78719485c8657bc9f5e1e91bd393b0bc1a523e56b5a1e06246c963e8661ed34707ef49e05cb15d6e94e57865c9932c

data/.rubocop.yml

@@ -22,6 +22,15 @@ Style/GlobalVars:
   Exclude:
     - ext/**/extconf.rb
 
+Style/EmptyMethod:
+  Enabled: false
+
+Style/IfUnlessModifier:
+  Enabled: false
+
+Style/GuardClause:
+  Enabled: false
+
 Style/Documentation:
   Enabled: false
 

data/CHANGELOG.md

@@ -1,5 +1,13 @@
 ## [Unreleased]
 
+- 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).
+- Disallow resetting the `WaitingThreads` counter when it is active (#7).
+
 ## [0.2.0] - 2023-03-28
 
 - Use C11 atomics instead of MRI's `rb_atomic_t`.

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,46 +1,51 @@
 PATH
   remote: .
   specs:
-    gvltools (0.2.0)
+    gvltools (0.4.0)
 
 GEM
   remote: https://rubygems.org/
   specs:
     ast (2.4.2)
-    minitest (5.15.0)
-    parallel (1.22.1)
-    parser (3.1.2.0)
+    json (2.7.1)
+    language_server-protocol (3.17.0.3)
+    minitest (5.21.2)
+    parallel (1.24.0)
+    parser (3.3.0.2)
       ast (~> 2.4.1)
+      racc
+    racc (1.7.3)
     rainbow (3.1.1)
     rake (13.0.6)
     rake-compiler (1.2.0)
       rake
-    regexp_parser (2.5.0)
-    rexml (3.2.5)
-    rubocop (1.30.1)
+    regexp_parser (2.9.0)
+    rexml (3.2.6)
+    rubocop (1.59.0)
+      json (~> 2.3)
+      language_server-protocol (>= 3.17.0)
       parallel (~> 1.10)
-      parser (>= 3.1.0.0)
+      parser (>= 3.2.2.4)
       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)
+      rubocop-ast (>= 1.30.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, < 3.0)
+    rubocop-ast (1.30.0)
+      parser (>= 3.2.1.0)
+    ruby-progressbar (1.13.0)
+    unicode-display_width (2.5.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)
 

data/README.md

@@ -59,6 +59,26 @@ class GVLInstrumentationMiddleware
 end
 ```
 
+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,44 @@ 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 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);
+        rb_thread_local_aset(thread, rb_intern("__gvltools_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 +62,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,7 +96,7 @@ 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
         );
     }
@@ -70,8 +116,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,68 +126,106 @@ 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_thread_local_aref(thread, rb_intern("__gvltools_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 VALUE waiting_threads_count(VALUE module) {
     return ULL2NUM(waiting_threads_total);
 }
 
 static VALUE waiting_threads_reset(VALUE module) {
+    waiting_threads_current_generation++;
     waiting_threads_total = 0;
     return Qtrue;
 }
 
 // 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)) {
+                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
+            thread_local_state *state = GT_EVENT_LOCAL_STATE(event_data, true);
+            if (!state->was_ready)  {
+                break; // In case we registered the hook while some threads were already waiting on the GVL
+            }
 
             if (ENABLED(WAITING_THREADS)) {
-                waiting_threads_total--;
+                if (state->waiting_threads_ready_generation == waiting_threads_current_generation) {
+                    waiting_threads_total--;
+                }
             }
 
             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)) {
@@ -156,6 +238,10 @@ 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();
+#endif
+
     VALUE rb_mGVLTools = rb_const_get(rb_cObject, rb_intern("GVLTools"));
 
     VALUE rb_mNative = rb_const_get(rb_mGVLTools, rb_intern("Native"));
@@ -167,11 +253,18 @@ 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);
+    rb_define_singleton_method(rb_mWaitingThreads, "_reset", waiting_threads_reset, 0);
     rb_define_singleton_method(rb_mWaitingThreads, "count", waiting_threads_count, 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.2.0"
+  VERSION = "0.4.0"
 end

data/lib/gvltools.rb

@@ -70,7 +70,7 @@ module GVLTools
     end
   end
 
-  module LocalTimer
+  class LocalTimer
     extend AbstractInstrumenter
 
     class << self
@@ -96,8 +96,27 @@ module GVLTools
       end
       alias_method :count, :count
 
+      def enable
+        unless enabled?
+          reset
+        end
+        super
+      end
+
+      def reset
+        if enabled?
+          raise Error, "can't reset WaitingThreads counter while it is active"
+        else
+          _reset
+        end
+      end
+
       private
 
+      def _reset
+      end
+      alias_method :_reset, :_reset # to be redefined from C.
+
       def metric
         WAITING_THREADS
       end

metadata

@@ -1,29 +1,15 @@
 --- !ruby/object:Gem::Specification
 name: gvltools
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Jean Boussier
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2023-03-28 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'
+date: 2024-01-19 00:00:00.000000000 Z
+dependencies: []
 description:
 email:
 - jean.boussier@gmail.com
@@ -67,7 +53,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.6
+rubygems_version: 3.5.3
 signing_key:
 specification_version: 4
 summary: Set of GVL instrumentation tools