pf2 0.14.0 → 1.0.0.alpha1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 117782be2a4d708cf477b5efb4cdf6cb7fbd7f58ef416d62b780c9d9ff4c7f16
-  data.tar.gz: 554efc38d2a316a84a9cd727afd9dac32815af50bc164409237bbb0fe38a9de9
+  metadata.gz: 9f219b8aa5b5281a6ed662a085e00f82636ab52365d2b0f7a8d61a3e06bfc9c6
+  data.tar.gz: 162e1eae488afe17e33291f63f807642aa304d7df8069cb165e3a25ce6f10895
 SHA512:
-  metadata.gz: 48601b3a739539cd028d3d72cbbb2b2838c2c3ca285a438b65be8fb3e14b6a7f4b1d67438f0f15f855d7d28a5d9dc815874a69d0acafc05d524adfb1ca87d1e4
-  data.tar.gz: 11759b313c52670f56f1fb05ed09565806049526aa649d740479d4363e636506a5eb745dcd9ddfaba6ea245dfd2b6547370bfe56df5b6166a740850ae36fa621
+  metadata.gz: 37b6a1aa4f6ab0753d86983d76cbdfae4b3dfbb7464afb0388aa113d728725f09eabcabb2ae7c2ffadc5ab797be75675b5b27b465c20565d5d69f30291d4837f
+  data.tar.gz: 7b69aea55c8873cfd6e28fba3bdddd09325e4c73e1e3e44a5be48fcb9ad776b03e811c707fc049ad8ccc1590e7c011032be7f4053e3d15a5ba5b50c4344db656

data/CHANGELOG.md

@@ -1,104 +1,5 @@
 ## [Unreleased]
 
-
-## [0.14.0] - 2026-01-25
-
-### Added
-
-- `Pf2.profile` can now directly write a Firefox Profiler-compatible profile into a file or an IO-ish object. Check out `Pf2.profile`'s `out:` and `format:` option.
-- An _experimental_ pprof-compatible recorder has been added. Profiles generated by this reporter can be passed to tools such as `go tool pprof`, or services such as Grafana Pyroscope or Google Cloud's Cloud Profiler.
-
-### Changed
-
-- `Pf2::Reporter::FirefoxProfilerSer2` now emits a JSON string, not a Hash. Parse the JSON to obtain the original representaion.
-
-### Fixed
-
-- Fixed a crash when a delayed SIGPROF is received after `Pf2.stop` is called.
-
-
-## [0.13.0] - 2026-01-18
-
-### Added
-
-- Pf2 should now have a dramatically lower memory footprint.
-  - Samples are now stored in a compact hashmap internally.
-  - See https://github.com/osyoyu/pf2/pull/85 for details.
-
-### Fixed
-
-- `pf2 serve` command now properly works. (Thanks @hanazuki)
-
-
-## [0.12.0] - 2026-01-09
-
-### Added
-
-- `Pf2.profile` now accepts the same options as `Pf2.start`.
-- The resulting profile now has `collected_sample_count` and `dropped_sample_count` fields.
-
-### Fixed
-
-- Samples captured after the collector thread was stopped now get included in the profile.
-  - This shouldn't matter in practice (this all happens after `Pf2.stop` is called).
-
-### Changed
-
-- Accepted max stack depth is expanded to 1024 for Ruby (was 200) and 512 for native (was 300).
-  - This is not configurable, but should be sufficient for most use cases. Please open an issue if you need higher limits.
-- Pf2.profile now accepts the same parameters as Pf2.start.
-- Internal changes
-  - Updated libbacktrace to the latest version as of 2026/1/8.
-  - Tests are now much more stabilized.
-
-
-## [0.11.3] - 2025-12-28
-
-This version is for testing the new release process through [Trusted Publishing](https://guides.rubygems.org/trusted-publishing/). All code is identical to 0.11.2.
-
-
-## [0.11.2] - 2025-12-28
-
-0.11.1 was yanked since it was accidentally published without libbacktrace vendored. Use 0.11.2.
-
-### Fixed
-
-- Fixed issues preventing builds on macOS.
-
-
-## [0.11.0] - 2025-12-27
-
-### Added
-
-- RDoc documentation is now online - https://osyoyu.github.io/pf2/
-- Native stack consolidation now supports LTO-ed binaries (@hanazuki)
-
-### Changed
-
-- `Pf2c` module is now completely removed. `Pf2c::Session` has been merged as `Pf2::Session`.
-
-### Fixed
-
-- Fixed an bug where the program crashes when a `Pf2::Session` is GC'd before profiling starts.
-- Fixed an bug where the program crashes when the native stack was more than 200 frames deep.
-
-
-## [0.10.0] - 2025-12-26
-
-### Added
-
-**This version contains a complete rewrite of the profiler!**
-
-- The default sample collection backend has been switched to the new C-based backend.
-  - The previous Rust-based backed has been removed. Use v0.9.0 if you need it.
-- macOS / non-Linux platform support!
-  - On platforms which lack `timer_create(3)` such as macOS, Pf2 now fall backs to `setitimer(3)` based sampling. This mode does not support per-thread CPU time sampling.
-
-### Changed
-
-- `logger` is now declared as a dependency (Ruby 4.0 compat).
-
-
 ## [0.9.0] - 2025-03-22
 
 ## Added
@@ -110,7 +11,6 @@ This version is for testing the new release process through [Trusted Publishing]
 
 - Set SA_RESTART flag to reduce EINTRs in profiled code
 
-
 ## [0.8.0] - 2025-01-27
 
 ## Added
@@ -119,14 +19,12 @@ This version is for testing the new release process through [Trusted Publishing]
   - This serializer is more efficient and has a smaller memory footprint than the default serializer.
   - Ser2 still lacks some features, such as weaving of native stacks.
 
-
 ## [0.7.1] - 2025-01-02
 
 ### Fixed
 
 - Reverted Cargo.lock version to 3 to support older versions of Rust (<1.78).
 
-
 ## [0.7.0] - 2025-01-03
 
 ### Changed

data/README.md

@@ -3,9 +3,6 @@ Pf2
 
 A experimental sampling-based profiler for Ruby 3.3+.
 
-- GitHub: https://github.com/osyoyu/pf2
-- Documentation: https://osyoyu.github.io/pf2/
-
 Notable Capabilites
 --------
 
@@ -16,48 +13,7 @@ Notable Capabilites
 Usage
 --------
 
-### Installation
-
-You will need a C compiler to build the native extension.
-
-Add this line to your application's Gemfile:
-
-```ruby
-gem 'pf2'
-
-# When using the main branch, specify submodules: true
-gem 'pf2', git: 'https://github.com/osyoyu/pf2.git', submodules: true
-```
-
-Pf2 can be installed as a standalone CLI tool as well.
-
-```console
-gem install pf2
-```
-
-### Profiling
-
-Surround and run your code with `Pf2.profile { }`.
-
-```ruby
-profile = Pf2.profile(out: 'profile.json') do
-  your_code_here() # will be profiled
-  Thread.new { threaded_code() } # will also be profiled
-end
-```
-
-Then drop 'profile.json' into https://profiler.firefox.com/ for nice visualization.
-
-Options for `Pf2.profile`:
-
-| Option      | Type              | Description                                    |
-| ----------- | ----------------- | ---------------------------------------------- |
-| interval_ms | Integer           | Sampling interval in milliseconds (default: 9) |
-| time_mode   | `:cpu` or `:wall` | Sampling timer mode (default: `:cpu`)          |
-| out         | String or IO-like | Location to write collected profile data       |
-| format      | `:firefox` or `:pf2prof` | Profile format to be saved              |
-
-### Direct visualization using 'pf2 serve'
+### Quickstart
 
 Run your Ruby program through `pf2 serve`.
 Wait a while until Pf2 collects profiles (or until the target program exits), then open the displayed link for visualization.
@@ -70,32 +26,39 @@ $ pf2 serve -- ruby target.rb
 I'm the target program!
 ```
 
-No profile data is sent to Mozilla's servers. https://profiler.firefox.com operates inside your browser, unless you explicitly upload your profile for sharing.
-
-### More precise control
+### Profiling
 
-More precise control may be acheived by using `Pf2.start` and `Pf2.stop`.
+Pf2 will collect samples every 10 ms of wall time by default.
 
 ```ruby
-Pf2.start
+# Threads in `threads` will be tracked
+Pf2.start(threads: [Thread.current])
 
 your_code_here
 
-# Stop profiling
+# Stop profiling and save the profile for visualization
 profile = Pf2.stop
-
-# Save file for later visualization using 'pf2 report'
-File.binwrite("my_program.pf2prof", Marshal.dump(profile))
+File.write("my_program.pf2profile", profile)
 ```
 
-`Pf2.start` accepts `interval_ms` and `time_mode`.
+Alternatively, you may provide a code block to profile.
+
+```ruby
+profile = Pf2.profile do
+  your_code_here() # will be profiled
+  Thread.new { threaded_code() } # will also be profiled
+end
+
+# Save the profile for visualization
+File.write("my_program.pf2profile", profile)
+```
 
 ### Reporting / Visualization
 
 Profiles can be visualized using the [Firefox Profiler](https://profiler.firefox.com/).
 
 ```console
-$ pf2 report -o report.json my_program.pf2prof
+$ pf2 report -o report.json my_program.pf2profile
 ```
 
 Alternatively, `pf2 annotate` can be used to display hit counts side-by-side with source code.
@@ -104,10 +67,25 @@ Alternatively, `pf2 annotate` can be used to display hit counts side-by-side wit
 $ pf2 annotate my_program.pf2prof
 ```
 
+### Configuration
+
+Pf2 accepts the following configuration keys:
+
+```rb
+Pf2.start(
+  interval_ms: 9,        # Integer: The sampling interval in milliseconds (default: 9)
+  time_mode: :cpu,        # `:cpu` or `:wall`: The sampling timer's mode
+                          # (default: `:cpu` for SignalScheduler, `:wall` for TimerThreadScheduler)
+  threads: [th1, th2],    # `Array<Thread>` | `:all`: A list of Ruby Threads to be tracked.
+                          # When `:all` or unspecified, Pf2 will track all active Threads.
+)
+```
+
+
 Overhead
 --------
 
-While Pf2 aims to be non-disturbulent as much as possible, a small overhead is still incured.
+While Pf2 aims to be non-disturbulent as much as possible, a small overhead still is incured.
 
 (TBD)
 
@@ -130,35 +108,45 @@ Pf2 is a _sampling profiler_. This means that Pf2 collects _samples_ of program
 
 Pf2 uses the `rb_profile_thread_frames()` API for sampling. When to do so is controlled by _Schedulers_, described in the following section.
 
-### Scheduling
+### Schedulers
 
-Schedulers determine when to execute sample collection, based on configuration (time mode and interval).
+Schedulers determine when to execute sample collection, based on configuration (time mode and interval). Pf2 has two schedulers available.
 
-#### Signal-based scheduling
+#### SignalScheduler (Linux-only)
 
-Pf2 schedules sample collection using POSIX timers. It creates a POSIX timer using `timer_create(3)` where available, or otherwise `setitimer(3)`. This leaves the actual time-keeping to the operating system kernel, which is capable of tracking accurate per-thread CPU time usage.
+The first is the `SignalScheduler`, based on POSIX timers. Pf2 will use this scheduler when possible. SignalScheduler creates a POSIX timer for each Ruby Thread (the underlying pthread to be more accurate) using `timer_create(2)`. This leaves the actual time-keeping to the OS, which is capable of tracking accurate per-thread CPU time usage.
 
-When the specified interval has arrived (the timer has _expired_), the OS delivers us a SIGPROF signal.
+When the specified interval has arrived (the timer has _expired_), the OS delivers us a SIGPROF signal. This is why the scheduler is named SignalScheduler.
 
 Signals are directed to Ruby Threads' underlying pthread, effectively "pausing" the Thread's activity. This routing is done using `SIGEV_THREAD_ID`, which is a Linux-only feature. Sample collection is done in the signal handler, which is expected to be more _accurate_, capturing the paused Thread's activity.
 
 This scheduler heavily relies on Ruby's 1:N Thread model (1 Ruby Threads is strongly tied to a native pthread). It will not work properly in MaNy (`RUBY_MN_THREADS=1`).
 
-#### ~~Timer-thread based scheduling~~
-
-Note: Timer thread-based scheduling has been removed in v0.10.0, when the profiling backend has been rewritten in C. This may come back in the future if needed.
+#### TimerThreadScheduler
 
 Another scheduler is the `TimerThreadScheduler`, which maintains a time-keeping thread by itself. A new native thread (pthread on Linux/macOS) will be created, and an infinite loop will be run inside. After `sleep(2)`-ing for the specified interval time, sampling will be queued using Ruby's Postponed Job API.
 
 This scheduler is wall-time only, and does not support CPU-time based profiling.
 
+#### macOS Support
+
+On platforms where `timer_create()` is not supported (namely macOS), Pf2 falls back to `setitimer()`.
+
+
+Wishlist
+--------
+
+- [Flame Scopes](https://www.brendangregg.com/flamescope.html)
+- More unit/e2e tests
+- more
+
 Development
 --------
 
 See [doc/development.md](doc/development.md).
 
+
 License
 --------
 
 The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
-See [LICENSE.txt](/LICENSE.txt) and [THIRD_PARTY_LICENSES.txt](/THIRD_PARTY_LICENSES.txt) for details.

data/Rakefile

@@ -1,7 +1,6 @@
 require 'bundler/gem_tasks'
 require 'rake/extensiontask'
 require 'minitest/test_task'
-require 'rdoc/task'
 
 task default: %i[]
 
@@ -15,9 +14,4 @@ Minitest::TestTask.create(:test) do |t|
   t.libs << "lib"
   t.warning = false
   t.test_globs = ["test/**/*_test.rb"]
-  t.extra_args << "--verbose"
-end
-
-RDoc::Task.new do |doc|
-  doc.rdoc_dir = "_site" # for GitHub pages
 end

data/doc/development.md

@@ -15,9 +15,3 @@ Releasing
 - Run `bundle install` to update Gemfile.lock
 - Commit changes
 - Run `bundle exec rake release`
-
-Hidden options for testing
---------
-
-- Pf2.start
-  - _test_no_install_timer: When true, no timer is installed. Manually send a SIGPROF to trigger sampling.

data/ext/pf2/configuration.c

@@ -1,12 +1,10 @@
 #include <ruby.h>
 #include <stdlib.h>
-#include <stdbool.h>
 
 #include "configuration.h"
 
 static int extract_interval_ms(VALUE options_hash);
 static enum pf2_time_mode extract_time_mode(VALUE options_hash);
-static bool extract__test_no_install_timer(VALUE options_hash);
 
 struct pf2_configuration *
 pf2_configuration_new_from_options_hash(VALUE options_hash)
@@ -18,7 +16,6 @@ pf2_configuration_new_from_options_hash(VALUE options_hash)
 
     config->interval_ms = extract_interval_ms(options_hash);
     config->time_mode = extract_time_mode(options_hash);
-    config->_test_no_install_timer = extract__test_no_install_timer(options_hash);
 
     return config;
 }
@@ -60,17 +57,6 @@ extract_time_mode(VALUE options_hash)
     }
 }
 
-static bool
-extract__test_no_install_timer(VALUE options_hash)
-{
-    if (options_hash == Qnil) {
-        return PF2_DEFAULT__TEST_NO_INSTALL_TIMER;
-    }
-
-    VALUE _test_no_install_timer = rb_hash_aref(options_hash, ID2SYM(rb_intern("_test_no_install_timer")));
-    return RTEST(_test_no_install_timer);
-}
-
 void
 pf2_configuration_free(struct pf2_configuration *config)
 {

data/ext/pf2/configuration.h

@@ -2,7 +2,6 @@
 #define PF2_CONFIGURATION_H
 
 #include <ruby.h>
-#include <stdbool.h>
 
 enum pf2_time_mode {
     PF2_TIME_MODE_CPU_TIME,
@@ -12,12 +11,10 @@ enum pf2_time_mode {
 struct pf2_configuration {
     int interval_ms;
     enum pf2_time_mode time_mode;
-    bool _test_no_install_timer; // for testing only
 };
 
 #define PF2_DEFAULT_INTERVAL_MS 9
 #define PF2_DEFAULT_TIME_MODE PF2_TIME_MODE_CPU_TIME
-#define PF2_DEFAULT__TEST_NO_INSTALL_TIMER false
 
 struct pf2_configuration *pf2_configuration_new_from_options_hash(VALUE options_hash);
 void pf2_configuration_free(struct pf2_configuration *config);

data/ext/pf2/extconf.rb

@@ -1,44 +1,10 @@
 require 'mkmf'
 require 'mini_portile2'
-require 'fileutils'
-require 'optparse'
-
-gem_root = File.expand_path(File.join(File.dirname(__FILE__), '..', '..'))
-
-options = {
-  debug: ENV['PF2_DEBUG'] == '1',
-}
-option_parser = OptionParser.new do |opts|
-  opts.on('--debug[=BOOL]') do |debug|
-    options[:debug] =
-      case debug
-      when nil, "true"
-        true
-      when "false"
-        false
-      else
-        raise OptionParser::InvalidArgument, "Expected true or false for --debug"
-      end
-  end
-end
-option_parser.parse!(ARGV)
 
 libbacktrace = MiniPortile.new('libbacktrace', '1.0.0')
-libbacktrace.source_directory = File.join(gem_root, 'vendor', 'libbacktrace')
-libbacktrace.patch_files = Dir.glob(File.join(gem_root, 'ext', 'patches', 'libbacktrace', '*.patch'))
+libbacktrace.source_directory = File.expand_path(File.join(File.dirname(__FILE__), '..', '..', 'vendor', 'libbacktrace'))
 libbacktrace.configure_options << 'CFLAGS=-fPIC'
-
-# Expand 'libbacktrace.cook' to call #patch on source_directory files
-libbacktrace.prepare_build_directory
-# Added: Copy source to build_directory
-build_directory = libbacktrace.send(:work_path)
-FileUtils.cp_r(File.join(libbacktrace.source_directory, '.'), build_directory)
-libbacktrace.patch
-libbacktrace.configure unless libbacktrace.configured?
-libbacktrace.compile
-libbacktrace.install unless libbacktrace.installed?
-# END expand 'libbacktrace.cook'
-
+libbacktrace.cook
 libbacktrace.mkmf_config
 
 if !have_func('backtrace_full', 'backtrace.h')
@@ -47,7 +13,7 @@ end
 
 append_ldflags('-lrt') # for timer_create
 append_cflags('-fvisibility=hidden')
-append_cflags('-DPF2_DEBUG') if options[:debug]
+append_cflags('-DPF2_DEBUG') if ENV['PF2_DEBUG'] == '1'
 
 # Check for timer functions
 have_timer_create = have_func('timer_create')

data/ext/pf2/pf2.c

@@ -2,16 +2,16 @@
 
 #include "session.h"
 
-VALUE rb_mPf2;
+VALUE rb_mPf2c;
 
 RUBY_FUNC_EXPORTED void
 Init_pf2(void)
 {
-    rb_mPf2 = rb_define_module("Pf2");
-    VALUE rb_mPf2_cSession = rb_define_class_under(rb_mPf2, "Session", rb_cObject);
-    rb_define_alloc_func(rb_mPf2_cSession, pf2_session_alloc);
-    rb_define_method(rb_mPf2_cSession, "initialize", rb_pf2_session_initialize, -1);
-    rb_define_method(rb_mPf2_cSession, "start", rb_pf2_session_start, 0);
-    rb_define_method(rb_mPf2_cSession, "stop", rb_pf2_session_stop, 0);
-    rb_define_method(rb_mPf2_cSession, "configuration", rb_pf2_session_configuration, 0);
+    rb_mPf2c = rb_define_module("Pf2c");
+    VALUE rb_mPf2c_cSession = rb_define_class_under(rb_mPf2c, "Session", rb_cObject);
+    rb_define_alloc_func(rb_mPf2c_cSession, pf2_session_alloc);
+    rb_define_method(rb_mPf2c_cSession, "initialize", rb_pf2_session_initialize, -1);
+    rb_define_method(rb_mPf2c_cSession, "start", rb_pf2_session_start, 0);
+    rb_define_method(rb_mPf2c_cSession, "stop", rb_pf2_session_stop, 0);
+    rb_define_method(rb_mPf2c_cSession, "configuration", rb_pf2_session_configuration, 0);
 }

data/ext/pf2/sample.c

@@ -9,6 +9,8 @@
 #include "backtrace_state.h"
 #include "sample.h"
 
+const int PF2_SAMPLE_MAX_NATIVE_DEPTH = 300;
+
 static int capture_native_backtrace(struct pf2_sample *sample);
 static int backtrace_on_ok(void *data, uintptr_t pc);
 
@@ -27,7 +29,7 @@ pf2_sample_capture(struct pf2_sample *sample)
     sample->context_pthread = pthread_self();
 
     // Obtain the current stack from Ruby
-    sample->depth = rb_profile_frames(0, PF2_SAMPLE_MAX_RUBY_DEPTH, sample->cmes, sample->linenos);
+    sample->depth = rb_profile_frames(0, 200, sample->cmes, sample->linenos);
 
     // Capture C-level backtrace
     sample->native_stack_depth = capture_native_backtrace(sample);

data/ext/pf2/sample.h

@@ -5,18 +5,17 @@
 
 #include <ruby.h>
 
-#define PF2_SAMPLE_MAX_RUBY_DEPTH 1024
-#define PF2_SAMPLE_MAX_NATIVE_DEPTH 512
+extern const int PF2_SAMPLE_MAX_NATIVE_DEPTH;
 
 struct pf2_sample {
     pthread_t context_pthread;
 
     int depth;
-    VALUE cmes[PF2_SAMPLE_MAX_RUBY_DEPTH];
-    int linenos[PF2_SAMPLE_MAX_RUBY_DEPTH];
+    VALUE cmes[200];
+    int linenos[200];
 
     size_t native_stack_depth;
-    uintptr_t native_stack[PF2_SAMPLE_MAX_NATIVE_DEPTH];
+    uintptr_t native_stack[200];
 
     uint64_t consumed_time_ns;
     uint64_t timestamp_ns;