async-safe 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: e20fdea7f6f63f3a47aa8be85492fa2725e6b3ea2c0284de63dd6fe45af6f49c
+  data.tar.gz: 6556e3ed8f46cfe8157983229d4584a6b01eb0e8f2b36f83fe3ec5f541211830
+SHA512:
+  metadata.gz: 6a02637fc476e5e38a6b1952394ad99ca3fbe13b106b6d7ac0abbafc7f285167f3a0ef9302a28ac0e12f29a70edce7158ea2690b88d309e99a5d1f073da58580
+  data.tar.gz: 24fbc11d3be799f80649e1a487edc6f1b4040fbb0e4688d590f2caafceb76b761c298569a3b2384939844753eec8b788ff0bf70d8f820b3fbe4c9d9403183542

data/context/getting-started.md

@@ -0,0 +1,176 @@
+# Getting Started
+
+This guide explains how to use `async-safe` to detect thread safety violations in your Ruby code.
+
+## Installation
+
+Add the gem to your project:
+
+~~~ bash
+$ bundle add async-safe
+~~~
+
+## Usage
+
+Enable monitoring in your test suite or development environment:
+
+~~~ ruby
+require 'async/safe'
+
+# Enable monitoring
+Async::Safe.enable!
+
+# Your concurrent code here...
+~~~
+
+When a violation is detected, an `Async::Safe::ViolationError` will be raised immediately with details about the object, method, and execution contexts involved.
+
+## Single-Owner Model
+
+By default, all objects are assumed to follow a **single-owner model** - they should only be accessed from one fiber/thread at a time:
+
+~~~ ruby
+class MyBody
+  def initialize(chunks)
+    @chunks = chunks
+    @index = 0
+  end
+  
+  def read
+    chunk = @chunks[@index]
+    @index += 1
+    chunk
+  end
+end
+
+body = MyBody.new(["a", "b", "c"])
+body.read  # OK - accessed from main fiber
+
+Fiber.schedule do
+  body.read  # 💥 Raises Async::Safe::ViolationError!
+end
+~~~
+
+## Marking Async-Safe Classes
+
+Mark entire classes as safe for concurrent access:
+
+~~~ ruby
+class MyQueue
+  async_safe!
+  
+  def initialize
+    @queue = Thread::Queue.new
+  end
+  
+  def push(item)
+    @queue.push(item)
+  end
+  
+  def pop
+    @queue.pop
+  end
+end
+
+queue = MyQueue.new
+queue.push("item")
+
+Fiber.schedule do
+  queue.push("another")  # ✅ OK - class is marked async-safe
+end
+~~~
+
+Alternatively, you can manually set the constant:
+
+~~~ ruby
+class MyQueue
+  ASYNC_SAFE = true
+  
+  # ... implementation
+end
+~~~
+
+## Marking Async-Safe Methods
+
+Mark specific methods as async-safe:
+
+~~~ ruby
+class MixedSafety
+  include Async::Safe
+  
+  async_safe :safe_read
+  
+  def initialize(data)
+    @data = data
+    @count = 0
+  end
+  
+  def safe_read
+    @data  # Async-safe method
+  end
+  
+  def increment
+    @count += 1  # Not async-safe
+  end
+end
+
+obj = MixedSafety.new("data")
+
+Fiber.schedule do
+  obj.safe_read  # ✅ OK - method is marked async-safe
+  obj.increment  # 💥 Raises Async::Safe::ViolationError!
+end
+~~~
+
+## Transferring Ownership
+
+Explicitly transfer ownership between fibers:
+
+~~~ ruby
+request = create_request
+process_in_main_fiber(request)
+
+Fiber.schedule do
+  Async::Safe.transfer(request)  # Transfer ownership
+  process_in_worker_fiber(request)  # ✅ OK now
+end
+~~~
+
+## Integration with Tests
+
+Add to your test helper (e.g., `config/sus.rb` or `spec/spec_helper.rb`):
+
+~~~ ruby
+require 'async/safe'
+
+Async::Safe.enable!
+~~~
+
+Then run your tests normally:
+
+~~~ bash
+$ bundle exec sus
+~~~
+
+Any thread safety violations will cause your tests to fail immediately with a clear error message showing which object was accessed incorrectly and from which fibers.
+
+## How It Works
+
+1. **Default Assumption**: All objects follow a single-owner model (not thread-safe).
+2. **TracePoint Monitoring**: Tracks which fiber/thread first accesses each object.
+3. **Violation Detection**: Raises an exception when a different fiber/thread accesses the same object.
+4. **Explicit Safety**: Objects/methods can be marked as thread-safe to allow concurrent access.
+5. **Zero Overhead**: Monitoring is only active when explicitly enabled.
+
+## Use Cases
+
+- **Detecting concurrency bugs** in development and testing.
+- **Validating thread safety assumptions** in async/fiber-based code.
+- **Finding race conditions** before they cause production issues.
+- **Educational tool** for learning about thread safety in Ruby.
+
+## Performance
+
+- **Zero overhead when disabled** - TracePoint is not activated.
+- **Minimal overhead when enabled** - suitable for development/test environments.
+- **Not recommended for production** - use only in development/testing.

data/context/index.yaml

@@ -0,0 +1,12 @@
+# 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: Runtime thread safety monitoring for concurrent Ruby code.
+metadata:
+  documentation_uri: https://socketry.github.io/async-safe/
+  source_code_uri: https://github.com/socketry/async-safe
+files:
+- path: getting-started.md
+  title: Getting Started
+  description: This guide explains how to use `async-safe` to detect thread safety
+    violations in your Ruby code.

data/lib/async/safe/builtins.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2025, by Samuel Williams.
+
+# Mark Ruby's built-in thread-safe classes as async-safe
+#
+# Note: Immutable values (nil, true, false, integers, symbols, etc.) are already
+# handled by the frozen? check in the monitor and don't need to be listed here.
+
+# Thread synchronization primitives:
+Thread::ASYNC_SAFE = true
+Thread::Queue::ASYNC_SAFE = true
+Thread::SizedQueue::ASYNC_SAFE = true
+Thread::Mutex::ASYNC_SAFE = true
+Thread::ConditionVariable::ASYNC_SAFE = true
+
+# Fibers are async-safe:
+Fiber::ASYNC_SAFE = true
+
+# ObjectSpace::WeakMap is async-safe:
+ObjectSpace::WeakMap::ASYNC_SAFE = true

data/lib/async/safe/class.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2025, by Samuel Williams.
+
+# Extend Class with a default async_safe? implementation
+class Class
+	# Check if this class or a specific method is async-safe.
+	#
+	# @parameter method [Symbol | Nil] The method name to check, or nil to check if the entire class is async-safe.
+	# @returns [Boolean] Whether the class or method is async-safe.
+	def async_safe?(method = nil)
+		# Check if entire class is marked async-safe via constant:
+		if const_defined?(:ASYNC_SAFE, false) && const_get(:ASYNC_SAFE)
+			return true
+		end
+		
+		false
+	end
+	
+	# Mark the class as async-safe or not.
+	#
+	# @parameter value [Boolean] Whether the class is async-safe.
+	# @returns [Boolean] Whether the class is async-safe.
+	def async_safe!(value = true)
+		self.const_set(:ASYNC_SAFE, value)
+	end
+end

data/lib/async/safe/monitor.rb

@@ -0,0 +1,147 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2025, by Samuel Williams.
+
+require "set"
+require "weakref"
+
+module Async
+	module Safe
+		# Raised when an object is accessed from a different fiber than the one that owns it.
+		class ViolationError < StandardError
+			# Initialize a new violation error.
+			#
+			# @parameter message [String | Nil] Optional custom message.
+			# @parameter target [Object] The object that was accessed.
+			# @parameter method [Symbol] The method that was called.
+			# @parameter owner [Fiber] The fiber that owns the object.
+			# @parameter current [Fiber] The fiber that attempted to access the object.
+			def initialize(message = nil, target:, method:, owner:, current:)
+				@target = target
+				@method = method
+				@owner = owner
+				@current = current
+				
+				super(message || build_message)
+			end
+			
+			attr_reader :object_class, :method, :owner, :current
+			
+			# Convert the violation error to a JSON-serializable hash.
+			#
+			# @returns [Hash] A hash representation of the violation.
+			def as_json
+				{
+					object_class: @object_class,
+					method: @method,
+					owner: {
+						name: @owner.inspect,
+						backtrace: @owner.backtrace,
+					},
+					current: {
+						name: @current.inspect,
+						backtrace: @current.backtrace,
+					},
+				}
+			end
+			
+			private def build_message
+				"Thread safety violation detected! #{@target.inspect}##{@method} was accessed from #{@current.inspect} by #{@owner.inspect}."
+			end
+		end
+		
+		# The core monitoring implementation using TracePoint.
+		#
+		# This class tracks object ownership across fibers, detecting when an object
+		# is accessed from a different fiber than the one that originally created or
+		# accessed it.
+		#
+		# The monitor uses a TracePoint on `:call` events to track all method calls,
+		# and maintains a registry of which fiber "owns" each object. Uses weak references
+		# to avoid preventing garbage collection of tracked objects.
+		class Monitor
+			ASYNC_SAFE = true
+			
+			# Initialize a new monitor instance.
+			def initialize
+				@owners = ObjectSpace::WeakMap.new
+				@mutex = Thread::Mutex.new
+				@trace_point = nil
+			end
+			
+			attr :owners
+			
+			# Enable the monitor by activating the TracePoint.
+			def enable!
+				@trace_point ||= TracePoint.trace(:call, &method(:check_access))
+			end
+			
+			# Disable the monitor by deactivating the TracePoint.
+			def disable!
+				if trace_point = @trace_point
+					@trace_point = nil
+					trace_point.disable
+				end
+			end
+			
+			# Explicitly transfer ownership of objects to the current fiber.
+			#
+			# @parameter objects [Array(Object)] The objects to transfer.
+			def transfer(*objects)
+				@mutex.synchronize do
+					current = Fiber.current
+					
+					objects.each do |object|
+						@owners[object] = current
+					end
+				end
+			end
+			
+			# Check if the current access is allowed or constitutes a violation.
+			#
+			# @parameter trace_point [TracePoint] The trace point containing access information.
+			def check_access(trace_point)
+				object = trace_point.self
+				
+				# Skip tracking class/module methods:
+				return if object.is_a?(Class) || object.is_a?(Module)
+				
+				# Skip frozen objects:
+				return if object.frozen?
+				
+				method = trace_point.method_id
+				klass = trace_point.defined_class
+				
+				# Check the object's actual class:
+				klass = object.class
+				
+				# Check if the class or method is marked as async-safe:
+				if klass.async_safe?(method)
+					return
+				end
+				
+				# Track ownership:
+				current = Fiber.current
+				
+				@mutex.synchronize do
+					if owner = @owners[object]
+						# Violation if accessed from different fiber:
+						if owner != current
+							raise ViolationError.new(
+								target: object,
+								method: method,
+								owner: owner,
+								current: current,
+							)
+						end
+					else
+						# First access - record owner:
+						@owners[object] = current
+					end
+				end
+			end
+		end
+	end
+end
+

data/lib/async/safe/version.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2025, by Samuel Williams.
+
+module Async
+	module Safe
+		VERSION = "0.1.0"
+	end
+end
+

data/lib/async/safe.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2025, by Samuel Williams.
+
+require_relative "safe/version"
+require_relative "safe/class"
+require_relative "safe/monitor"
+require_relative "safe/builtins"
+
+# @namespace
+module Async
+	# Provides runtime thread safety monitoring for concurrent Ruby code.
+	#
+	# By default, all objects follow a **single-owner model** - they should only be accessed
+	# from one fiber/thread at a time. Objects or methods can be explicitly marked as
+	# async-safe to allow concurrent access.
+	#
+	# Enable monitoring in your test suite to catch concurrency bugs early.
+	module Safe
+		# Include this module to mark specific methods as async-safe
+		def self.included(base)
+			base.extend(ClassMethods)
+		end
+		
+		# Class methods for marking async-safe methods
+		module ClassMethods
+			# Mark one or more methods as async-safe.
+			#
+			# @parameter method_names [Array(Symbol)] The methods to mark as async-safe.
+			def async_safe(*method_names)
+				@async_safe_methods ||= Set.new
+				@async_safe_methods.merge(method_names)
+			end
+			
+			# Check if a method is async-safe.
+			#
+			# Overrides the default implementation from `Class` to also check method-level safety.
+			#
+			# @parameter method [Symbol | Nil] The method name to check, or nil to check if the entire class is async-safe.
+			# @returns [Boolean] Whether the method or class is async-safe.
+			def async_safe?(method = nil)
+				# Check if entire class is marked async-safe:
+				return true if super
+				
+				# Check if specific method is marked async-safe:
+				if method
+					return @async_safe_methods&.include?(method)
+				end
+				
+				# Default to false if no method is specified and the class is not async safe:
+				return false
+			end
+		end
+		
+		class << self
+			# @attribute [Monitor] The global monitoring instance.
+			attr_reader :monitor
+			
+			# Enable thread safety monitoring.
+			#
+			# This activates a TracePoint that tracks object access across fibers and threads.
+			# There is no performance overhead when monitoring is disabled.
+			def enable!
+				@monitor ||= Monitor.new
+				@monitor.enable!
+			end
+			
+			# Disable thread safety monitoring.
+			def disable!
+				@monitor&.disable!
+				@monitor = nil
+			end
+			
+			# Explicitly transfer ownership of objects to the current fiber.
+			#
+			# This allows an object to be safely passed between fibers.
+			#
+			# @parameter objects [Array(Object)] The objects to transfer ownership of.
+			#
+			# ~~~ ruby
+			# request = Request.new(...)
+			# 
+			# Fiber.schedule do
+			# 	# Transfer ownership of the request to this fiber:
+			# 	Async::Safe.transfer(request)
+			# 	process(request)
+			# end
+			# ~~~
+			def transfer(*objects)
+				@monitor&.transfer(*objects)
+			end
+		end
+	end
+end
+

data/license.md

@@ -0,0 +1,21 @@
+# MIT License
+
+Copyright, 2025, 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
+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,55 @@
+# Async::Safe
+
+Runtime thread safety monitoring for concurrent Ruby code.
+
+This gem provides a TracePoint-based ownership tracking system that detects when objects are accessed from multiple fibers or threads without proper synchronization. It helps catch concurrency bugs during development and testing with zero overhead in production.
+
+[![Development Status](https://github.com/socketry/async-safe/workflows/Test/badge.svg)](https://github.com/socketry/async-safe/actions?workflow=Test)
+
+## Motivation
+
+Ruby's fiber-based concurrency (via `async`) requires careful attention to object ownership. This gem helps you catch violations of the single-owner model in your test suite, preventing concurrency bugs from reaching production.
+
+Enable it in your tests to get immediate feedback when objects are incorrectly shared across fibers.
+
+## Usage
+
+Please see the [project documentation](https://socketry.github.io/async-safe/) for more details.
+
+  - [Getting Started](https://socketry.github.io/async-safe/guides/getting-started/index) - This guide explains how to use `async-safe` to detect thread safety violations in your Ruby code.
+
+## Releases
+
+Please see the [project releases](https://socketry.github.io/async-safe/releases/index) for all releases.
+
+### v0.1.0
+
+  - Implement TracePoint-based ownership tracking.
+  - Add `Async::Safe::Concurrent` module for marking thread-safe classes.
+  - Add `thread_safe` class method for marking thread-safe methods.
+  - Add `Async::Safe.transfer` for explicit ownership transfer
+  - Add violation detection and reporting
+  - Zero overhead when monitoring is disabled
+
+## See Also
+
+  - [async](https://github.com/socketry/async) - Composable asynchronous I/O for Ruby.
+  - [Thread Safety Guide](https://github.com/socketry/async/blob/main/.context/async/thread-safety.md) - Best practices for concurrent Ruby code.
+
+## Contributing
+
+We welcome contributions to this project.
+
+1.  Fork it.
+2.  Create your feature branch (`git checkout -b my-new-feature`).
+3.  Commit your changes (`git commit -am 'Add some feature'`).
+4.  Push to the branch (`git push origin my-new-feature`).
+5.  Create new Pull Request.
+
+### 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.
+
+### Community Guidelines
+
+This project is best served by a collaborative and respectful environment. Treat each other professionally, respect differing viewpoints, and engage constructively. Harassment, discrimination, or harmful behavior is not tolerated. Communicate clearly, listen actively, and support one another. If any issues arise, please inform the project maintainers.

data/releases.md

@@ -0,0 +1,10 @@
+# Releases
+
+## v0.1.0
+
+  - Implement TracePoint-based ownership tracking.
+  - Add `Async::Safe::Concurrent` module for marking thread-safe classes.
+  - Add `thread_safe` class method for marking thread-safe methods.
+  - Add `Async::Safe.transfer` for explicit ownership transfer
+  - Add violation detection and reporting
+  - Zero overhead when monitoring is disabled

metadata

@@ -0,0 +1,78 @@
+--- !ruby/object:Gem::Specification
+name: async-safe
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Samuel Williams
+bindir: bin
+cert_chain:
+- |
+  -----BEGIN CERTIFICATE-----
+  MIIE2DCCA0CgAwIBAgIBATANBgkqhkiG9w0BAQsFADBhMRgwFgYDVQQDDA9zYW11
+  ZWwud2lsbGlhbXMxHTAbBgoJkiaJk/IsZAEZFg1vcmlvbnRyYW5zZmVyMRIwEAYK
+  CZImiZPyLGQBGRYCY28xEjAQBgoJkiaJk/IsZAEZFgJuejAeFw0yMjA4MDYwNDUz
+  MjRaFw0zMjA4MDMwNDUzMjRaMGExGDAWBgNVBAMMD3NhbXVlbC53aWxsaWFtczEd
+  MBsGCgmSJomT8ixkARkWDW9yaW9udHJhbnNmZXIxEjAQBgoJkiaJk/IsZAEZFgJj
+  bzESMBAGCgmSJomT8ixkARkWAm56MIIBojANBgkqhkiG9w0BAQEFAAOCAY8AMIIB
+  igKCAYEAomvSopQXQ24+9DBB6I6jxRI2auu3VVb4nOjmmHq7XWM4u3HL+pni63X2
+  9qZdoq9xt7H+RPbwL28LDpDNflYQXoOhoVhQ37Pjn9YDjl8/4/9xa9+NUpl9XDIW
+  sGkaOY0eqsQm1pEWkHJr3zn/fxoKPZPfaJOglovdxf7dgsHz67Xgd/ka+Wo1YqoE
+  e5AUKRwUuvaUaumAKgPH+4E4oiLXI4T1Ff5Q7xxv6yXvHuYtlMHhYfgNn8iiW8WN
+  XibYXPNP7NtieSQqwR/xM6IRSoyXKuS+ZNGDPUUGk8RoiV/xvVN4LrVm9upSc0ss
+  RZ6qwOQmXCo/lLcDUxJAgG95cPw//sI00tZan75VgsGzSWAOdjQpFM0l4dxvKwHn
+  tUeT3ZsAgt0JnGqNm2Bkz81kG4A2hSyFZTFA8vZGhp+hz+8Q573tAR89y9YJBdYM
+  zp0FM4zwMNEUwgfRzv1tEVVUEXmoFCyhzonUUw4nE4CFu/sE3ffhjKcXcY//qiSW
+  xm4erY3XAgMBAAGjgZowgZcwCQYDVR0TBAIwADALBgNVHQ8EBAMCBLAwHQYDVR0O
+  BBYEFO9t7XWuFf2SKLmuijgqR4sGDlRsMC4GA1UdEQQnMCWBI3NhbXVlbC53aWxs
+  aWFtc0BvcmlvbnRyYW5zZmVyLmNvLm56MC4GA1UdEgQnMCWBI3NhbXVlbC53aWxs
+  aWFtc0BvcmlvbnRyYW5zZmVyLmNvLm56MA0GCSqGSIb3DQEBCwUAA4IBgQB5sxkE
+  cBsSYwK6fYpM+hA5B5yZY2+L0Z+27jF1pWGgbhPH8/FjjBLVn+VFok3CDpRqwXCl
+  xCO40JEkKdznNy2avOMra6PFiQyOE74kCtv7P+Fdc+FhgqI5lMon6tt9rNeXmnW/
+  c1NaMRdxy999hmRGzUSFjozcCwxpy/LwabxtdXwXgSay4mQ32EDjqR1TixS1+smp
+  8C/NCWgpIfzpHGJsjvmH2wAfKtTTqB9CVKLCWEnCHyCaRVuKkrKjqhYCdmMBqCws
+  JkxfQWC+jBVeG9ZtPhQgZpfhvh+6hMhraUYRQ6XGyvBqEUe+yo6DKIT3MtGE2+CP
+  eX9i9ZWBydWb8/rvmwmX2kkcBbX0hZS1rcR593hGc61JR6lvkGYQ2MYskBveyaxt
+  Q2K9NVun/S785AP05vKkXZEFYxqG6EW012U4oLcFl5MySFajYXRYbuUpH6AY+HP8
+  voD0MPg1DssDLKwXyt1eKD/+Fq0bFWhwVM/1XiAXL7lyYUyOq24KHgQ2Csg=
+  -----END CERTIFICATE-----
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- context/getting-started.md
+- context/index.yaml
+- lib/async/safe.rb
+- lib/async/safe/builtins.rb
+- lib/async/safe/class.rb
+- lib/async/safe/monitor.rb
+- lib/async/safe/version.rb
+- license.md
+- readme.md
+- releases.md
+homepage: https://github.com/socketry/async-safe
+licenses:
+- MIT
+metadata:
+  documentation_uri: https://socketry.github.io/async-safe/
+  source_code_uri: https://github.com/socketry/async-safe
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Runtime thread safety monitoring for concurrent Ruby code.
+test_files: []