duel-gvl 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 262cd836d526942fc68b7994b37318ba4b4677b7a8b8b6cf562507171bdb6605
+  data.tar.gz: 15fbe625b54e163cf6778191fc8c7e7a177be3bbfc8017ad86cd1496adc71907
+SHA512:
+  metadata.gz: d4198de77958ccc952464529998760db5ccb0e20622cd50e65ad951ef0416d1a166ded66f157d2b3f28b113bbe84cba5933a8428e38b5fccfbd9a4f78d911b30
+  data.tar.gz: 3777cd966a104dcba2b23a8f288fd38d02ce16c99d06e3f4c4462060ddbe02b7a74f541482da4894033022d06dfd4bdd148c7ff532dc67a845b6375911792c85

data/CHANGELOG.md

@@ -0,0 +1,29 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/2.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-10-24
+
+The first release. duel-gvl is a Duel plugin, open source under the MIT
+license. It needs Duel 0.1 and CRuby 3.4 or later, where it builds a
+small C extension (elsewhere it installs without it, and measures
+nothing).
+
+### Added
+
+- `c.use :gvl`: the `gvl_wait` metric, how long threads waited
+  for the GVL in each sample of a benchmark with threads of its own, from
+  Ruby's thread event hooks, in a C extension (CRuby), loaded in Duel's
+  workers. It's judged on samples that wait a tenth of their CPU time or
+  more on either version (`cpu_floor: 0.1`), against a limit of 1.5, and
+  not across the board (`across: false`). It's in nanoseconds
+  (`unit: "ns"`), so reports show it as time (`51.16µs → 817.9µs an
+  iteration`).
+
+[Unreleased]: https://github.com/sferik/duel-ruby/compare/duel-gvl-v0.1.0...HEAD
+[0.1.0]: https://github.com/sferik/duel-ruby/releases/tag/duel-gvl-v0.1.0

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Erik Berlin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,108 @@
+# duel-gvl
+
+[![Duel](https://raw.githubusercontent.com/sferik/duel-ruby/main/assets/badge.svg)](https://github.com/sferik/duel-ruby)
+[![duel-gvl](https://github.com/sferik/duel-ruby/actions/workflows/plugin-gvl.yml/badge.svg)](https://github.com/sferik/duel-ruby/actions/workflows/plugin-gvl.yml)
+[![Gem Version](https://badge.fury.io/rb/duel-gvl.svg)](https://rubygems.org/gems/duel-gvl)
+
+A [Duel](https://github.com/sferik/duel-ruby) plugin for code that runs
+threads: every benchmark with threads of its own is judged on how long
+they waited for the GVL too.
+
+| Metric | What it is | A regression |
+|---|---|---|
+| `gvl_wait` | the time all threads spent waiting for the GVL, in ns | > 50% more, 99% confident (where it's a tenth of the sample's CPU time or more, on either version) |
+
+A thread waiting for the GVL uses no CPU, so contention a change adds
+doesn't show in CPU time: holding the GVL longer around I/O, a C call
+that stops releasing it, more threads fighting over it. It shows here,
+for two threads whose C call stopped releasing the GVL:
+
+```
+! wait                                              18.4s n=150    gvl_wait 34.093 [25.666, 41.575] slower  cpu 1.023 [0.959, 1.238] same
+```
+
+And under the regression, how long they waited an iteration on each
+version (here, in another run):
+
+```
+REGRESSION wait: worse gvl_wait in every measurement
+  gvl_wait: 51.16µs → 817.9µs an iteration (16.47x)
+```
+
+## Installation
+
+```ruby
+# Gemfile
+group :development do
+  gem "duel-gvl"
+end
+```
+
+> [!NOTE]
+> It needs CRuby (3.4 or later), and builds a small C extension when it's
+> installed. Elsewhere (JRuby and TruffleRuby, which have no GVL, Windows,
+> or no C compiler) it installs without it, and there's no `gvl_wait`.
+
+## Usage
+
+```ruby
+# .duel.rb
+Duel.configure { |c| c.use :gvl }
+```
+
+It measures only benchmarks marked `only: :timing`, as benchmarks with
+threads of their own should be (their counts vary from run to run). The
+rest have one thread and nothing to wait for:
+
+```ruby
+# duel/pool_duel.rb
+duel "pool: 4 threads", only: :timing do |n|
+  jobs = Thread::Queue.new(Array.new(n) { |i| i }).tap(&:close)
+  Array.new(4) { Thread.new { while (job = jobs.pop) do MyPool.handle(job) end } }.each(&:join)
+end
+```
+
+The threads are best started and joined in the benchmark, as here: one
+that outlives a sample may be waiting in the next one.
+
+## How it measures
+
+Ruby tells the extension when a thread starts waiting for the GVL and
+when it gets it (its thread event hooks), and it adds up the waits. The
+hook is added only for a sample of a benchmark it measures, and removed
+after it. Then each time a thread takes the GVL costs two clock readings
+more: some 40-70 ns on macOS (5-8% of a loop of one-byte pipe reads and
+writes), more where reading the clock is slow (some virtual machines),
+nothing in code that doesn't release the GVL, and alike on both
+versions.
+
+How long threads wait depends on when the operating system runs them,
+so on what else the machine is doing: on a busy one, the same code's
+samples can wait half or twice as long. What contention a change adds
+makes them wait many times as long, so `gvl_wait` is slower only past
+half as much again (limit 1.5). And it isn't judged across the board
+(`across: false`), where Duel looks for a slowdown too small for any
+one benchmark in all of them together, with a quarter of the margin: an
+eighth more is well within what the machine alone does to it.
+
+Threads that hardly wait for each other still wait a little now and
+then, as the scheduler has it (starting and ending a thread are
+handoffs too): some 0.3-2.5% of their CPU time, on a busy machine
+too. Threads that fight for it wait about as long as they run, or
+longer: a thread that wants the GVL waits until the one holding it lets
+go, or its time slice runs out. (Threads that mostly wait on I/O, and
+only now and then want the GVL at once, wait anything from a twentieth
+as long as they run to more than that, as the machine is busy.) So a
+benchmark is judged on `gvl_wait` only when its samples wait a tenth of
+their CPU time or more on either version (`cpu_floor: 0.1`): code that hardly waits on
+both isn't judged on the noise, and code that starts waiting where it
+hardly did is (its ratio is many times over). It's a share and not a
+time since samples are as long as their CPU time needs to settle (some
+10 ms, or more). `gvl_wait` doesn't size samples: CPU time does.
+
+Duel's `c.measure` changes its settings, or leaves it out:
+
+```ruby
+c.measure("gvl_wait", cpu_floor: 0.5, limit: 2.0) # judged from half the CPU time, slower past twice as long
+c.measure("gvl_wait", skip: true)
+```

data/ext/duel_gvl/duel_gvl.c

@@ -0,0 +1,108 @@
+/*
+ * Duel::GVL::Hook: the total time Ruby threads have spent waiting for
+ * the GVL while it's measuring.
+ *
+ * Ruby calls gvl_event when a thread starts waiting for the GVL (READY,
+ * without the GVL) and when it gets it (RESUMED, with it), possibly from
+ * several native threads at once, and not necessarily on the native
+ * thread that runs the Ruby thread: a thread woken by another (a new
+ * one, or one joining a thread that ends) is READY on the waker's, and
+ * with M:N threads any may be. So the start of a wait is kept with the
+ * Ruby thread, in a slot of the thread-specific storage Ruby keeps for
+ * tools like this one (in a native thread's variable, a joining thread's
+ * wait would be counted from a READY long before), and each wait is
+ * added to one total atomically.
+ *
+ * The hook is added by start and removed by stop: between them, each
+ * time a thread takes the GVL costs two clock readings and Ruby's
+ * calling the hook (some 25 ns): 40-70 ns on macOS, more where reading
+ * the clock is slow (some virtual machines); outside them, nothing.
+ */
+#include <ruby.h>
+#include <ruby/thread.h>
+#include <stdint.h>
+#include <time.h>
+
+static rb_internal_thread_specific_key_t ready_key;
+static rb_internal_thread_event_hook_t *hook;
+static uint64_t waited_ns;
+static uint64_t started_at;
+
+/*
+ * Monotonic nanoseconds, as cheaply as the platform has them: each
+ * handoff of the GVL reads the clock twice (macOS's CLOCK_UPTIME_RAW
+ * skips the conversion its CLOCK_MONOTONIC makes, a third of the hook's
+ * cost there).
+ */
+static uint64_t monotonic_ns(void) {
+#ifdef __APPLE__
+    return clock_gettime_nsec_np(CLOCK_UPTIME_RAW);
+#else
+    struct timespec now;
+    clock_gettime(CLOCK_MONOTONIC, &now);
+    return ((uint64_t)now.tv_sec * 1000000000U) + (uint64_t)now.tv_nsec;
+#endif
+}
+
+static void gvl_event(rb_event_flag_t event, const rb_internal_thread_event_data_t *data, void *user_data) {
+    (void)user_data;
+    if (event == RUBY_INTERNAL_THREAD_EVENT_READY) {
+        rb_internal_thread_specific_set(data->thread, ready_key, (void *)(uintptr_t)monotonic_ns());
+        return;
+    }
+    uint64_t ready_at = (uint64_t)(uintptr_t)rb_internal_thread_specific_get(data->thread, ready_key);
+    /*
+     * A thread that was waiting already when measuring started has no
+     * start in this stretch: its stamp is older (or from an earlier
+     * stretch, its wait's end unseen), and its wait isn't counted.
+     */
+    if (ready_at >= __atomic_load_n(&started_at, __ATOMIC_RELAXED)) {
+        __atomic_fetch_add(&waited_ns, monotonic_ns() - ready_at, __ATOMIC_RELAXED);
+    }
+    rb_internal_thread_specific_set(data->thread, ready_key, NULL);
+}
+
+/* Starts measuring (again); does nothing while measuring. */
+static VALUE native_start(VALUE self) {
+    (void)self;
+    if (hook == NULL) {
+        __atomic_store_n(&started_at, monotonic_ns(), __ATOMIC_RELAXED);
+        hook = rb_internal_thread_add_event_hook(
+            gvl_event, RUBY_INTERNAL_THREAD_EVENT_READY | RUBY_INTERNAL_THREAD_EVENT_RESUMED, NULL);
+    }
+    return Qnil;
+}
+
+/* Stops measuring; the total stays. */
+static VALUE native_stop(VALUE self) {
+    (void)self;
+    if (hook != NULL) {
+        rb_internal_thread_remove_event_hook(hook);
+        hook = NULL;
+    }
+    return Qnil;
+}
+
+static VALUE native_running_p(VALUE self) {
+    (void)self;
+    return (hook != NULL) ? Qtrue : Qfalse;
+}
+
+/* Nanoseconds all threads have waited for the GVL while measuring. */
+static VALUE native_wait_ns(VALUE self) {
+    (void)self;
+    return ULL2NUM(__atomic_load_n(&waited_ns, __ATOMIC_RELAXED));
+}
+
+/* Called by Ruby's `require`, so it must have external linkage. */
+void Init_duel_gvl(void) {
+    VALUE duel = rb_define_module("Duel");
+    VALUE gvl = rb_define_module_under(duel, "GVL");
+    VALUE hook_module = rb_define_module_under(gvl, "Hook");
+
+    ready_key = rb_internal_thread_specific_key_create();
+    rb_define_module_function(hook_module, "start", native_start, 0);
+    rb_define_module_function(hook_module, "stop", native_stop, 0);
+    rb_define_module_function(hook_module, "running?", native_running_p, 0);
+    rb_define_module_function(hook_module, "wait_ns", native_wait_ns, 0);
+}

data/ext/duel_gvl/extconf.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+# The extension is optional: without it, Duel::GVL leaves its metric out,
+# so a gem install never fails over it. Where it can't be built (JRuby and
+# TruffleRuby, which have no GVL to wait for; Windows, where Ruby's thread
+# event hooks do nothing; 32-bit platforms, where a thread's slot can't
+# hold a timestamp; no working C compiler), write a Makefile that does
+# nothing.
+def write_noop_makefile(reason)
+  warn "duel-gvl: not building the extension (#{reason}); there will be no gvl_wait metric"
+  File.write("Makefile", "all install clean distclean static:\n\t@:\n.PHONY: all install clean distclean static\n")
+end
+
+if RUBY_ENGINE != "ruby"
+  write_noop_makefile("#{RUBY_ENGINE} has no GVL")
+elsif Gem.win_platform?
+  write_noop_makefile("Ruby's thread event hooks do nothing on Windows")
+elsif [0].pack("J").bytesize < 8
+  write_noop_makefile("a 32-bit platform")
+else
+  require "mkmf"
+
+  if try_compile("int main(void) { return 0; }") && have_func("rb_internal_thread_specific_get", "ruby/thread.h")
+    $CFLAGS << " -O2 -std=c99 -Wall -Wextra -Wno-unused-parameter -Wno-declaration-after-statement" # rubocop:disable Style/GlobalVars -- mkmf API
+    create_makefile("duel_gvl/duel_gvl")
+  else
+    write_noop_makefile("no working C compiler")
+  end
+end

data/lib/duel/gvl/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Duel
+  module GVL
+    VERSION = "0.1.0"
+  end
+end

data/lib/duel/gvl.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+require "duel"
+require_relative "gvl/version"
+
+module Duel
+  # How long threads waited for the GVL during each sample: the cost of
+  # the contention a change adds (holding the GVL longer around I/O, a C
+  # call that stops releasing it, more threads fighting for it), which
+  # CPU time doesn't show, since a thread waiting for the GVL uses none.
+  #
+  #   # .duel.rb
+  #   Duel.configure { |c| c.use :gvl }
+  #
+  # gvl_wait (a ratio metric, in nanoseconds) is measured for benchmarks with
+  # threads of their own (only: :timing), and left out of the rest, whose
+  # one thread has nothing to wait for. It needs CRuby and the gem's C
+  # extension (Duel::GVL::Hook); elsewhere it's left out.
+  module GVL
+    Duel.plugin(:gvl, self)
+
+    # Configures Duel for the plugin (c.use :gvl): the gvl_wait metric
+    # (where it's available), and the extension, loaded in workers.
+    # Returns the metric.
+    def self.configure(config)
+      config.in_worker { load_extension }
+      config.metric(Wait)
+    end
+
+    # Whether the extension is loaded to measure with.
+    def self.available? = const_defined?(:Hook, false)
+
+    # Loads the extension (Hook) where it can be: only on CRuby (another
+    # Ruby would try a build of CRuby's left in lib/), and only where it
+    # was built. Whether it's loaded. (Each worker loads it, before its
+    # metrics are made; the process that runs them needn't.)
+    def self.load_extension(engine: RUBY_ENGINE, feature: "duel_gvl/duel_gvl")
+      return false unless engine == "ruby"
+
+      require feature
+      available?
+    rescue LoadError
+      false
+    end
+
+    # gvl_wait: nanoseconds all threads waited for the GVL during a
+    # sample of a benchmark with threads of its own.
+    #
+    # Threads that hardly wait still wait a little now and then, as the
+    # scheduler has it (a thread's start and end are handoffs too), so a
+    # sample is judged on it only when it waited a tenth of its CPU time
+    # or more (CPU_FLOOR) on either version: code that starts waiting where it
+    # hardly did is judged (its ratio is many times over), code that
+    # hardly waits on both isn't judged on the noise. Threads that hardly
+    # wait wait some 0.3-2.5% of their CPU time, on a busy machine too;
+    # threads that fight for the GVL wait as long as they run, or longer
+    # (a thread wanting it waits out the holder's time slice), and those
+    # that only now and then want it at once, 5% to more than 100%, as
+    # busy as the machine is. A share of CPU time, and not a time, since
+    # a sample is as long as it takes for its CPU time to settle.
+    #
+    # How long threads wait depends on when the operating system runs
+    # them, so on everything else the machine is doing: on a busy one,
+    # the same code's samples can wait half or twice as long. What makes
+    # threads wait much longer is a change that holds the GVL where it
+    # didn't, which waits many times as long; so it's slower only past
+    # half as much again (LIMIT), and it isn't judged across the board,
+    # where the margin is a quarter of that (an eighth more).
+    #
+    # It doesn't size samples: four threads fighting for the GVL wait
+    # three times as long as they run, and samples sized by that would be
+    # too short for their CPU time to settle.
+    class Wait < Metric
+      CPU_FLOOR = 0.1
+
+      LIMIT = 1.5
+
+      def self.measures = {"gvl_wait" => {kind: :ratio, unit: "ns", cpu_floor: CPU_FLOOR, limit: LIMIT, sizes_samples: false, across: false}}
+
+      def self.available? = GVL.available?
+
+      def start_sample(sample)
+        @measuring = sample.benchmark.only == :timing
+        return unless @measuring
+
+        Hook.start
+        @waited = Hook.wait_ns
+      end
+
+      def stop_sample
+        return unless @measuring
+
+        Hook.stop
+        Hook.wait_ns - @waited
+      end
+    end
+  end
+end

data/sig/duel/gvl.rbs

@@ -0,0 +1,52 @@
+module Duel
+  # How long threads waited for the GVL during each sample of a benchmark
+  # with threads of its own (gvl_wait).
+  module GVL
+    VERSION: String
+
+    # Configures Duel for the plugin (c.use :gvl): the gvl_wait metric
+    # (where it's available), and the extension, loaded in workers.
+    # Returns the metric.
+    def self.configure: (Config config) -> singleton(Metric)
+
+    # Whether the extension is loaded to measure with.
+    def self.available?: () -> bool
+
+    # Loads the extension (Hook) where it can be; whether it's loaded.
+    def self.load_extension: (?engine: String, ?feature: String) -> bool
+
+    # The C extension: the total time threads have waited for the GVL
+    # while it's measuring.
+    module Hook
+      # Starts measuring (again); does nothing while measuring.
+      def self.start: () -> nil
+
+      # Stops measuring; the total stays.
+      def self.stop: () -> nil
+
+      def self.running?: () -> bool
+
+      # Nanoseconds all threads have waited for the GVL while measuring.
+      def self.wait_ns: () -> Integer
+    end
+
+    # gvl_wait: nanoseconds all threads waited for the GVL during a
+    # sample of a benchmark with threads of its own; judged at CPU_FLOOR
+    # of the sample's CPU time or more on either version, slower past
+    # LIMIT, and not across the board.
+    class Wait < Metric
+      CPU_FLOOR: Float
+
+      LIMIT: Float
+
+      @measuring: bool
+      @waited: Integer
+
+      def self.available?: () -> bool
+
+      def start_sample: (Sample sample) -> void
+
+      def stop_sample: () -> Integer?
+    end
+  end
+end

metadata

@@ -0,0 +1,70 @@
+--- !ruby/object:Gem::Specification
+name: duel-gvl
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Erik Berlin
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: duel
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
+description: 'A Duel plugin: benchmarks with threads of their own are judged on how
+  long their threads waited for the GVL too, so a change that adds contention fails
+  even when its CPU time doesn''t.'
+email:
+- sferik@gmail.com
+executables: []
+extensions:
+- ext/duel_gvl/extconf.rb
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- ext/duel_gvl/duel_gvl.c
+- ext/duel_gvl/extconf.rb
+- lib/duel/gvl.rb
+- lib/duel/gvl/version.rb
+- sig/duel/gvl.rbs
+homepage: https://github.com/sferik/duel-ruby/tree/main/plugins/gvl
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/sferik/duel-ruby/tree/main/plugins/gvl
+  changelog_uri: https://github.com/sferik/duel-ruby/blob/main/plugins/gvl/CHANGELOG.md
+  bug_tracker_uri: https://github.com/sferik/duel-ruby/issues
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.4'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.23
+specification_version: 4
+summary: How long threads waited for the GVL, for every Duel benchmark with threads
+  of its own
+test_files: []