corkscrews 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 47479f224980721d4b7b42338c36b0c6231bbef6ee46e7196f8092578ad58535
+  data.tar.gz: 5e9223bb6124b75df1a0b1e2da1cafefe925d70e9df81550f1c882a076f3396c
+SHA512:
+  metadata.gz: 81baabd850c9ac7902a999e11fc50c0c8dd8a569aad063542459d89d093d435c3c340c94da76737bde9ab4083b917afd42b420e8fd3bb65eed081052faca903d
+  data.tar.gz: '085b8ee57acfd988940f8c8db093bf93f55140f46001dd0278c01b5499ac16b5b9597652e3682e5d8434d5201959ea12d05b2bfffda1b1a5ad186ae22cef0f50'

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Yudai Takada
+
+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,130 @@
+# Corkscrews
+
+Corkscrews is a Ruby causal-profiling toolkit for bottleneck experiments. It
+records progress points, line samples, latency spans, Ruby-level wait targets,
+and validation benchmark results, then reports virtual speedup curves for likely
+bottlenecks.
+
+The gem includes a portable Ruby engine and a native CRuby extension for thread
+hooks, GC hooks, delay accounting, sampling handoff, stamp inheritance, native
+monitor ticks, native sample ring flushes, thread-state gauges, adaptive
+line/wait experiment rounds, and runtime snapshots.
+
+## Installation
+
+Install the gem and add it to the application's Gemfile by executing:
+
+```sh
+bundle add corkscrews
+```
+
+If Bundler is not being used to manage dependencies, install the gem by
+executing:
+
+```sh
+gem install corkscrews
+```
+
+Corkscrews requires CRuby 3.3 or newer. The native extension is compiled during
+installation when the required CRuby APIs are available; otherwise the Ruby
+engine remains the portable fallback.
+
+## Usage
+
+Profile an existing Ruby command with the CLI:
+
+```sh
+corkscrews run --repeat 3 --targets both --output run.corkscrews.ndjson -- ruby app.rb
+```
+
+Generate reports from the recorded NDJSON file:
+
+```sh
+corkscrews report --html report.html --firefox profile.json run.corkscrews.ndjson
+```
+
+`--firefox` writes an aggregate Firefox Profiler JSON with thread, sample,
+stack, frame, function, marker, and string tables. It includes target summary
+markers and round timeline markers derived from Corkscrews' NDJSON records.
+
+### Progress Points
+
+Application code can provide throughput and latency points:
+
+```ruby
+require "corkscrews"
+
+Corkscrews.latency_begin(:request)
+do_work
+Corkscrews.progress(:request)
+Corkscrews.latency_end(:request)
+```
+
+`--targets lines` records line targets. `--targets waits` or `--targets both`
+also enables Ruby-level wrappers for `Mutex`, `Thread::Queue`,
+`Thread::SizedQueue`, `Thread::ConditionVariable`, `Kernel.sleep`, and `IO`.
+
+### Native Signal Source
+
+The default signal source is Ruby's `setitimer` path. The native monitor can
+deliver `SIGPROF` to the registered profiling thread by setting
+`CORKSCREWS_NATIVE_SIGNALS=1`; this path is recorded in native counters and kept
+opt-in because direct pthread signal delivery can conflict with platform signal
+handling in embedded Ruby processes.
+
+## Validation
+
+Run the bundled validation harness:
+
+```sh
+corkscrews validate --quick
+corkscrews validate
+```
+
+The validation harness includes benchmark manifests for serial CPU hotspots,
+false hotspots under concurrency, I/O wait, lock contention, GVL contention, GC
+pressure, queue pipeline behavior, and native-call attribution smoke coverage.
+
+## Development
+
+After checking out the repo, install dependencies:
+
+```sh
+bundle install
+```
+
+Compile the native extension and run the test suite:
+
+```sh
+bundle exec rake compile
+bundle exec rake
+```
+
+Install the gem locally from the checkout:
+
+```sh
+bundle exec rake install
+```
+
+Run validation locally:
+
+```sh
+ruby -Ilib exe/corkscrews validate --quick
+ruby -Ilib exe/corkscrews validate
+python3 validate/harness/stats_check.py
+```
+
+For local CLI testing without installing the gem, use:
+
+```sh
+ruby -Ilib exe/corkscrews run --repeat 1 --output run.corkscrews.ndjson -- ruby app.rb
+```
+
+## Contributing
+
+Bug reports and pull requests are welcome. Please include a focused reproduction
+or validation benchmark when changing profiling behavior.
+
+## License
+
+The gem is available as open source under the terms of the MIT License.

data/Rakefile

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task :compile do
+  sh "cd ext/corkscrews && ruby extconf.rb && make"
+end
+
+task :validate do
+  sh "ruby -Ilib exe/corkscrews validate --quick"
+end
+
+task :validate_full do
+  sh "ruby -Ilib exe/corkscrews validate"
+end
+
+task default: :spec

data/exe/corkscrews

@@ -0,0 +1,9 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+lib = File.expand_path("../lib", __dir__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+
+require "corkscrews/cli"
+
+exit Corkscrews::CLI.new(ARGV).run

data/ext/corkscrews/corkscrews.c

@@ -0,0 +1,24 @@
+#include "ruby.h"
+#include "corkscrews_native.h"
+
+cs_global_t cs_global;
+
+void Init_corkscrews_hooks(VALUE rb_mCorkscrews);
+void Init_corkscrews_sampler(VALUE rb_mCorkscrews);
+void Init_corkscrews_delay(VALUE rb_mCorkscrews);
+void Init_corkscrews_record(VALUE rb_mCorkscrews);
+void Init_corkscrews_monitor(VALUE rb_mCorkscrews);
+
+void
+Init_corkscrews(void)
+{
+    VALUE rb_mCorkscrews = rb_define_module("Corkscrews");
+    VALUE rb_mNativeExtension = rb_define_module_under(rb_mCorkscrews, "NativeExtension");
+    atomic_store(&cs_global.sample_period_ns, 1000000ULL);
+    rb_define_const(rb_mNativeExtension, "AVAILABLE", Qtrue);
+    Init_corkscrews_hooks(rb_mCorkscrews);
+    Init_corkscrews_sampler(rb_mCorkscrews);
+    Init_corkscrews_delay(rb_mCorkscrews);
+    Init_corkscrews_record(rb_mCorkscrews);
+    Init_corkscrews_monitor(rb_mCorkscrews);
+}

data/ext/corkscrews/corkscrews_native.h

@@ -0,0 +1,85 @@
+#ifndef CORKSCREWS_NATIVE_H
+#define CORKSCREWS_NATIVE_H
+
+#include "ruby.h"
+#include "ruby/debug.h"
+#include "ruby/thread.h"
+#include "ruby/internal/event.h"
+
+#include <stdatomic.h>
+#include <stdint.h>
+
+#define CS_RECORD_RING_SIZE 8192
+
+typedef struct {
+    _Atomic uint64_t global_delay_ns;
+    _Atomic uint64_t experiment_id;
+    _Atomic uintptr_t target_iseq;
+    _Atomic uint32_t target_line;
+    _Atomic uint32_t target_kind;
+    _Atomic uint32_t speedup_pct;
+    _Atomic uint64_t sample_period_ns;
+    _Atomic uint64_t vclock_credit_ns;
+    _Atomic uint64_t samples;
+    _Atomic uint64_t target_hits;
+    _Atomic uint64_t thread_events_started;
+    _Atomic uint64_t thread_events_ready;
+    _Atomic uint64_t thread_events_resumed;
+    _Atomic uint64_t thread_events_suspended;
+    _Atomic uint64_t thread_events_exited;
+    _Atomic uint64_t thread_state_running;
+    _Atomic uint64_t thread_state_ready;
+    _Atomic uint64_t thread_state_suspended;
+    _Atomic uint64_t thread_state_dead;
+    _Atomic uint64_t thread_live_count;
+    _Atomic uint64_t thread_max_live_count;
+    _Atomic uint64_t gc_enter_count;
+    _Atomic uint64_t gc_exit_count;
+    _Atomic uint64_t gc_pause_ns;
+    _Atomic uint64_t debt_settlements;
+    _Atomic uint64_t debt_settled_ns;
+    _Atomic uint64_t monitor_ticks;
+    _Atomic uint64_t monitor_signals;
+    _Atomic uint64_t monitor_signal_failures;
+    _Atomic uint64_t monitor_start_count;
+    _Atomic uint64_t monitor_stop_count;
+    _Atomic uint8_t monitor_running;
+    _Atomic uint8_t monitor_target_registered;
+} cs_global_t;
+
+typedef struct {
+    _Atomic uint64_t local_delay_ns;
+    _Atomic uint64_t inherited_stamp;
+    _Atomic uint8_t state;
+    _Atomic uint8_t state_initialized;
+    _Atomic uint8_t settle_requested;
+    _Atomic uint64_t suspended_since_id;
+} cs_thread_t;
+
+typedef struct {
+    uint64_t sequence;
+    uintptr_t site_key;
+    uint32_t line;
+    uint32_t target_kind;
+    uint32_t speedup_pct;
+    uint64_t experiment_id;
+    uint64_t delay_ns;
+    uint8_t target_hit;
+} cs_record_entry_t;
+
+extern cs_global_t cs_global;
+
+cs_thread_t *cs_thread_data_for(VALUE thread, int create);
+cs_thread_t *cs_current_thread_data(void);
+uint64_t cs_settled_now_for_current_thread(void);
+void cs_stamp_write(VALUE object);
+void cs_stamp_inherit(VALUE object);
+void cs_delay_set_experiment(uint32_t target_kind, uintptr_t target_iseq, uint32_t target_line, uint32_t speedup_pct);
+void cs_delay_clear_experiment(void);
+void cs_delay_issue_for_current(uint64_t delay_ns);
+uint64_t cs_delay_settle_current(void);
+void cs_delay_request_settle(void);
+VALUE cs_record_snapshot(VALUE self);
+void cs_record_line_sample(uintptr_t site_key, uint32_t line, uint8_t target_hit, uint64_t delay_ns);
+
+#endif

data/ext/corkscrews/delay.c

@@ -0,0 +1,259 @@
+#include "corkscrews_native.h"
+
+#include <stdlib.h>
+#include <time.h>
+
+static VALUE stamp_table;
+static ID id_aref;
+static ID id_aset;
+static rb_postponed_job_handle_t settle_job_handle = POSTPONED_JOB_HANDLE_INVALID;
+static rb_internal_thread_specific_key_t thread_key = -1;
+
+static void *
+nogvl_sleep(void *ptr)
+{
+    uint64_t ns = *((uint64_t *)ptr);
+    struct timespec ts;
+    ts.tv_sec = (time_t)(ns / 1000000000ULL);
+    ts.tv_nsec = (long)(ns % 1000000000ULL);
+    nanosleep(&ts, NULL);
+    return NULL;
+}
+
+cs_thread_t *
+cs_thread_data_for(VALUE thread, int create)
+{
+    if (thread_key == -1) {
+        rb_raise(rb_eRuntimeError, "corkscrews delay storage is not initialized");
+    }
+
+    cs_thread_t *data = rb_internal_thread_specific_get(thread, thread_key);
+    if (!data && create) {
+        data = calloc(1, sizeof(cs_thread_t));
+        if (!data) rb_memerror();
+        atomic_store(&data->local_delay_ns, atomic_load(&cs_global.global_delay_ns));
+        atomic_store(&data->inherited_stamp, 0);
+        atomic_store(&data->state, 3);
+        atomic_store(&data->state_initialized, 0);
+        atomic_store(&data->settle_requested, 0);
+        atomic_store(&data->suspended_since_id, 0);
+        rb_internal_thread_specific_set(thread, thread_key, data);
+    }
+    return data;
+}
+
+cs_thread_t *
+cs_current_thread_data(void)
+{
+    return cs_thread_data_for(rb_thread_current(), 1);
+}
+
+uint64_t
+cs_settled_now_for_current_thread(void)
+{
+    cs_thread_t *data = cs_current_thread_data();
+    uint64_t local = atomic_load(&data->local_delay_ns);
+    uint64_t inherited = atomic_load(&data->inherited_stamp);
+    return local > inherited ? local : inherited;
+}
+
+void
+cs_delay_set_experiment(uint32_t target_kind, uintptr_t target_iseq, uint32_t target_line, uint32_t speedup_pct)
+{
+    atomic_fetch_add(&cs_global.experiment_id, 1);
+    atomic_store(&cs_global.target_kind, target_kind);
+    atomic_store(&cs_global.target_iseq, target_iseq);
+    atomic_store(&cs_global.target_line, target_line);
+    atomic_store(&cs_global.speedup_pct, speedup_pct);
+}
+
+void
+cs_delay_clear_experiment(void)
+{
+    atomic_store(&cs_global.target_kind, 0);
+}
+
+void
+cs_delay_issue_for_current(uint64_t delay_ns)
+{
+    /* Paper basis: Coz SOSP'15 Section 3.4 / Figure 3: a target hit
+     * virtually speeds that code by charging equivalent delay to other
+     * execution while crediting the thread that hit the target.
+     * Paper URL: https://arxiv.org/abs/1608.03676 */
+    cs_thread_t *self = cs_current_thread_data();
+    atomic_fetch_add(&cs_global.global_delay_ns, delay_ns);
+    atomic_fetch_add(&self->local_delay_ns, delay_ns);
+}
+
+uint64_t
+cs_delay_settle_current(void)
+{
+    /* Paper basis: Coz SOSP'15 Section 3.4 inserts pauses for virtual
+     * speedup. The CRuby adaptation pays that debt without holding GVL.
+     * Paper URL: https://arxiv.org/abs/1608.03676 */
+    cs_thread_t *self = cs_current_thread_data();
+    uint64_t global = atomic_load(&cs_global.global_delay_ns);
+    uint64_t local = atomic_load(&self->local_delay_ns);
+    uint64_t inherited = atomic_load(&self->inherited_stamp);
+    uint64_t settled = local > inherited ? local : inherited;
+    if (global <= settled) {
+        atomic_store(&self->settle_requested, 0);
+        return 0;
+    }
+
+    uint64_t debt = global - settled;
+    rb_thread_call_without_gvl(nogvl_sleep, &debt, RUBY_UBF_IO, NULL);
+    atomic_store(&self->local_delay_ns, global);
+    atomic_store(&self->settle_requested, 0);
+    atomic_fetch_add(&cs_global.debt_settlements, 1);
+    atomic_fetch_add(&cs_global.debt_settled_ns, debt);
+    return debt;
+}
+
+static void
+settle_postponed_job(void *arg)
+{
+    (void)arg;
+    cs_delay_settle_current();
+}
+
+void
+cs_delay_request_settle(void)
+{
+    cs_thread_t *self = cs_current_thread_data();
+    if (atomic_exchange(&self->settle_requested, 1)) return;
+    if (settle_job_handle != POSTPONED_JOB_HANDLE_INVALID) {
+        rb_postponed_job_trigger(settle_job_handle);
+    }
+}
+
+void
+cs_stamp_write(VALUE object)
+{
+    /* Paper basis: Coz SOSP'15 Section 3.4 uses delayed execution as
+     * the virtual-speedup mechanism. Stamp inheritance is the CRuby
+     * synchronization adaptation that prevents double-paying delay.
+     * Paper URL: https://arxiv.org/abs/1608.03676 */
+    rb_funcall(stamp_table, id_aset, 2, object, ULL2NUM(cs_settled_now_for_current_thread()));
+}
+
+void
+cs_stamp_inherit(VALUE object)
+{
+    VALUE stored = rb_funcall(stamp_table, id_aref, 1, object);
+    if (NIL_P(stored)) return;
+
+    cs_thread_t *self = cs_current_thread_data();
+    uint64_t stamp = NUM2ULL(stored);
+    uint64_t inherited = atomic_load(&self->inherited_stamp);
+    if (stamp > inherited) {
+        atomic_store(&self->inherited_stamp, stamp);
+    }
+}
+
+static VALUE
+delay_available_p(VALUE self)
+{
+    (void)self;
+    return Qtrue;
+}
+
+static VALUE
+delay_set_experiment(VALUE self, VALUE kind, VALUE iseq, VALUE line, VALUE speedup)
+{
+    (void)self;
+    cs_delay_set_experiment(NUM2UINT(kind), (uintptr_t)NUM2ULL(iseq), NUM2UINT(line), NUM2UINT(speedup));
+    return Qnil;
+}
+
+static VALUE
+delay_set_sample_period(VALUE self, VALUE period_ns)
+{
+    (void)self;
+    atomic_store(&cs_global.sample_period_ns, NUM2ULL(period_ns));
+    return Qnil;
+}
+
+static VALUE
+delay_clear_experiment(VALUE self)
+{
+    (void)self;
+    cs_delay_clear_experiment();
+    return Qnil;
+}
+
+static VALUE
+delay_settle_current(VALUE self)
+{
+    (void)self;
+    return ULL2NUM(cs_delay_settle_current());
+}
+
+static VALUE
+delay_request_settle(VALUE self)
+{
+    (void)self;
+    cs_delay_request_settle();
+    return Qnil;
+}
+
+static VALUE
+delay_debt_current(VALUE self)
+{
+    (void)self;
+    uint64_t global = atomic_load(&cs_global.global_delay_ns);
+    uint64_t settled = cs_settled_now_for_current_thread();
+    return ULL2NUM(global > settled ? global - settled : 0);
+}
+
+static VALUE
+delay_settled_now(VALUE self)
+{
+    (void)self;
+    return ULL2NUM(cs_settled_now_for_current_thread());
+}
+
+static VALUE
+delay_stamp_write(VALUE self, VALUE object)
+{
+    (void)self;
+    cs_stamp_write(object);
+    return Qnil;
+}
+
+static VALUE
+delay_stamp_inherit(VALUE self, VALUE object)
+{
+    (void)self;
+    cs_stamp_inherit(object);
+    return Qnil;
+}
+
+void
+Init_corkscrews_delay(VALUE rb_mCorkscrews)
+{
+    VALUE rb_mDelay = rb_define_module_under(rb_mCorkscrews, "Delay");
+    VALUE rb_mObjectSpace = rb_const_get(rb_cObject, rb_intern("ObjectSpace"));
+    VALUE rb_cWeakMap = rb_const_get(rb_mObjectSpace, rb_intern("WeakMap"));
+
+    if (thread_key == -1) {
+        thread_key = rb_internal_thread_specific_key_create();
+    }
+
+    id_aref = rb_intern("[]");
+    id_aset = rb_intern("[]=");
+    stamp_table = rb_funcall(rb_cWeakMap, rb_intern("new"), 0);
+    rb_global_variable(&stamp_table);
+    settle_job_handle = rb_postponed_job_preregister(0, settle_postponed_job, NULL);
+
+    rb_define_singleton_method(rb_mDelay, "available?", delay_available_p, 0);
+    rb_define_singleton_method(rb_mDelay, "set_experiment", delay_set_experiment, 4);
+    rb_define_singleton_method(rb_mDelay, "set_sample_period", delay_set_sample_period, 1);
+    rb_define_singleton_method(rb_mDelay, "clear_experiment", delay_clear_experiment, 0);
+    rb_define_singleton_method(rb_mDelay, "settle_current", delay_settle_current, 0);
+    rb_define_singleton_method(rb_mDelay, "request_settle", delay_request_settle, 0);
+    rb_define_singleton_method(rb_mDelay, "debt_current", delay_debt_current, 0);
+    rb_define_singleton_method(rb_mDelay, "settled_now", delay_settled_now, 0);
+    rb_define_singleton_method(rb_mDelay, "stamp_write", delay_stamp_write, 1);
+    rb_define_singleton_method(rb_mDelay, "stamp_inherit", delay_stamp_inherit, 1);
+}

data/ext/corkscrews/extconf.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require "mkmf"
+require "rubygems"
+
+required_version = Gem::Version.new("3.3")
+current_version = Gem::Version.new(RUBY_VERSION)
+abort "corkscrews native extension requires Ruby >= #{required_version}" if current_version < required_version
+
+required = %w[
+  rb_profile_frames
+  rb_thread_call_without_gvl
+  rb_add_event_hook
+  rb_internal_thread_add_event_hook
+  rb_internal_thread_specific_key_create
+  rb_internal_thread_specific_get
+  rb_internal_thread_specific_set
+  rb_postponed_job_preregister
+  rb_postponed_job_trigger
+]
+
+missing_required = required.reject { |name| have_func(name) }
+abort "missing required Ruby C APIs: #{missing_required.join(", ")}" unless missing_required.empty?
+
+create_makefile("corkscrews/corkscrews")