async-safe 0.4.1 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 72500ee1207a863df7f749896936bf9edce7e06f2f7d7a519329c0ada72951eb
-  data.tar.gz: 584c0393294503ea01cf1e1858f88f3c2faf5e2cd6fdf1b2f632af0708e4d787
+  metadata.gz: a159f426b967f880b5935565fde44767b006695b75475e097f3e8d2e7239f8fe
+  data.tar.gz: a3549d80e371d6b42e6bacd9f6aa64f09479e8432e0648b8aa4b2a93c5e25f45
 SHA512:
-  metadata.gz: 305ea4886f6b9fa0452de045244623806ed824ba24791ed0d2d1e6bf96a14f536f31fccbd54f099e5cc10ee1dc39067609be9b646daac413c47126a86f0306a2
-  data.tar.gz: 78dd7ab4aab4893c2824788e03522905698d6f400557976677253fbcc53643b4a0dbaaa8a8157249415f9380a317ffddc126948bb484fa2b6c795513abf4fc2d
+  metadata.gz: 8b514ecda9b54080477fe913b9facaeba091523ba6d72dc2aa3a186c1c01fff74595057f64947fff3fcb570804166d273009518d3275861373cd5ccea21edc67
+  data.tar.gz: 4fe5eabb41e14c091176b1b30ee600db76143158db5a18bfa4b995d8e3a071b8d84e7857cb84a3443d70864cf36accc57ba514c857948fc18c9699bea88e443d

data/context/getting-started.md

@@ -25,31 +25,103 @@ Async::Safe.enable!
 
 When a violation is detected, an `Async::Safe::ViolationError` will be raised immediately with details about the object, method, and execution contexts involved.
 
+## Concurrent Access Detection
+
+`async-safe` detects **concurrent access** (data races) to objects across fibers. Objects can move freely between fibers - violations are only raised when two fibers try to access the same object simultaneously.
+
+~~~ ruby
+Async::Safe.enable!
+
+request = Request.new("http://example.com")
+request.process  # Main fiber
+
+Fiber.new do
+	# No problem - sequential access is allowed
+	request.process  # ✅ OK
+end.resume
+~~~
+
+However, actual concurrent access is detected:
+
+~~~ ruby
+require 'async'
+
+counter = Counter.new
+counter.increment
+
+Async do |task|
+	task.async do
+		counter.increment  # Fiber A accessing
+		sleep 0.1  # ... method is still running
+	end
+	
+	task.async do
+		sleep 0.05  # Wait for Fiber A to start
+		counter.increment  # 💥 Concurrent access detected!
+	end
+end
+~~~
+
+This approach focuses on catching **actual bugs** (data races) while allowing objects to move naturally between fibers.
+
+### Guard-Based Concurrency
+
+For objects with multiple independent operation types (like streams with separate read/write operations), `async_safe?` can return different guard symbols for different operations:
+
+~~~ ruby
+class Stream
+	def self.async_safe?(method)
+		case method
+		when :read then :readable
+		when :write then :writable
+		else false
+		end
+	end
+	
+	def read; end
+	def write(data); end
+end
+~~~
+
+This allows:
+- ✅ Concurrent `read` and `write` (different guards: `:readable` and `:writable`)
+- ❌ Concurrent `read` and `read` (same `:readable` guard)
+- ❌ Concurrent `write` and `write` (same `:writable` guard)
+
+Each guard can only be held by one fiber at a time, but different guards can be held concurrently.
+
 ### Single-Owner Model
 
 By default, all classes are assumed to be async-safe. To enable tracking for specific classes, mark them with `ASYNC_SAFE = false`:
 
 ~~~ ruby
 class MyBody
-  ASYNC_SAFE = false  # Enable tracking for this class
-  
-  def initialize(chunks)
-    @chunks = chunks
-    @index = 0
-  end
-  
-  def read
-    chunk = @chunks[@index]
-    @index += 1
-    chunk
-  end
+	ASYNC_SAFE = false  # Enable tracking for this class
+	
+	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
+body.read  # Main fiber
 
 Fiber.schedule do
-  body.read  # 💥 Raises Async::Safe::ViolationError!
+	body.read  # ✅ OK - sequential access is allowed
+end
+
+# But concurrent access is detected:
+require 'async'
+Async do |task|
+	task.async { body.read }  # Two fibers accessing
+	task.async { body.read }  # at the same time → ViolationError!
 end
 ~~~
 
@@ -59,26 +131,26 @@ 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
+	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
+	queue.push("another")  # ✅ OK - class is marked async-safe
 end
 ~~~
 
@@ -86,9 +158,9 @@ Alternatively, you can manually set the constant:
 
 ~~~ ruby
 class MyQueue
-  ASYNC_SAFE = true
-  
-  # ... implementation
+	ASYNC_SAFE = true
+	
+	# ... implementation
 end
 ~~~
 
@@ -96,12 +168,12 @@ Or use a hash for per-method configuration:
 
 ~~~ ruby
 class MixedClass
-  ASYNC_SAFE = {
-    read: true,    # This method is async-safe
-    write: false   # This method is NOT async-safe
-  }.freeze
-  
-  # ... implementation
+	ASYNC_SAFE = {
+		read: true,    # This method is async-safe
+		write: false   # This method is NOT async-safe
+	}.freeze
+	
+	# ... implementation
 end
 ~~~
 
@@ -111,30 +183,30 @@ Use a hash to specify which methods are async-safe:
 
 ~~~ ruby
 class MixedSafety
-  ASYNC_SAFE = {
-    safe_read: true,   # This method is async-safe
-    increment: false   # This method is NOT async-safe
-  }.freeze
-  
-  def initialize(data)
-    @data = data
-    @count = 0
-  end
-  
-  def safe_read
-    @data  # Async-safe method
-  end
-  
-  def increment
-    @count += 1  # Not async-safe - will be tracked
-  end
+	ASYNC_SAFE = {
+		safe_read: true,   # This method is async-safe
+		increment: false   # This method is NOT async-safe
+	}.freeze
+	
+	def initialize(data)
+		@data = data
+		@count = 0
+	end
+	
+	def safe_read
+		@data  # Async-safe method
+	end
+	
+	def increment
+		@count += 1  # Not async-safe - will be tracked
+	end
 end
 
 obj = MixedSafety.new("data")
 
 Fiber.schedule do
-  obj.safe_read  # ✅ OK - method is marked async-safe
-  obj.increment  # 💥 Raises Async::Safe::ViolationError!
+	obj.safe_read  # ✅ OK - method is marked async-safe
+	obj.increment  # 💥 Raises Async::Safe::ViolationError!
 end
 ~~~
 
@@ -142,58 +214,13 @@ Or use an array to list async-safe methods:
 
 ~~~ ruby
 class MyClass
-  ASYNC_SAFE = [:read, :inspect].freeze
-  
-  # read and inspect are async-safe
-  # all other methods will be tracked
+	ASYNC_SAFE = [:read, :inspect].freeze
+	
+	# read and inspect are async-safe
+	# all other methods will be tracked
 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
-~~~
-
-### Deep Transfer with Traversal
-
-By default, `transfer` only transfers the object itself (shallow). For collections like `Array`, `Hash`, and `Set`, the gem automatically traverses and transfers contained objects:
-
-~~~ ruby
-bodies = [Body.new, Body.new]
-
-Async::Safe.transfer(bodies)  # Transfers array AND all bodies inside
-~~~
-
-Custom classes can define traversal behavior using `async_safe_traverse`:
-
-~~~ ruby
-class Request
-  async_safe!(false)
-  attr_accessor :body, :headers
-  
-  def self.async_safe_traverse(instance, &block)
-    yield instance.body
-    yield instance.headers
-  end
-end
-
-request = Request.new
-request.body = Body.new
-request.headers = Headers.new
-
-Async::Safe.transfer(request)  # Transfers request, body, AND headers.
-~~~
-
-**Note:** Shareable objects (`async_safe? -> true`) are never traversed or transferred, as they can be safely shared across fibers.
 
 ## Integration with Tests
 
@@ -222,37 +249,37 @@ When deciding whether to mark a class or method with `ASYNC_SAFE = false`, consi
 **Immutable objects:**
 ~~~ ruby
 class ImmutableUser
-  def initialize(name, email)
-    @name = name.freeze
-    @email = email.freeze
-    freeze  # Entire object is frozen
-  end
-  
-  attr_reader :name, :email
+	def initialize(name, email)
+		@name = name.freeze
+		@email = email.freeze
+		freeze  # Entire object is frozen
+	end
+	
+	attr_reader :name, :email
 end
 ~~~
 
 **Pure functions (no state modification):**
 ~~~ ruby
 class Calculator
-  def add(a, b)
-    a + b  # No instance state, pure computation
-  end
+	def add(a, b)
+		a + b  # No instance state, pure computation
+	end
 end
 ~~~
 
 **Thread-safe synchronization:**
 ~~~ ruby
 class SafeQueue
-  ASYNC_SAFE = true  # Explicitly marked
-  
-  def initialize
-    @queue = Thread::Queue.new  # Thread-safe internally
-  end
-  
-  def push(item)
-    @queue.push(item)  # Delegates to thread-safe queue
-  end
+	ASYNC_SAFE = true  # Explicitly marked
+	
+	def initialize
+		@queue = Thread::Queue.new  # Thread-safe internally
+	end
+	
+	def push(item)
+		@queue.push(item)  # Delegates to thread-safe queue
+	end
 end
 ~~~
 
@@ -261,44 +288,44 @@ end
 **Mutable instance state:**
 ~~~ ruby
 class Counter
-  ASYNC_SAFE = false  # Enable tracking
-  
-  def initialize
-    @count = 0
-  end
-  
-  def increment
-    @count += 1  # Reads and writes @count (race condition!)
-  end
+	ASYNC_SAFE = false  # Enable tracking
+	
+	def initialize
+		@count = 0
+	end
+	
+	def increment
+		@count += 1  # Reads and writes @count (race condition!)
+	end
 end
 ~~~
 
 **Stateful iteration:**
 ~~~ ruby
 class Reader
-  ASYNC_SAFE = false  # Enable tracking
-  
-  def initialize(data)
-    @data = data
-    @index = 0
-  end
-  
-  def read
-    value = @data[@index]
-    @index += 1  # Mutates state
-    value
-  end
+	ASYNC_SAFE = false  # Enable tracking
+	
+	def initialize(data)
+		@data = data
+		@index = 0
+	end
+	
+	def read
+		value = @data[@index]
+		@index += 1  # Mutates state
+		value
+	end
 end
 ~~~
 
 **Lazy initialization:**
 ~~~ ruby
 class DataLoader
-  ASYNC_SAFE = false  # Enable tracking
-  
-  def data
-    @data ||= load_data  # Not atomic! (race condition)
-  end
+	ASYNC_SAFE = false  # Enable tracking
+	
+	def data
+		@data ||= load_data  # Not atomic! (race condition)
+	end
 end
 ~~~
 
@@ -308,23 +335,23 @@ Use hash or array configuration for classes with both safe and unsafe methods:
 
 ~~~ ruby
 class MixedClass
-  ASYNC_SAFE = {
-    read_config: true,   # Safe: only reads frozen data
-    update_state: false  # Unsafe: modifies mutable state
-  }.freeze
-  
-  def initialize
-    @config = {setting: "value"}.freeze
-    @state = {count: 0}
-  end
-  
-  def read_config
-    @config[:setting]  # Safe: frozen hash
-  end
-  
-  def update_state
-    @state[:count] += 1  # Unsafe: mutates state
-  end
+	ASYNC_SAFE = {
+		read_config: true,   # Safe: only reads frozen data
+		update_state: false  # Unsafe: modifies mutable state
+	}.freeze
+	
+	def initialize
+		@config = {setting: "value"}.freeze
+		@state = {count: 0}
+	end
+	
+	def read_config
+		@config[:setting]  # Safe: frozen hash
+	end
+	
+	def update_state
+		@state[:count] += 1  # Unsafe: mutates state
+	end
 end
 ~~~
 
@@ -351,24 +378,3 @@ If you're unsure whether a class is thread-safe:
 2. **Run your tests** with monitoring enabled.
 3. **If no violations occur** after thorough testing, it's likely safe.
 4. **Review the code** for the patterns above.
-
-## 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/lib/async/safe/class.rb

@@ -50,27 +50,4 @@ class Class
 	def async_safe!(value = true)
 		self.const_set(:ASYNC_SAFE, value)
 	end
-	
-	# Define how to traverse this object's children during ownership transfer.
-	#
-	# This method is called by `Async::Safe.transfer` to recursively transfer
-	# ownership of contained objects. By default, only the object itself is transferred.
-	# Define this method to enable deep transfer for collection-like classes.
-	#
-	# @parameter instance [Object] The instance to traverse.
-	# @parameter block [Proc] Block to call for each child object that should be transferred.
-	#
-	# ~~~ ruby
-	# class MyContainer
-	#   async_safe!(false)
-	#   attr_reader :children
-	#   
-	#   def self.async_safe_traverse(instance, &block)
-	#     instance.children.each(&block)
-	#   end
-	# end
-	# ~~~
-	def async_safe_traverse(instance, &block)
-		# Default: no traversal (shallow transfer only)
-	end
 end

data/lib/async/safe/monitor.rb

@@ -3,81 +3,42 @@
 # Released under the MIT License.
 # Copyright, 2025, by Samuel Williams.
 
-require "set"
-require "weakref"
-
-# Fiber-local variable to track when we're in a transfer operation:
-Fiber.attr_accessor :async_safe_transfer
+require_relative "violation_error"
 
 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!\n\tObject: #{@target.inspect}##{@method}\n\tOwner: #{@owner.inspect}\n\tAccessed by: #{@current.inspect}"
-			end
-		end
-		
-		# The core monitoring implementation using TracePoint.
+		# Monitors for concurrent access to objects across fibers.
 		#
-		# 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.
+		# This monitor detects when multiple fibers try to execute methods on the same
+		# object simultaneously (actual data races). Sequential access across fibers is
+		# allowed - objects can be passed between fibers freely.
 		#
-		# 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.
+		# Uses TracePoint to track in-flight method calls and detect concurrent access.
 		class Monitor
 			ASYNC_SAFE = true
 			
-			# Initialize a new monitor instance.
+			# Initialize a new concurrency monitor.
 			def initialize
-				@owners = ObjectSpace::WeakMap.new
+				@guards = ObjectSpace::WeakMap.new  # Tracks {object => fiber} or {object => {guard => fiber}}
 				@mutex = Thread::Mutex.new
 				@trace_point = nil
 			end
 			
-			attr :owners
+			attr :guards
 			
 			# Enable the monitor by activating the TracePoint.
 			def enable!
-				@trace_point ||= TracePoint.trace(:call, &method(:check_access))
+				return if @trace_point
+				
+				@trace_point = TracePoint.new(:call, :return) do |tp|
+					if tp.event == :call
+						check_call(tp)
+					else
+						check_return(tp)
+					end
+				end
+				
+				@trace_point.enable
 			end
 			
 			# Disable the monitor by deactivating the TracePoint.
@@ -88,67 +49,94 @@ module Async
 				end
 			end
 			
-			# Explicitly transfer ownership of objects to the current fiber.
+			# Transfer has no effect in concurrency monitoring.
 			#
-			# Also recursively transfers ownership of any tracked instance variables and
-			# objects contained in collections (Array, Hash, Set).
+			# Objects can move freely between fibers. This method exists for
+			# backward compatibility but does nothing.
 			#
-			# @parameter objects [Array(Object)] The objects to transfer.
+			# @parameter objects [Array(Object)] The objects to transfer (ignored).
 			def transfer(*objects)
-				current = Fiber.current
-				visited = Set.new
-				
-				# Disable tracking during traversal to avoid deadlock:
-				current.async_safe_transfer = true
-				
-				begin
-					# Traverse object graph:
-					objects.each do |object|
-						traverse_objects(object, visited)
-					end
-					
-					# Transfer all visited objects:
-					@mutex.synchronize do
-						visited.each do |object|
-							@owners[object] = current if @owners.key?(object)
-						end
-					end
-				ensure
-					current.async_safe_transfer = false
-				end
+				# No-op - objects move freely between fibers
 			end
 			
-			# Traverse the object graph and collect all reachable objects.
+			# Check method call for concurrent access violations.
 			#
-			# @parameter object [Object] The object to traverse.
-			# @parameter visited [Set] Set of visited objects (object references, not IDs).
-			private def traverse_objects(object, visited)
-				# Avoid circular references:
-				return if visited.include?(object)
+			# @parameter trace_point [TracePoint] The trace point containing call information.
+			private def check_call(trace_point)
+				object = trace_point.self
+				
+				# Skip tracking class/module methods:
+				return if object.is_a?(Module)
+				
+				# Skip frozen objects:
+				return if object.frozen?
 				
-				# Skip objects that don't need traversing:
-				return if object.frozen? or object.is_a?(Module)
+				method = trace_point.method_id
 				
-				# Skip async-safe (shareable) objects - they're not owned:
+				# Check the object's actual class:
 				klass = object.class
-				return if klass.async_safe?(nil)
 				
-				# Mark as visited:
-				visited << object
+				# Check if the class or method is marked as async-safe:
+				# Returns: true (skip), false (simple tracking), or Symbol (guard-based tracking)
+				safe = klass.async_safe?(method)
+				return if safe == true
+				
+				current = Fiber.current
 				
-				# Recurse through custom traversal:
-				klass.async_safe_traverse(object) do |element|
-					traverse_objects(element, visited)
+				@mutex.synchronize do
+					if safe == false
+						# Simple tracking (single guard)
+						if fiber = @guards[object]
+							if fiber != current && !fiber.is_a?(Hash)
+								# Concurrent access detected!
+								raise ViolationError.new(
+									"Concurrent access detected!",
+									target: object,
+									method: method,
+									owner: fiber,
+									current: current,
+								)
+							end
+						else
+							# Acquire the guard
+							@guards[object] = current
+						end
+					else
+						# Multi-guard tracking
+						guard = safe
+						
+						# Get or create the guards hash for this object
+						entry = @guards[object]
+						if entry.nil? || !entry.is_a?(Hash)
+							guards = @guards[object] = {}
+						else
+							guards = entry
+						end
+						
+						# Check if another fiber currently holds this guard
+						if fiber = guards[guard]
+							if fiber != current
+								# Concurrent access detected within the same guard!
+								raise ViolationError.new(
+									"Concurrent access detected (guard: #{guard})!",
+									target: object,
+									method: method,
+									owner: fiber,
+									current: current,
+								)
+							end
+						else
+							# Acquire this guard
+							guards[guard] = current
+						end
+					end
 				end
 			end
 			
-			# Check if the current access is allowed or constitutes a violation.
+			# Check method return to release guard.
 			#
-			# @parameter trace_point [TracePoint] The trace point containing access information.
-			def check_access(trace_point)
-				# Skip if we're in a transfer operation:
-				return if Fiber.current.async_safe_transfer
-				
+			# @parameter trace_point [TracePoint] The trace point containing return information.
+			private def check_return(trace_point)
 				object = trace_point.self
 				
 				# Skip tracking class/module methods:
@@ -158,33 +146,32 @@ module Async
 				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
+				safe = klass.async_safe?(method)
+				return if safe == true
 				
-				# 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
+					entry = @guards[object]
+					
+					if safe == false
+						# Simple tracking (single guard)
+						# Release if this fiber holds it
+						@guards.delete(object) if entry == current
 					else
-						# First access - record owner:
-						@owners[object] = current
+						# Multi-guard tracking
+						guard = safe
+						
+						if entry.is_a?(Hash)
+							entry.delete(guard) if entry[guard] == current
+							# Clean up empty guards hash
+							@guards.delete(object) if entry.empty?
+						end
 					end
 				end
 			end

data/lib/async/safe/version.rb

@@ -5,7 +5,7 @@
 
 module Async
 	module Safe
-		VERSION = "0.4.1"
+		VERSION = "0.5.0"
 	end
 end
 

data/lib/async/safe/violation_error.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2025, by Samuel Williams.
+
+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!\n\tObject: #{@target.inspect}##{@method}\n\tOwner: #{@owner.inspect}\n\tAccessed by: #{@current.inspect}"
+			end
+		end
+	end
+end
+

data/lib/async/safe.rb

@@ -6,7 +6,6 @@
 require_relative "safe/version"
 require_relative "safe/class"
 require_relative "safe/monitor"
-require_relative "safe/builtins"
 
 # @namespace
 module Async
@@ -24,8 +23,11 @@ module Async
 			
 			# 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.
+			# This activates a TracePoint that detects concurrent access to objects across
+			# fibers and threads. There is no performance overhead when monitoring is disabled.
+			#
+			# Objects can move freely between fibers - only actual concurrent access (data races)
+			# is detected and reported.
 			def enable!
 				@monitor ||= Monitor.new
 				@monitor.enable!
@@ -37,23 +39,14 @@ module Async
 				@monitor = nil
 			end
 			
-			# Explicitly transfer ownership of objects to the current fiber.
-			#
-			# This allows an object to be safely passed between fibers.
+			# Transfer has no effect in concurrency monitoring mode.
 			#
-			# @parameter objects [Array(Object)] The objects to transfer ownership of.
+			# Objects can move freely between fibers. This method is kept for
+			# backward compatibility but does nothing.
 			#
-			# ~~~ ruby
-			# request = Request.new(...)
-			# 
-			# Fiber.schedule do
-			# 	# Transfer ownership of the request to this fiber:
-			# 	Async::Safe.transfer(request)
-			# 	process(request)
-			# end
-			# ~~~
+			# @parameter objects [Array(Object)] The objects to transfer (ignored).
 			def transfer(*objects)
-				@monitor&.transfer(*objects)
+				# No-op - objects can move freely between fibers
 			end
 		end
 	end

data/readme.md

@@ -8,9 +8,9 @@ This gem provides a TracePoint-based ownership tracking system that detects when
 
 ## 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.
+Ruby's fiber-based concurrency (via `async`) can lead to data races when objects are accessed concurrently. This gem helps you catch these concurrency bugs in your test suite by detecting when multiple fibers access the same object simultaneously.
 
-Enable it in your tests to get immediate feedback when objects are incorrectly shared across fibers.
+Enable it in your tests to get immediate feedback when invalid concurrent access occurs.
 
 ## Usage
 
@@ -22,6 +22,11 @@ Please see the [project documentation](https://socketry.github.io/async-safe/) f
 
 Please see the [project releases](https://socketry.github.io/async-safe/releases/index) for all releases.
 
+### v0.5.0
+
+  - More conservative tracking of objects using call/return for ownership transfer.
+  - Introduced guard concept for splitting ownership within a single object, e.g. independently concurrent readable and writable parts of an object.
+
 ### v0.4.0
 
   - Improved `Async::Safe.transfer` to recursively transfer ownership of tracked instance variables.

data/releases.md

@@ -1,5 +1,10 @@
 # Releases
 
+## v0.5.0
+
+  - More conservative tracking of objects using call/return for ownership transfer.
+  - Introduced guard concept for splitting ownership within a single object, e.g. independently concurrent readable and writable parts of an object.
+
 ## v0.4.0
 
   - Improved `Async::Safe.transfer` to recursively transfer ownership of tracked instance variables.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: async-safe
 version: !ruby/object:Gem::Version
-  version: 0.4.1
+  version: 0.5.0
 platform: ruby
 authors:
 - Samuel Williams
@@ -45,10 +45,10 @@ 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
+- lib/async/safe/violation_error.rb
 - license.md
 - readme.md
 - releases.md

data/lib/async/safe/builtins.rb

@@ -1,97 +0,0 @@
-# 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.
-
-# Arrays contain references to other objects that may need transfer:
-class Array
-	ASYNC_SAFE = false
-	
-	# Traverse array elements during ownership transfer.
-	#
-	# @parameter instance [Array] The array instance to traverse.
-	# @parameter block [Proc] Block to call for each element.
-	def self.async_safe_traverse(instance, &block)
-		instance.each(&block)
-	end
-end
-
-# Hashes contain keys and values that may need transfer:
-class Hash
-	ASYNC_SAFE = false
-	
-	# Traverse hash keys and values during ownership transfer.
-	#
-	# @parameter instance [Hash] The hash instance to traverse.
-	# @parameter block [Proc] Block to call for each key and value.
-	def self.async_safe_traverse(instance, &block)
-		instance.each_key(&block)
-		instance.each_value(&block)
-	end
-end
-
-# Sets contain elements that may need transfer:
-class Set
-	ASYNC_SAFE = false
-	
-	# Traverse set elements during ownership transfer.
-	#
-	# @parameter instance [Set] The set instance to traverse.
-	# @parameter block [Proc] Block to call for each element.
-	def self.async_safe_traverse(instance, &block)
-		instance.each(&block)
-	end
-end
-
-module Async
-	module Safe
-		# Automatically transfers ownership of objects when they are removed from a Thread::Queue.
-		#
-		# When included in Thread::Queue or Thread::SizedQueue, this module wraps pop/deq/shift
-		# methods to automatically transfer ownership of the dequeued object to the fiber that
-		# dequeues it.
-		module TransferableThreadQueue
-			# Pop an object from the queue and transfer ownership to the current fiber.
-			#
-			# @parameter arguments [Array] Arguments passed to the original pop method.
-			# @returns [Object] The dequeued object with transferred ownership.
-			def pop(...)
-				object = super(...)
-				Async::Safe.transfer(object)
-				object
-			end
-			
-			# Dequeue an object from the queue and transfer ownership to the current fiber.
-			#
-			# Alias for {#pop}.
-			#
-			# @parameter arguments [Array] Arguments passed to the original deq method.
-			# @returns [Object] The dequeued object with transferred ownership.
-			def deq(...)
-				object = super(...)
-				Async::Safe.transfer(object)
-				object
-			end
-			
-			# Shift an object from the queue and transfer ownership to the current fiber.
-			#
-			# Alias for {#pop}.
-			#
-			# @parameter arguments [Array] Arguments passed to the original shift method.
-			# @returns [Object] The dequeued object with transferred ownership.
-			def shift(...)
-				object = super(...)
-				Async::Safe.transfer(object)
-				object
-			end
-		end
-	end
-end
-
-Thread::Queue.prepend(Async::Safe::TransferableThreadQueue)
-Thread::SizedQueue.prepend(Async::Safe::TransferableThreadQueue)