Don't default to unsafe...

Author: samuel-williams-shopify

guides/getting-started/readme.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
@@ -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,6 +138,17 @@ Fiber.schedule do
 end
 ~~~
 
+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:

lib/async/safe.rb

@@ -12,47 +12,12 @@
 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
@@ -61,14 +26,8 @@ class << self
 			#
 			# This activates a TracePoint that tracks object access across fibers and threads.
 			# There is no performance overhead when monitoring is disabled.
-			#
-			# @parameter logger [Object | Nil] Optional logger to use for violations instead of raising exceptions.
-			def enable!(logger: nil)
-				if @monitor
-					raise "Async::Safe is already enabled!"
-				end
-				
-				@monitor = Monitor.new(logger: logger)
+			def enable!
+				@monitor ||= Monitor.new
 				@monitor.enable!
 			end
 

lib/async/safe/builtins.rb

@@ -8,34 +8,42 @@
 # 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
-
-# Fibers are async-safe:
-Fiber::ASYNC_SAFE = true
-
-# ObjectSpace::WeakMap is async-safe:
-ObjectSpace::WeakMap::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)

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.

lib/async/safe/monitor.rb

@@ -64,13 +64,10 @@ class Monitor
 			ASYNC_SAFE = true
 
 			# Initialize a new monitor instance.
-			#
-			# @parameter logger [Object | Nil] Optional logger to use for violations instead of raising exceptions.
-			def initialize(logger: nil)
+			def initialize
 				@owners = ObjectSpace::WeakMap.new
 				@mutex = Thread::Mutex.new
 				@trace_point = nil
-				@logger = logger
 			end
 
 			attr :owners
@@ -131,11 +128,12 @@ def check_access(trace_point)
 					if owner = @owners[object]
 						# Violation if accessed from different fiber:
 						if owner != current
-							if @logger
-								@logger.warn(self, "Async::Safe violation detected!", klass: klass, method: method, owner: owner, current: current, backtrace: caller_locations(3..))
-							else
-								raise ViolationError.new(target: object, method: method, owner: owner, current: current)
-							end
+							raise ViolationError.new(
+								target: object,
+								method: method,
+								owner: owner,
+								current: current,
+							)
 						end
 					else
 						# First access - record owner:

releases.md

@@ -1,5 +1,15 @@
 # Releases
 
+## Unreleased
+
+- 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.