async-safe 0.3.2 → 0.4.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3d1ccb933e5a9b488f7c33e02d547ca69463e4b7c94fadccb3550196f9f765d5
-  data.tar.gz: 1050434843c8f29403076ef9bf3aa0946122e9e62d68d6aea5334c17cd5a449c
+  metadata.gz: 72500ee1207a863df7f749896936bf9edce7e06f2f7d7a519329c0ada72951eb
+  data.tar.gz: 584c0393294503ea01cf1e1858f88f3c2faf5e2cd6fdf1b2f632af0708e4d787
 SHA512:
-  metadata.gz: e0a5426f5a9157f304e8e4d679199d5db4da2d82aba4322c84c3b67b1d61fb64c98c6370260d09f7a8615b8b785bd3691167e7ec897b31ee7d123b75e9ac2bc4
-  data.tar.gz: 9d0101093bf612f7915083bf7e03bf2e1bc38d9cb3cae8dbde5e7ae0507926a4f47dba0b39592581fca00b1c556137f45fdb71ba9688d40d123e9cbf9232b921
+  metadata.gz: 305ea4886f6b9fa0452de045244623806ed824ba24791ed0d2d1e6bf96a14f536f31fccbd54f099e5cc10ee1dc39067609be9b646daac413c47126a86f0306a2
+  data.tar.gz: 78dd7ab4aab4893c2824788e03522905698d6f400557976677253fbcc53643b4a0dbaaa8a8157249415f9380a317ffddc126948bb484fa2b6c795513abf4fc2d

data/context/getting-started.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
+    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
 
 Add to your test helper (e.g., `config/sus.rb` or `spec/spec_helper.rb`):

data/lib/async/safe/builtins.rb

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

data/lib/async/safe/class.rb

@@ -45,9 +45,32 @@ class Class
 	
 	# 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)
+	#   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

@@ -6,6 +6,9 @@
 require "set"
 require "weakref"
 
+# Fiber-local variable to track when we're in a transfer operation:
+Fiber.attr_accessor :async_safe_transfer
+
 module Async
 	module Safe
 		# Raised when an object is accessed from a different fiber than the one that owns it.
@@ -87,14 +90,55 @@ module Async
 			
 			# 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)
-				@mutex.synchronize do
-					current = Fiber.current
-					
+				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|
-						@owners[object] = current
+						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
+			end
+			
+			# 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).
+			private 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
 			
@@ -102,10 +146,13 @@ module Async
 			#
 			# @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
+				
 				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?

data/lib/async/safe/version.rb

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

data/readme.md

@@ -22,6 +22,10 @@ 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.4.0
+
+  - Improved `Async::Safe.transfer` to recursively transfer ownership of tracked instance variables.
+
 ### v0.3.2
 
   - Better error message.
@@ -32,6 +36,9 @@ Please see the [project releases](https://socketry.github.io/async-safe/releases
   - 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.
 

data/releases.md

@@ -1,5 +1,9 @@
 # Releases
 
+## v0.4.0
+
+  - Improved `Async::Safe.transfer` to recursively transfer ownership of tracked instance variables.
+
 ## v0.3.2
 
   - Better error message.
@@ -10,6 +14,9 @@
   - 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.
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: async-safe
 version: !ruby/object:Gem::Version
-  version: 0.3.2
+  version: 0.4.1
 platform: ruby
 authors:
 - Samuel Williams