async-safe 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e20fdea7f6f63f3a47aa8be85492fa2725e6b3ea2c0284de63dd6fe45af6f49c
-  data.tar.gz: 6556e3ed8f46cfe8157983229d4584a6b01eb0e8f2b36f83fe3ec5f541211830
+  metadata.gz: 8d77ebea20acb12bfc6f9e7848a809a17d993df98604ec9b457433ddf211437d
+  data.tar.gz: b7bdcdf3d68df5a5f385a252926319b6ffb2154b3bb431507d63fb3fe64f255e
 SHA512:
-  metadata.gz: 6a02637fc476e5e38a6b1952394ad99ca3fbe13b106b6d7ac0abbafc7f285167f3a0ef9302a28ac0e12f29a70edce7158ea2690b88d309e99a5d1f073da58580
-  data.tar.gz: 24fbc11d3be799f80649e1a487edc6f1b4040fbb0e4688d590f2caafceb76b761c298569a3b2384939844753eec8b788ff0bf70d8f820b3fbe4c9d9403183542
+  metadata.gz: 9cc0287a91eb60e17f4a6047574a88bf813dbe39ddf345738d3aacadd8a171ed3540e2e7f1004c987c45a5abd3afdfe83407cec276f08ede0a612a76fd0509da
+  data.tar.gz: ada0c1d9c123abacc5688a787229a0c578d2b3c59b7dbd7fe2c944e990a9eb2ffa3de4842e43b22b3eb0521683a8c1f7ccfd5221be35df9f6d36ee16e3e33914

data/context/getting-started.md

@@ -25,12 +25,14 @@ 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.
 
-## Single-Owner Model
+### Single-Owner Model (Opt-In)
 
-By default, all objects are assumed to follow a **single-owner model** - they should only be accessed from one fiber/thread at a time:
+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
@@ -51,7 +53,7 @@ Fiber.schedule do
 end
 ~~~
 
-## Marking Async-Safe Classes
+### Marking Async-Safe Classes
 
 Mark entire classes as safe for concurrent access:
 
@@ -90,15 +92,29 @@ class MyQueue
 end
 ~~~
 
-## Marking Async-Safe Methods
+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
+end
+~~~
+
+### Marking Methods with Hash
 
-Mark specific methods as async-safe:
+Use a hash to specify which methods are async-safe:
 
 ~~~ ruby
 class MixedSafety
-  include Async::Safe
-  
-  async_safe :safe_read
+  ASYNC_SAFE = {
+    safe_read: true,   # This method is async-safe
+    increment: false   # This method is NOT async-safe
+  }.freeze
   
   def initialize(data)
     @data = data
@@ -110,7 +126,7 @@ class MixedSafety
   end
   
   def increment
-    @count += 1  # Not async-safe
+    @count += 1  # Not async-safe - will be tracked
   end
 end
 
@@ -122,7 +138,18 @@ Fiber.schedule do
 end
 ~~~
 
-## Transferring Ownership
+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
+end
+~~~
+
+### Transferring Ownership
 
 Explicitly transfer ownership between fibers:
 

data/lib/async/safe/builtins.rb

@@ -8,15 +8,50 @@
 # 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
+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
 
-# Fibers are async-safe:
-Fiber::ASYNC_SAFE = true
-
-# ObjectSpace::WeakMap is async-safe:
-ObjectSpace::WeakMap::ASYNC_SAFE = true
+Thread::Queue.prepend(Async::Safe::TransferableThreadQueue)
+Thread::SizedQueue.prepend(Async::Safe::TransferableThreadQueue)

data/lib/async/safe/class.rb

@@ -7,15 +7,40 @@
 class Class
 	# Check if this class or a specific method is async-safe.
 	#
+	# The `ASYNC_SAFE` constant can be:
+	# - `true` - entire class is async-safe.
+	# - `false` - entire class is NOT async-safe (single-owner).
+	# - `{method_name: true/false}` - per-method configuration.
+	# - `[method_name1, method_name2]` - per-method configuration.
+	#
 	# @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.
+	# @returns [Boolean] Whether the class or method is async-safe. Defaults to true if not specified.
 	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
+		if const_defined?(:ASYNC_SAFE)
+			async_safe = const_get(:ASYNC_SAFE)
+			
+			case async_safe
+			when Hash
+				if method
+					async_safe = async_safe.fetch(method, false)
+				else
+					# In general, some methods may not be safe:
+					async_safe = false
+				end
+			when Array
+				if method
+					async_safe = async_safe.include?(method)
+				else
+					# In general, some methods may not be safe:
+					async_safe = false
+				end
+			end
+			
+			return async_safe
 		end
 		
-		false
+		# Default to true:
+		return true
 	end
 	
 	# Mark the class as async-safe or not.

data/lib/async/safe/version.rb

@@ -5,7 +5,7 @@
 
 module Async
 	module Safe
-		VERSION = "0.1.0"
+		VERSION = "0.3.0"
 	end
 end
 

data/lib/async/safe.rb

@@ -12,47 +12,12 @@ require_relative "safe/builtins"
 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.
+	# By default, all classes are assumed to be async-safe. Classes that follow a
+	# **single-owner model** should be explicitly marked with `ASYNC_SAFE = false` to
+	# enable tracking and violation detection.
 	#
 	# 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

data/readme.md

@@ -22,6 +22,21 @@ 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.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.
+  - Removed `reset!` method: use `disable!` + `enable!` instead.
+
+### v0.2.0
+
+  - `Thread::Queue` transfers ownership of objects popped from it.
+  - Add support for `logger:` option in `Async::Safe.enable!` which logs violations instead of raising errors.
+
 ### v0.1.0
 
   - Implement TracePoint-based ownership tracking.

data/releases.md

@@ -1,5 +1,20 @@
 # Releases
 
+## 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.
+  - Removed `reset!` method: use `disable!` + `enable!` instead.
+
+## v0.2.0
+
+  - `Thread::Queue` transfers ownership of objects popped from it.
+  - Add support for `logger:` option in `Async::Safe.enable!` which logs violations instead of raising errors.
+
 ## v0.1.0
 
   - Implement TracePoint-based ownership tracking.

metadata

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