fiber-profiler 0.5.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1d62567e3ffd2eb3e9fd7ff6ad432d1fdda2d5d23f73284fdc91b4407851bd98
-  data.tar.gz: d37839a3d1c08c12b4a0dadd808c46698678a7b8f646ead271a5defd5ffe4427
+  metadata.gz: 4eb8511c2bd355496fcb3461944f5fc7881795e7e44d13f4a59497689feaa838
+  data.tar.gz: 5146ceedbb0f9fc2230b5c3f50b1c0fac9ef2b424078ced732051b6e7e303431
 SHA512:
-  metadata.gz: e7a5b9dcbfd5c80c735dd36c2961e16c2cc97bc4f1a1496f612b36552fb03a7993c0da17d0fe81d2519d0760607c51a9c36573c4ceaa249cb4d201fa1154b92d
-  data.tar.gz: f1ff0b98c24d6c15736c3d15da1375f73f3c2fc6608d2669c554d6ae773ec8df7e21921599f314750bb99da8aeaa518f9607bc5982e8b81ce429b3acf308dd1a
+  metadata.gz: 427ddb031dc285d0c45c7c1dc72e0793c200b216ca3854272d675ad2cf677c58bf5a7a07bdaf043890f583527fe32ec263b0e12cf53ac11e95a90921e6576013
+  data.tar.gz: 625fe37c351399c0c1a5588f2577238899b2cad5b3b876d2e4fbe7c76ffdd26865c31111d68c09e04160a369cb0ca149e9c2eb97e1417dacdb7247a5a6b06861

data/bake/fiber/profiler/analyze.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2025, by Samuel Williams.
+
+# @parameter input [Input] The input to process.
+def analyze(input:)
+	summary = {}
+	
+	input.each do |sample|
+		duration = sample["duration"]
+		calls = sample["calls"]
+		
+		if duration and calls
+			calls.each do |call|
+				location = "#{call["path"]}:#{call["line"]}"
+				
+				summary[location] ||= {duration: 0, calls: 0, class: call["class"], method: call["method"]}
+				summary[location][:duration] += call["duration"]
+				summary[location][:calls] += 1
+			end
+		end
+	end
+	
+	summary.sort_by{|location, data| -data[:duration]}
+end

data/context/getting-started.md

@@ -0,0 +1,72 @@
+# Getting Started
+
+This guide explains how to detect stalls using the fiber profiler.
+
+## Installation
+
+Add the gem to your project:
+
+```bash
+$ bundle add fiber-profiler
+```
+
+## Usage
+
+Instrument your code using the default profiler:
+
+```ruby
+#!/usr/bin/env ruby
+
+require "fiber/profiler"
+
+profiler = Fiber::Profiler.default
+
+profiler&.start
+
+# Your application code:
+Fiber.new do
+	sleep 0.1
+end.resume
+
+profiler&.stop
+```
+
+Running this program will output the following:
+
+```bash
+$ FIBER_PROFILER_CAPTURE=true bundle exec ./test.rb
+Fiber stalled for 0.105 seconds
+/Users/samuel/Developer/socketry/fiber-profiler/test.rb:11 in c-call 'Kernel#sleep' (0.105s)
+```
+
+## Integration with Async
+
+The fiber profiler is optionally supported by `Async`. Simply enable the profiler using `FIBER_PROFILER_CAPTURE=true` to capture and report stalls.
+
+## Default Environment Variables
+
+### `FIBER_PROFILER_CAPTURE`
+
+Set to `true` to enable capturing of stalled fibers.
+
+### `FIBER_PROFILER_CAPTURE_STALL_THRESHOLD`
+
+Set the threshold in seconds for reporting a stalled fiber. Default is `0.01`.
+
+### `FIBER_PROFILER_CAPTURE_TRACK_CALLS`
+
+Set to `true` to track calls within the fiber. Default is `true`. This can be disabled to reduce overhead.
+
+### `FIBER_PROFILER_CAPTURE_SAMPLE_RATE`
+
+Set the sample rate of the profiler as a percentage of all context switches. The default is 1.0 (100%).
+
+## Analyzing Logs
+
+If you collect your logs in a file (e.g. as `ndjson`) you can analyze them using the included `bake` commands:
+
+```bash
+$ bundle exec bake input --file samples.ndjson fiber:profiler:analyze output
+```
+
+This will aggregate all the call logs and generate a short summary, ordered by duration.

data/context/index.yaml

@@ -0,0 +1,11 @@
+# Automatically generated context index for Utopia::Project guides.
+# Do not edit then files in this directory directly, instead edit the guides and then run `bake utopia:project:agent:context:update`.
+---
+description: A fiber stall profiler.
+metadata:
+  documentation_uri: https://socketry.github.io/fiber-profiler/
+  source_code_uri: https://github.com/socketry/fiber-profiler.git
+files:
+- path: getting-started.md
+  title: Getting Started
+  description: This guide explains how to detect stalls using the fiber profiler.

data/ext/fiber/profiler/capture.c

@@ -181,8 +181,6 @@ static void Fiber_Profiler_Capture_compact(void *ptr) {
 static void Fiber_Profiler_Capture_free(void *ptr) {
 	struct Fiber_Profiler_Capture *capture = (struct Fiber_Profiler_Capture*)ptr;
 	
-	RUBY_ASSERT(capture->running == 0);
-	
 	Fiber_Profiler_Stream_free(&capture->stream);
 	Fiber_Profiler_Deque_free(&capture->calls);
 	

data/lib/fiber/profiler/capture.rb

@@ -1,6 +1,44 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2025, by Samuel Williams.
+# Copyright, 2025-2026, by Samuel Williams.
 
 require_relative "native"
+require_relative "fork_handler"
+
+module Fiber::Profiler
+	# Thread-local storage for the active profiler capture.
+	::Thread.attr_accessor :fiber_profiler_capture
+	
+	# Private module that wraps start/stop to manage thread-local storage.
+	module ThreadLocalCapture
+		# Start profiling and store the capture in the current thread's thread-local storage.
+		def start
+			result = super
+			
+			if result
+				Thread.current.fiber_profiler_capture = self
+			end
+			
+			return result
+		end
+		
+		# Stop profiling and clear the capture from the current thread's thread-local storage.
+		def stop
+			result = super
+			
+			if result
+				Thread.current.fiber_profiler_capture = nil
+			end
+			
+			return result
+		end
+	end
+	
+	private_constant :ThreadLocalCapture
+	
+	# Represents a running profiler capture.
+	class Capture
+		prepend ThreadLocalCapture
+	end
+end

data/lib/fiber/profiler/fork_handler.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+module Fiber::Profiler
+	# Private module that hooks into Process._fork to handle fork events.
+	#
+	# If `Scheduler#process_fork` hook is adopted in Ruby 4, this code can be removed after Ruby < 4 is no longer supported.
+	module ForkHandler
+		def _fork(&block)
+			result = super
+			
+			if result.zero?
+				# Child process: disable the profiler for the current thread
+				if capture = Thread.current.fiber_profiler_capture
+					begin
+						capture.stop
+					rescue
+						# Ignore errors - the profiler may be in an invalid state after fork
+					end
+				end
+			end
+			
+			return result
+		end
+	end
+	
+	private_constant :ForkHandler
+	
+	# Hook into Process._fork to handle fork events automatically:
+	::Process.singleton_class.prepend(ForkHandler)
+end

data/lib/fiber/profiler/version.rb

@@ -7,6 +7,6 @@
 class Fiber
 	# @namespace
 	module Profiler
-		VERSION = "0.5.0"
+		VERSION = "0.6.0"
 	end
 end

data/lib/fiber/profiler.rb

@@ -1,10 +1,11 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2025, by Samuel Williams.
+# Copyright, 2025-2026, by Samuel Williams.
 
 require_relative "profiler/version"
 require_relative "profiler/native"
+require_relative "profiler/fork_handler"
 
 module Fiber::Profiler
 	# The default profiler to use, if any.

data/license.md

@@ -1,6 +1,6 @@
 # MIT License
 
-Copyright, 2025, by Samuel Williams.  
+Copyright, 2025-2026, by Samuel Williams.  
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/readme.md

@@ -18,6 +18,10 @@ Please see the [project documentation](https://socketry.github.io/fiber-profiler
 
 Please see the [project releases](https://socketry.github.io/fiber-profiler/releases/index) for all releases.
 
+### v0.6.0
+
+  - Fixed compatibility with `Process.fork`.
+
 ### v0.1.3
 
   - Improved performance when not profiling (when sampling is enabled).
@@ -36,6 +40,22 @@ We welcome contributions to this project.
 4.  Push to the branch (`git push origin my-new-feature`).
 5.  Create new Pull Request.
 
+### Running Tests
+
+To run the test suite:
+
+``` shell
+bundle exec sus
+```
+
+### Making Releases
+
+To make a new release:
+
+``` shell
+bundle exec bake gem:release:patch # or minor or major
+```
+
 ### Developer Certificate of Origin
 
 In order to protect users of this project, we require all contributors to comply with the [Developer Certificate of Origin](https://developercertificate.org/). This ensures that all contributions are properly licensed and attributed.

data/releases.md

@@ -1,5 +1,9 @@
 # Releases
 
+## v0.6.0
+
+  - Fixed compatibility with `Process.fork`.
+
 ## v0.1.3
 
   - Improved performance when not profiling (when sampling is enabled).

data.tar.gz.sig

@@ -1,2 +1,3 @@
-��
�I9?�8��3ŝy��m�ӗ<��T�qT0+Hʎ��
-���p�c�7q��[��{�CJ���cg�W4�=���M����E���T?l�V�"IZ���+���|��	̛���>y�u3�t>C���|9�9���n�]`�b������(���Z���=�“9�~l�9�������6%^�G0��y*�̺:�_ܐ���b�x�b���QP�Sf���>�@T,��o��0�b�;X�o?�#��	���IfO��^.��GI?��捰Eo�9p�Ԑ)9��ټ)�S�"�}�����:	sr��7���V]
+j��(��6���x��PU�@��� ǒ����t��h���1��x�e��:��Eaʩ̵�����at4�7�iB߆�ɬ�c���1��QsĹ��Y'ߘYg�r7=�-����0�z�ݐBL��#~��m�X�?����55�l�M�ڂE$��<(f���kX�H��`6ї(}��0��Q&<2_J�qV��3h���){���7�� �G�
+�
+o��

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: fiber-profiler
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.6.0
 platform: ruby
 authors:
 - Samuel Williams
@@ -43,6 +43,9 @@ extensions:
 - ext/extconf.rb
 extra_rdoc_files: []
 files:
+- bake/fiber/profiler/analyze.rb
+- context/getting-started.md
+- context/index.yaml
 - ext/extconf.rb
 - ext/fiber/profiler/capture.c
 - ext/fiber/profiler/capture.h
@@ -55,6 +58,7 @@ files:
 - ext/fiber/profiler/time.h
 - lib/fiber/profiler.rb
 - lib/fiber/profiler/capture.rb
+- lib/fiber/profiler/fork_handler.rb
 - lib/fiber/profiler/native.rb
 - lib/fiber/profiler/version.rb
 - license.md
@@ -73,14 +77,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '3.2'
+      version: '3.3'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.7
+rubygems_version: 4.0.6
 specification_version: 4
 summary: A fiber stall profiler.
 test_files: []