async-safe 0.3.2 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3d1ccb933e5a9b488f7c33e02d547ca69463e4b7c94fadccb3550196f9f765d5
-  data.tar.gz: 1050434843c8f29403076ef9bf3aa0946122e9e62d68d6aea5334c17cd5a449c
+  metadata.gz: 7859608fbc62080a81bb9f20ce2c9ffe8f299f76432d1ec9f4a3d4aa47291240
+  data.tar.gz: e9a4f441e4ccdbfe0f086d6df486f22c7aa9504d07f42128689f54fd1befad4d
 SHA512:
-  metadata.gz: e0a5426f5a9157f304e8e4d679199d5db4da2d82aba4322c84c3b67b1d61fb64c98c6370260d09f7a8615b8b785bd3691167e7ec897b31ee7d123b75e9ac2bc4
-  data.tar.gz: 9d0101093bf612f7915083bf7e03bf2e1bc38d9cb3cae8dbde5e7ae0507926a4f47dba0b39592581fca00b1c556137f45fdb71ba9688d40d123e9cbf9232b921
+  metadata.gz: 12d90b93da4da2d525d6bf9e14acf235f0a2c50bc8301cd265b88f333a9d8c9af55ed0a7d69cb992239af715f5cd680650de0d2b111fb474c3a487f1007acfdb
+  data.tar.gz: 84d82aa42d46b54494ac5f4c8b025c80f41b2c8ccb7e1412d89a5d1073c662f9b86c7a84dce7c782c73e97164fc8a2df0a5d064bb4dac83a9e0de3d7a85cc264

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,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.

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

@@ -87,17 +87,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)
+				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.
@@ -105,7 +143,7 @@ module Async
 				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.0"
 	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.0
 platform: ruby
 authors:
 - Samuel Williams

metadata.gz.sig

@@ -1,2 +1 @@
-�br���b�ٚ�)O�zil����qa�qT�`��ލ�c�ߴ��œu��u}(�g�=F��j����Z�1�<����F��z�$�N�ia�>������Zebε
-��cB4�V$h�0}�>cd��U@j�D�^Li�a@-�����!��J�!�{
+'�i��HX���Kl4�fŷ�9�O�^��w|��P _�]��@_�AFW	�URHwvn�9