async-safe 0.3.0 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8d77ebea20acb12bfc6f9e7848a809a17d993df98604ec9b457433ddf211437d
-  data.tar.gz: b7bdcdf3d68df5a5f385a252926319b6ffb2154b3bb431507d63fb3fe64f255e
+  metadata.gz: a165b5a9b594d4eec52f9a7c80ee3cc020db7925ac7630ddc342a552a3a20112
+  data.tar.gz: c9cedd555a12b366f00bf4fa43906501bd6596a8abd3db2531b457d3083bd093
 SHA512:
-  metadata.gz: 9cc0287a91eb60e17f4a6047574a88bf813dbe39ddf345738d3aacadd8a171ed3540e2e7f1004c987c45a5abd3afdfe83407cec276f08ede0a612a76fd0509da
-  data.tar.gz: ada0c1d9c123abacc5688a787229a0c578d2b3c59b7dbd7fe2c944e990a9eb2ffa3de4842e43b22b3eb0521683a8c1f7ccfd5221be35df9f6d36ee16e3e33914
+  metadata.gz: 5816b73d736aa8570fbdf3eed10ba2424e0dc138ac823bd37577cda99b42ac5c120556ac34b60cb645d08206a0214bd5b9a36bd8b25fae829791c522c2586ccf
+  data.tar.gz: d5c2d51e17041f290616eb45a4be80acd5e33b6a6b4e59a801462a3d7bfaccb453633c8e921a2d615136ac784b20fa92436fa73cf664ba4bcf6eaa807ab6ec7e

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

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

metadata

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