async-safe 0.3.0 → 0.3.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8d77ebea20acb12bfc6f9e7848a809a17d993df98604ec9b457433ddf211437d
-  data.tar.gz: b7bdcdf3d68df5a5f385a252926319b6ffb2154b3bb431507d63fb3fe64f255e
+  metadata.gz: 3d1ccb933e5a9b488f7c33e02d547ca69463e4b7c94fadccb3550196f9f765d5
+  data.tar.gz: 1050434843c8f29403076ef9bf3aa0946122e9e62d68d6aea5334c17cd5a449c
 SHA512:
-  metadata.gz: 9cc0287a91eb60e17f4a6047574a88bf813dbe39ddf345738d3aacadd8a171ed3540e2e7f1004c987c45a5abd3afdfe83407cec276f08ede0a612a76fd0509da
-  data.tar.gz: ada0c1d9c123abacc5688a787229a0c578d2b3c59b7dbd7fe2c944e990a9eb2ffa3de4842e43b22b3eb0521683a8c1f7ccfd5221be35df9f6d36ee16e3e33914
+  metadata.gz: e0a5426f5a9157f304e8e4d679199d5db4da2d82aba4322c84c3b67b1d61fb64c98c6370260d09f7a8615b8b785bd3691167e7ec897b31ee7d123b75e9ac2bc4
+  data.tar.gz: 9d0101093bf612f7915083bf7e03bf2e1bc38d9cb3cae8dbde5e7ae0507926a4f47dba0b39592581fca00b1c556137f45fdb71ba9688d40d123e9cbf9232b921

data/context/getting-started.md

@@ -25,7 +25,7 @@ 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 (Opt-In)
+### Single-Owner Model
 
 By default, all classes are assumed to be async-safe. To enable tracking for specific classes, mark them with `ASYNC_SAFE = false`:
 
@@ -181,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/monitor.rb

@@ -47,7 +47,7 @@ module Async
 			end
 			
 			private def build_message
-				"Thread safety violation detected! #{@target.inspect}##{@method} was accessed from #{@current.inspect} by #{@owner.inspect}."
+				"Thread safety violation detected!\n\tObject: #{@target.inspect}##{@method}\n\tOwner: #{@owner.inspect}\n\tAccessed by: #{@current.inspect}"
 			end
 		end
 		

data/lib/async/safe/version.rb

@@ -5,7 +5,7 @@
 
 module Async
 	module Safe
-		VERSION = "0.3.0"
+		VERSION = "0.3.2"
 	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.3.2
+
+  - Better error message.
+
 ### v0.3.0
 
   - Inverted default model: classes are async-safe by default, use `ASYNC_SAFE = false` to enable tracking.
@@ -30,7 +34,6 @@ Please see the [project releases](https://socketry.github.io/async-safe/releases
   - 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
 

data/releases.md

@@ -1,5 +1,9 @@
 # Releases
 
+## v0.3.2
+
+  - Better error message.
+
 ## v0.3.0
 
   - Inverted default model: classes are async-safe by default, use `ASYNC_SAFE = false` to enable tracking.
@@ -8,7 +12,6 @@
   - 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
 

metadata

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