Better ownership transfer.

Author: samuel-williams-shopify

guides/getting-started/readme.md

@@ -163,6 +163,38 @@ Fiber.schedule do
 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 if instance.body
+    yield instance.headers if 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
 
 Add to your test helper (e.g., `config/sus.rb` or `spec/spec_helper.rb`):

lib/async/safe/builtins.rb

@@ -8,6 +8,34 @@
 # 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
+	
+	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
+	
+	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
+	
+	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.

lib/async/safe/class.rb

@@ -45,9 +45,31 @@ def async_safe?(method = nil)
 
 	# 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.
+	# @parameter value [Boolean | Hash | Array] Configuration for async-safety.
+	# @returns [Boolean | Hash | Array] The configured value.
 	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)
+	#   
+	#   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

lib/async/safe/monitor.rb

@@ -87,25 +87,63 @@ def disable!
 
 			# Explicitly transfer ownership of objects to the current fiber.
 			#
+			# Also recursively transfers ownership of any tracked instance variables and
+			# objects contained in collections (Array, Hash, Set).
+			#
 			# @parameter objects [Array(Object)] The objects to transfer.
 			def transfer(*objects)
+				current = Fiber.current
+				visited = Set.new
+				
+				# Traverse object graph (outside mutex to avoid deadlock):
+				objects.each do |object|
+					traverse_objects(object, visited)
+				end
+				
+				# Transfer all visited objects (convert to array to avoid triggering TracePoint in sync block):
+				objects_to_transfer = visited.to_a
+				
 				@mutex.synchronize do
-					current = Fiber.current
-					
-					objects.each do |object|
-						@owners[object] = current
+					objects_to_transfer.each do |object|
+						@owners[object] = current if @owners.key?(object)
 					end
 				end
 			end
 
+			private
+			
+			# Traverse the object graph and collect all reachable objects.
+			#
+			# @parameter object [Object] The object to traverse.
+			# @parameter visited [Set] Set of visited objects (object references, not IDs).
+			def traverse_objects(object, visited)
+				# Avoid circular references:
+				return if visited.include?(object)
+				
+				# Skip objects that don't need traversing:
+				return if object.frozen? or object.is_a?(Module)
+				
+				# Skip async-safe (shareable) objects - they're not owned:
+				klass = object.class
+				return if klass.async_safe?(nil)
+				
+				# Mark as visited:
+				visited << object
+				
+				# Recurse through custom traversal:
+				klass.async_safe_traverse(object) do |element|
+					traverse_objects(element, visited)
+				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)
+				return if object.is_a?(Module)
 
 				# Skip frozen objects:
 				return if object.frozen?

releases.md

@@ -1,17 +1,24 @@
 # Releases
 
+## Unreleased
+
+  - Improved `Async::Safe.transfer` to recursively transfer ownership of tracked instance variables.
+
 ## v0.3.2
 
   - Better error message.
 
 ## v0.3.0
 
-  - Inverted default model: classes are async-safe by default, use `ASYNC_SAFE = false` to enable tracking.
-  - Added flexible `ASYNC_SAFE` constant support: boolean, hash, or array configurations.
-  - Added `Class#async_safe!` method for marking classes.
-  - Added `Class#async_safe?(method)` method for querying safety.
-  - Removed logger feature: always raises `ViolationError` exceptions.
-  - Removed `Async::Safe::Concurrent` module: use `async_safe!` instead.
+- Inverted default model: classes are async-safe by default, use `ASYNC_SAFE = false` to enable tracking.
+- Added flexible `ASYNC_SAFE` constant support: boolean, hash, or array configurations.
+- Added `Class#async_safe!` method for marking classes.
+- Added `Class#async_safe?(method)` method for querying safety.
+- Added `Class.async_safe_traverse` for custom deep transfer traversal (opt-in).
+- Improved `Async::Safe.transfer` to use shallow transfer by default with opt-in deep traversal.
+- Mark built-in collections (`Array`, `Hash`, `Set`) as single-owner with deep traversal support.
+- Removed logger feature: always raises `ViolationError` exceptions.
+- Removed `Async::Safe::Concurrent` module: use `async_safe!` instead.
 
 ## v0.2.0
 

test/async/safe.rb

@@ -73,6 +73,33 @@ def push(item)
 		end.not.to raise_exception
 	end
 
+	it "recursively transfers owned instance variables" do
+		inner_class = Class.new do
+			async_safe!(false)
+			def read; "data"; end
+		end
+		
+		outer_class = Class.new do
+			async_safe!(false)
+			attr_reader :inner
+			def initialize(inner); @inner = inner; end
+		end
+		
+		inner = inner_class.new
+		outer = outer_class.new(inner)
+		
+		# Both owned by main fiber:
+		inner.read
+		outer.inner
+		
+		Fiber.new do
+			Async::Safe.transfer(outer)
+			
+			# Both outer and inner should be transferred:
+			outer.inner.read
+		end.resume
+	end
+	
 	it "allows access after ownership transfer" do
 		body = body_class.new(["a", "b"])
 		body.read  # Main fiber owns it