async-safe 0.2.0 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 52f743f5c66ba254659d3f6afb52e8f6bf1189f395ca931e708890eea1fe4e00
-  data.tar.gz: 4a89412e5fd61a9c4c5bdac4d90a6897e70fbeccac5301b58e56a3cf622542a8
+  metadata.gz: a165b5a9b594d4eec52f9a7c80ee3cc020db7925ac7630ddc342a552a3a20112
+  data.tar.gz: c9cedd555a12b366f00bf4fa43906501bd6596a8abd3db2531b457d3083bd093
 SHA512:
-  metadata.gz: b7b6981fe90ffdbef57060678ba4988202333120848cc40d4528873b9a6ccd5b39a53549d35886d75a08343db12697855eb56c74af9d06c9434e2a153d6caef5
-  data.tar.gz: 8a0ec23a746938beeadd581af8e7aaa19dc0219826343a40ef9d93071e34b2956e67fcab1c33c3529940716195b7958e2f99a127c2e6c47ca72e333f0c783f61
+  metadata.gz: 5816b73d736aa8570fbdf3eed10ba2424e0dc138ac823bd37577cda99b42ac5c120556ac34b60cb645d08206a0214bd5b9a36bd8b25fae829791c522c2586ccf
+  data.tar.gz: d5c2d51e17041f290616eb45a4be80acd5e33b6a6b4e59a801462a3d7bfaccb453633c8e921a2d615136ac784b20fa92436fa73cf664ba4bcf6eaa807ab6ec7e

data/context/getting-started.md

@@ -27,10 +27,12 @@ When a violation is detected, an `Async::Safe::ViolationError` will be raised im
 
 ### Single-Owner Model
 
-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:
 
-Mark specific methods as async-safe:
+~~~ 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
+
+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:
@@ -154,6 +181,145 @@ $ bundle exec sus
 
 Any thread safety violations will cause your tests to fail immediately with a clear error message showing which object was accessed incorrectly and from which fibers.
 
+## Determining Async Safety
+
+When deciding whether to mark a class or method with `ASYNC_SAFE = false`, consider these factors:
+
+### Async-Safe Patterns
+
+**Immutable objects:**
+~~~ ruby
+class ImmutableUser
+  def initialize(name, email)
+    @name = name.freeze
+    @email = email.freeze
+    freeze  # Entire object is frozen
+  end
+  
+  attr_reader :name, :email
+end
+~~~
+
+**Pure functions (no state modification):**
+~~~ ruby
+class Calculator
+  def add(a, b)
+    a + b  # No instance state, pure computation
+  end
+end
+~~~
+
+**Thread-safe synchronization:**
+~~~ ruby
+class SafeQueue
+  ASYNC_SAFE = true  # Explicitly marked
+  
+  def initialize
+    @queue = Thread::Queue.new  # Thread-safe internally
+  end
+  
+  def push(item)
+    @queue.push(item)  # Delegates to thread-safe queue
+  end
+end
+~~~
+
+### Unsafe (Single-Owner) Patterns
+
+**Mutable instance state:**
+~~~ ruby
+class Counter
+  ASYNC_SAFE = false  # Enable tracking
+  
+  def initialize
+    @count = 0
+  end
+  
+  def increment
+    @count += 1  # Reads and writes @count (race condition!)
+  end
+end
+~~~
+
+**Stateful iteration:**
+~~~ ruby
+class Reader
+  ASYNC_SAFE = false  # Enable tracking
+  
+  def initialize(data)
+    @data = data
+    @index = 0
+  end
+  
+  def read
+    value = @data[@index]
+    @index += 1  # Mutates state
+    value
+  end
+end
+~~~
+
+**Lazy initialization:**
+~~~ ruby
+class DataLoader
+  ASYNC_SAFE = false  # Enable tracking
+  
+  def data
+    @data ||= load_data  # Not atomic! (race condition)
+  end
+end
+~~~
+
+### Mixed Safety
+
+Use hash or array configuration for classes with both safe and unsafe methods:
+
+~~~ ruby
+class MixedClass
+  ASYNC_SAFE = {
+    read_config: true,   # Safe: only reads frozen data
+    update_state: false  # Unsafe: modifies mutable state
+  }.freeze
+  
+  def initialize
+    @config = {setting: "value"}.freeze
+    @state = {count: 0}
+  end
+  
+  def read_config
+    @config[:setting]  # Safe: frozen hash
+  end
+  
+  def update_state
+    @state[:count] += 1  # Unsafe: mutates state
+  end
+end
+~~~
+
+### Quick Checklist
+
+Mark a method as unsafe (`ASYNC_SAFE = false`) if it:
+- ❌ Modifies instance variables.
+- ❌ Uses `||=` for lazy initialization.
+- ❌ Iterates with mutable state (like `@index`).
+- ❌ Reads then writes shared state.
+- ❌ Accesses mutable collections without synchronization.
+
+A method is likely safe if it:
+- ✅ Only reads from frozen/immutable data.
+- ✅ Has no instance state.
+- ✅ Uses only local variables.
+- ✅ Delegates to thread-safe primitives `Thread::Queue`, `Mutex`, etc.
+- ✅ The object itself is frozen.
+
+### When in Doubt
+
+If you're unsure whether a class is thread-safe:
+1. **Mark it as unsafe** (`ASYNC_SAFE = false`) - let the monitoring catch any issues.
+2. **Run your tests** with monitoring enabled.
+3. **If no violations occur** after thorough testing, it's likely safe.
+4. **Review the code** for the patterns above.
+
 ## How It Works
 
 1. **Default Assumption**: All objects follow a single-owner model (not thread-safe).

data/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)

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/monitor.rb

@@ -64,13 +64,10 @@ module Async
 			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 @@ module Async
 					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:

data/lib/async/safe/version.rb

@@ -5,7 +5,7 @@
 
 module Async
 	module Safe
-		VERSION = "0.2.0"
+		VERSION = "0.3.1"
 	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
@@ -61,14 +26,8 @@ module Async
 			#
 			# 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
 			

data/readme.md

@@ -22,6 +22,16 @@ 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.

data/releases.md

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

metadata

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