pf2 0.12.0 → 0.14.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ef67bdd8a362c1f5cd3dd37a47e13b64f5ee0663a204908d0f075d41acc94da3
-  data.tar.gz: 535d1fe8efb9a408ce47218910d6ad3ddfe88c2a4e4f42ac42c01ab8dceceacd
+  metadata.gz: 117782be2a4d708cf477b5efb4cdf6cb7fbd7f58ef416d62b780c9d9ff4c7f16
+  data.tar.gz: 554efc38d2a316a84a9cd727afd9dac32815af50bc164409237bbb0fe38a9de9
 SHA512:
-  metadata.gz: 15a65711f8c1a804b06d8b2195a9e620646972b7905a714fdab67561f9d796d7c92a1f332f9169ffa27c14b6b91d9f33ba254d84d47c281f66f7a069cc660d58
-  data.tar.gz: 411bdf85ef4db94bed73840224132498621f389e4f6092a45e222bf5834dd5d1e6aa6940cafcb56cdc86148163d1b9bda4eee45501cc9c307ce729894954613d
+  metadata.gz: 48601b3a739539cd028d3d72cbbb2b2838c2c3ca285a438b65be8fb3e14b6a7f4b1d67438f0f15f855d7d28a5d9dc815874a69d0acafc05d524adfb1ca87d1e4
+  data.tar.gz: 11759b313c52670f56f1fb05ed09565806049526aa649d740479d4363e636506a5eb745dcd9ddfaba6ea245dfd2b6547370bfe56df5b6166a740850ae36fa621

data/.rdoc_options

@@ -2,5 +2,8 @@ title: Pf2
 main_page: README.md
 encoding: UTF-8
 
+exclude:
+  - ext/patches
+
 autolink_excluded_words:
   - Pf2

data/CHANGELOG.md

@@ -1,5 +1,35 @@
 ## [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

data/README.md

@@ -6,8 +6,6 @@ A experimental sampling-based profiler for Ruby 3.3+.
 - GitHub: https://github.com/osyoyu/pf2
 - Documentation: https://osyoyu.github.io/pf2/
 
-NOTE: This README contains some outdated information!
-
 Notable Capabilites
 --------
 
@@ -37,7 +35,29 @@ Pf2 can be installed as a standalone CLI tool as well.
 gem install pf2
 ```
 
-### Quickstart
+### 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'
 
 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.
@@ -50,39 +70,32 @@ $ pf2 serve -- ruby target.rb
 I'm the target program!
 ```
 
-### Profiling
+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.
 
-Pf2 will collect samples every 10 ms of wall time by default.
+### More precise control
+
+More precise control may be acheived by using `Pf2.start` and `Pf2.stop`.
 
 ```ruby
-# Threads in `threads` will be tracked
-Pf2.start(threads: [Thread.current])
+Pf2.start
 
 your_code_here
 
-# Stop profiling and save the profile for visualization
+# Stop profiling
 profile = Pf2.stop
-File.write("my_program.pf2profile", profile)
-```
-
-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)
+# Save file for later visualization using 'pf2 report'
+File.binwrite("my_program.pf2prof", Marshal.dump(profile))
 ```
 
+`Pf2.start` accepts `interval_ms` and `time_mode`.
+
 ### Reporting / Visualization
 
 Profiles can be visualized using the [Firefox Profiler](https://profiler.firefox.com/).
 
 ```console
-$ pf2 report -o report.json my_program.pf2profile
+$ pf2 report -o report.json my_program.pf2prof
 ```
 
 Alternatively, `pf2 annotate` can be used to display hit counts side-by-side with source code.
@@ -91,25 +104,10 @@ 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 still is incured.
+While Pf2 aims to be non-disturbulent as much as possible, a small overhead is still incured.
 
 (TBD)
 
@@ -132,45 +130,35 @@ 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
 --------
 
 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/THIRD_PARTY_LICENSES.txt

@@ -0,0 +1,75 @@
+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.
+
+## profile.proto
+
+    Copyright 2016 Google Inc. All Rights Reserved.
+
+    Licensed under the Apache License, Version 2.0 (the "License");
+    you may not use this file except in compliance with the License.
+    You may obtain a copy of the License at
+
+        http://www.apache.org/licenses/LICENSE-2.0
+
+    Unless required by applicable law or agreed to in writing, software
+    distributed under the License is distributed on an "AS IS" BASIS,
+    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+    See the License for the specific language governing permissions and
+    limitations under the License.

data/doc/development.md

@@ -15,3 +15,9 @@ 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/extconf.rb

@@ -1,9 +1,28 @@
 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'))
@@ -28,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')