pf2 0.11.3 → 0.13.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 86fd284a999c583522ded7f75ac859162e5f125cf699f5a8eba8a3fac968874b
-  data.tar.gz: ae12d4bf742da3ede82a4e4c3229410ab8a06ef24b020e9d2232f923d64c2c70
+  metadata.gz: 84ea10eb9b861a910a1190ea017ad276ad593bc460c01687aabce8128392e35a
+  data.tar.gz: abd41b0b0ca74ebbcfeb1a202b75a4eec52f7c48b5b87e80d6e3052516304415
 SHA512:
-  metadata.gz: f0d7cc6bf5436ca522e00ec2eabe31a00030df584365b4a3cf5847d7b1d48d287304520e85884635373c025237562951e80e45e121250c72437e27db88687547
-  data.tar.gz: 19cb2e6fcb953134cde12e45dbc861129cd25c325ad3f44492e5808dbb7a10e2acb386e8d8d8041fe4a4a773bd9f8538989b1f9bbfd8bb6b4aedda3b4c4db8ea
+  metadata.gz: 7f17ba3e89269c97398559f97b87033a598e590b4c20efe341b76ce4841a47080a75c6324cce0881f83b6d68a336892ccd7ca593b953f5963097cf99b0a065ab
+  data.tar.gz: d09630c20fbddb0e5b072c20cf97ad0af0f541db7fa4265090427a0a64af0bf4b565923fe9e988438a623e060c902ba92243b75d6b0f257df57b11674d8d4d1b

data/CHANGELOG.md

@@ -1,5 +1,40 @@
 ## [Unreleased]
 
+## [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.

data/README.md

@@ -6,6 +6,7 @@ A experimental sampling-based profiler for Ruby 3.3+.
 - GitHub: https://github.com/osyoyu/pf2
 - Documentation: https://osyoyu.github.io/pf2/
 
+
 Notable Capabilites
 --------
 
@@ -96,10 +97,7 @@ 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.
+  time_mode: :cpu,       # `:cpu` or `:wall`: The sampling timer's mode
 )
 ```
 
@@ -130,36 +128,33 @@ 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.
 
-### Schedulers
+### Scheduling
 
-Schedulers determine when to execute sample collection, based on configuration (time mode and interval). Pf2 has two schedulers available.
+Schedulers determine when to execute sample collection, based on configuration (time mode and interval).
 
-#### SignalScheduler (Linux-only)
+#### Signal-based scheduling
 
-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.
+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.
 
-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.
+When the specified interval has arrived (the timer has _expired_), the OS delivers us a SIGPROF signal.
 
 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`).
 
-#### TimerThreadScheduler
+#### ~~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.
 
 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
@@ -172,3 +167,4 @@ 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

@@ -15,6 +15,7 @@ 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|

data/THIRD_PARTY_LICENSES.txt

@@ -0,0 +1,59 @@
+This project includes the following third-party software:
+
+## khashl
+
+    The MIT License
+
+    Copyright (c) 2019- by Attractive Chaos <attractor@live.co.uk>
+
+    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.
+
+## libbacktrace
+
+    Copyright (C) 2012-2016 Free Software Foundation, Inc.
+
+    Redistribution and use in source and binary forms, with or without
+    modification, are permitted provided that the following conditions are
+    met:
+
+        (1) Redistributions of source code must retain the above copyright
+        notice, this list of conditions and the following disclaimer. 
+
+        (2) Redistributions in binary form must reproduce the above copyright
+        notice, this list of conditions and the following disclaimer in
+        the documentation and/or other materials provided with the
+        distribution.  
+
+        (3) The name of the author may not be used to
+        endorse or promote products derived from this software without
+        specific prior written permission.
+
+    THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
+    IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+    WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+    DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT,
+    INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+    (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+    SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+    HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
+    STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
+    IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+    POSSIBILITY OF SUCH DAMAGE.

data/ext/patches/libbacktrace/0001-Support-MACH_O_MH_BUNDLE.patch

@@ -0,0 +1,32 @@
+From 4cd047583bc48ad0617fb6c036174de062573e68 Mon Sep 17 00:00:00 2001
+From: Daisuke Aritomo <osyoyu@osyoyu.com>
+Date: Wed, 7 Jan 2026 02:50:54 +0900
+Subject: [PATCH] Support MACH_O_MH_BUNDLE
+
+---
+ macho.c | 2 ++
+ 1 file changed, 2 insertions(+)
+
+diff --git a/macho.c b/macho.c
+index 9f8738d..5ea07ae 100644
+--- a/macho.c
++++ b/macho.c
+@@ -92,6 +92,7 @@ struct macho_header_fat
+ 
+ #define MACH_O_MH_EXECUTE	0x02
+ #define MACH_O_MH_DYLIB		0x06
++#define MACH_O_MH_BUNDLE	0x08
+ #define MACH_O_MH_DSYM		0x0a
+ 
+ /* A component of a fat file.  A fat file starts with a
+@@ -1062,6 +1063,7 @@ macho_add (struct backtrace_state *state, const char *filename, int descriptor,
+     {
+     case MACH_O_MH_EXECUTE:
+     case MACH_O_MH_DYLIB:
++    case MACH_O_MH_BUNDLE:
+     case MACH_O_MH_DSYM:
+       break;
+     default:
+-- 
+2.39.5 (Apple Git-154)
+

data/ext/pf2/configuration.c

@@ -1,10 +1,12 @@
 #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)
@@ -16,6 +18,7 @@ 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;
 }
@@ -57,6 +60,17 @@ 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,6 +2,7 @@
 #define PF2_CONFIGURATION_H
 
 #include <ruby.h>
+#include <stdbool.h>
 
 enum pf2_time_mode {
     PF2_TIME_MODE_CPU_TIME,
@@ -11,10 +12,12 @@ 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,10 +1,44 @@
 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.expand_path(File.join(File.dirname(__FILE__), '..', '..', 'vendor', 'libbacktrace'))
+libbacktrace.source_directory = File.join(gem_root, 'vendor', 'libbacktrace')
+libbacktrace.patch_files = Dir.glob(File.join(gem_root, 'ext', 'patches', 'libbacktrace', '*.patch'))
 libbacktrace.configure_options << 'CFLAGS=-fPIC'
-libbacktrace.cook
+
+# 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.mkmf_config
 
 if !have_func('backtrace_full', 'backtrace.h')
@@ -13,7 +47,7 @@ end
 
 append_ldflags('-lrt') # for timer_create
 append_cflags('-fvisibility=hidden')
-append_cflags('-DPF2_DEBUG') if ENV['PF2_DEBUG'] == '1'
+append_cflags('-DPF2_DEBUG') if options[:debug]
 
 # Check for timer functions
 have_timer_create = have_func('timer_create')