@shd101wyy/yo 0.1.30 → 0.1.32

package/std/sync/channel.yo

@@ -23,6 +23,7 @@ pragma(Pragma.AllowUnsafe);
 { malloc, free } :: GlobalAllocator;
 { Mutex } :: import("./mutex");
 { Cond } :: import("./cond");
+{ AtomicBool, AtomicUsize, MemoryOrder } :: import("./atomic");
 /// Thread-safe bounded channel for passing values between threads.
 /// Uses atomic reference counting — implements `Send` and can be
 /// safely shared across threads without `Arc` wrapping.
@@ -32,12 +33,12 @@ Channel :: (fn(comptime(T) : Type, where(T <: Send)) -> comptime(Type))(
     object(
       _data : *(T),
       _head : usize,
-      _len : usize,
+      _len : AtomicUsize,
       _capacity : usize,
-      _mutex : Mutex,
+      _mutex : Mutex(bool),
       _not_empty : Cond,
       _not_full : Cond,
-      _closed : bool
+      _closed : AtomicBool
     )
   )
 );
@@ -54,12 +55,12 @@ impl(
       Self(
         _data : ptr,
         _head : usize(0),
-        _len : usize(0),
+        _len : AtomicUsize(usize(0)),
         _capacity : capacity,
-        _mutex : Mutex.new(),
+        _mutex : Mutex(bool).new(false),
         _not_empty : Cond.new(),
         _not_full : Cond.new(),
-        _closed : false
+        _closed : AtomicBool(false)
       )
     );
   }),
@@ -67,38 +68,45 @@ impl(
   /// Blocks if the channel is full until space becomes available.
   /// Returns .Ok(()) on success, .Err(()) if the channel is closed.
   send : (fn(self : Self, value : T) -> Result(unit, unit))({
-    self._mutex.lock();
+    self._mutex._raw_lock();
     // Wait while buffer is full and channel is not closed
-    while(runtime((self._len >= self._capacity) && (!(self._closed))), {
-      self._not_full.wait(self._mutex);
+    while(runtime(
+      (self._len.load(MemoryOrder.Relaxed) >= self._capacity)
+      && (!(self._closed.load(MemoryOrder.Relaxed)))
+    ), {
+      self._not_full.wait(self._mutex._raw_handle_ptr());
     });
     cond(
-      self._closed => {
-        self._mutex.unlock();
+      self._closed.load(MemoryOrder.Relaxed) => {
+        self._mutex._raw_unlock();
         return(.Err(()));
       },
       true => ()
     );
     // Write value at tail position
-    (tail : usize) = ((self._head + self._len) % self._capacity);
+    (current_len : usize) = self._len.load(MemoryOrder.Relaxed);
+    (tail : usize) = ((self._head + current_len) % self._capacity);
     consume((self._data &+ tail).* = value);
-    self._len = (self._len + usize(1));
+    self._len.store(current_len + usize(1), MemoryOrder.Release);
     self._not_empty.signal();
-    self._mutex.unlock();
+    self._mutex._raw_unlock();
     return(.Ok(()));
   }),
   /// Receive a value from the channel.
   /// Blocks if the channel is empty until a value is available.
   /// Returns .Some(value) on success, .None if the channel is closed and empty.
   recv : (fn(self : Self) -> ?(T))({
-    self._mutex.lock();
+    self._mutex._raw_lock();
     // Wait while buffer is empty and channel is not closed
-    while(runtime((self._len == usize(0)) && (!(self._closed))), {
-      self._not_empty.wait(self._mutex);
+    while(runtime(
+      (self._len.load(MemoryOrder.Relaxed) == usize(0))
+      && (!(self._closed.load(MemoryOrder.Relaxed)))
+    ), {
+      self._not_empty.wait(self._mutex._raw_handle_ptr());
     });
     cond(
-      (self._len == usize(0)) => {
-        self._mutex.unlock();
+      (self._len.load(MemoryOrder.Relaxed) == usize(0)) => {
+        self._mutex._raw_unlock();
         return(.None);
       },
       true => ()
@@ -108,36 +116,40 @@ impl(
     (val : T) = element_ptr.*;
     unsafe.drop(element_ptr.*);
     self._head = ((self._head + usize(1)) % self._capacity);
-    self._len = (self._len - usize(1));
+    self._len.store(self._len.load(MemoryOrder.Relaxed) - usize(1), MemoryOrder.Release);
     self._not_full.signal();
-    self._mutex.unlock();
+    self._mutex._raw_unlock();
     return(.Some(val));
   }),
   /// Try to send a value without blocking.
   /// Returns .Ok(()) if sent, .Err(()) if full or closed.
   try_send : (fn(self : Self, value : T) -> Result(unit, unit))({
-    self._mutex.lock();
+    self._mutex._raw_lock();
     cond(
-      (self._closed || (self._len >= self._capacity)) => {
-        self._mutex.unlock();
+      (
+        self._closed.load(MemoryOrder.Relaxed)
+        || (self._len.load(MemoryOrder.Relaxed) >= self._capacity)
+      ) => {
+        self._mutex._raw_unlock();
         return(.Err(()));
       },
       true => ()
     );
-    (tail : usize) = ((self._head + self._len) % self._capacity);
+    (current_len : usize) = self._len.load(MemoryOrder.Relaxed);
+    (tail : usize) = ((self._head + current_len) % self._capacity);
     consume((self._data &+ tail).* = value);
-    self._len = (self._len + usize(1));
+    self._len.store(current_len + usize(1), MemoryOrder.Release);
     self._not_empty.signal();
-    self._mutex.unlock();
+    self._mutex._raw_unlock();
     return(.Ok(()));
   }),
   /// Try to receive a value without blocking.
   /// Returns .Some(value) if available, .None if empty.
   try_recv : (fn(self : Self) -> ?(T))({
-    self._mutex.lock();
+    self._mutex._raw_lock();
     cond(
-      (self._len == usize(0)) => {
-        self._mutex.unlock();
+      (self._len.load(MemoryOrder.Relaxed) == usize(0)) => {
+        self._mutex._raw_unlock();
         return(.None);
       },
       true => ()
@@ -146,32 +158,34 @@ impl(
     (val : T) = element_ptr.*;
     unsafe.drop(element_ptr.*);
     self._head = ((self._head + usize(1)) % self._capacity);
-    self._len = (self._len - usize(1));
+    self._len.store(self._len.load(MemoryOrder.Relaxed) - usize(1), MemoryOrder.Release);
     self._not_full.signal();
-    self._mutex.unlock();
+    self._mutex._raw_unlock();
     return(.Some(val));
   }),
   /// Close the channel. No more values can be sent.
   /// Pending recv() calls will return .None once the buffer is drained.
   /// Pending send() calls will return .Err(()).
   close : (fn(self : Self) -> unit)({
-    self._mutex.lock();
-    self._closed = true;
+    self._mutex._raw_lock();
+    self._closed.store(true, MemoryOrder.Release);
     self._not_empty.broadcast();
     self._not_full.broadcast();
-    self._mutex.unlock();
+    self._mutex._raw_unlock();
   }),
-  /// Check if the channel is closed.
+  /// Check if the channel is closed (lock-free atomic load).
   is_closed : (fn(self : Self) -> bool)(
-    self._closed
+    self._closed.load(MemoryOrder.Acquire)
   ),
-  /// Return the number of values currently buffered.
+  /// Return the number of values currently buffered (lock-free atomic load).
+  /// Snapshot semantics: the value may be stale by the time the caller acts on it,
+  /// matching Rust's `mpsc::channel` idiom.
   len : (fn(self : Self) -> usize)(
-    self._len
+    self._len.load(MemoryOrder.Acquire)
   ),
-  /// Check if the channel buffer is empty.
+  /// Check if the channel buffer is empty (lock-free atomic load).
   is_empty : (fn(self : Self) -> bool)(
-    self._len == usize(0)
+    self._len.load(MemoryOrder.Acquire) == usize(0)
   )
 );
 // Dispose: drop remaining elements and free the buffer
@@ -181,8 +195,9 @@ impl(
   where(T <: Send),
   Dispose(
     dispose : (fn(self : Self) -> unit)({
+      (current_len : usize) = self._len.load(MemoryOrder.Relaxed);
       (i : usize) = usize(0);
-      while(runtime(i < self._len), {
+      while(runtime(i < current_len), {
         (idx : usize) = ((self._head + i) % self._capacity);
         unsafe.drop((self._data &+ idx).*);
         i = (i + usize(1));

package/std/sync/cond.yo

@@ -1,6 +1,6 @@
 //! Condition variable for thread synchronization.
 pragma(Pragma.AllowUnsafe);
-{ __YO_THREAD_SYNC_TYPE, mutex_t, Mutex } :: import("./mutex");
+{ __YO_THREAD_SYNC_TYPE, mutex_t } :: import("./mutex");
 extern(
   "Yo",
   __YO_COND_TYPE : Type,
@@ -10,6 +10,10 @@ extern(
   __yo_cond_broadcast : (fn(cv : *(__YO_COND_TYPE)) -> unit),
   __yo_cond_destroy : (fn(cv : *(__YO_COND_TYPE)) -> unit)
 );
+// SAFETY: __YO_COND_TYPE is an opaque C-level condition variable
+// (pthread_cond_t or equivalent). It carries its own internal
+// synchronization and is designed to be shared across threads. It is
+// trivially Acyclic — opaque C types don't participate in ARC.
 impl(__YO_COND_TYPE, Send());
 impl(__YO_COND_TYPE, Acyclic());
 /// Low-level condition variable (manual lifetime via `destroy`).
@@ -46,8 +50,8 @@ impl(
   new : (fn() -> Self)({
     return(Self(__yo_cond_create()));
   }),
-  wait : (fn(self : Self, mutex : Mutex) -> unit)({
-    return(__yo_cond_wait(&(self.cv), &(mutex.mutex)));
+  wait : (fn(self : Self, handle : *(__YO_THREAD_SYNC_TYPE)) -> unit)({
+    return(__yo_cond_wait(&(self.cv), handle));
   }),
   signal : (fn(self : Self) -> unit)({
     return(__yo_cond_signal(&(self.cv)));

package/std/sync/mutex.yo

@@ -1,5 +1,12 @@
 //! Mutual exclusion lock primitives.
+//!
+//! Phase D (THREAD_SAFETY): Mutex parameterized over the protected data.
+//! Access is granted via `with_lock(closure)` — the closure receives a
+//! `ref(v): T` that is second-class (cannot escape the closure scope).
+//! The private `__MutexUnlocker` handles unlock on both normal return
+//! and unwind via its `Drop`.
 pragma(Pragma.AllowUnsafe);
+
 extern(
   "Yo",
   __YO_THREAD_SYNC_TYPE : Type,
@@ -8,8 +15,13 @@ extern(
   __yo_mutex_unlock : (fn(mutex : *(__YO_THREAD_SYNC_TYPE)) -> unit),
   __yo_mutex_destroy : (fn(mutex : *(__YO_THREAD_SYNC_TYPE)) -> unit)
 );
+// SAFETY: __YO_THREAD_SYNC_TYPE is an opaque C-level synchronization
+// primitive (pthread_mutex_t or equivalent). It carries its own internal
+// synchronization and is designed to be shared across threads. It is
+// trivially Acyclic — opaque C types don't participate in ARC.
 impl(__YO_THREAD_SYNC_TYPE, Send());
 impl(__YO_THREAD_SYNC_TYPE, Acyclic());
+
 /// Low-level mutex (manual lifetime via `destroy`).
 mutex_t :: newtype(
   mutex : __YO_THREAD_SYNC_TYPE
@@ -29,35 +41,83 @@ impl(
     return(__yo_mutex_destroy(&(self.mutex)));
   })
 );
-/// Reference-counted mutex with automatic cleanup via `Dispose`.
-/// Uses atomic reference counting for safe cross-thread sharing.
-Mutex :: atomic(
+
+// ============================================================================
+// Mutex(T) — atomic-object mutex wrapper with closure-scoped lock API
+// ============================================================================
+Mutex :: (fn(comptime(T) : Type, where(T <: Send)) -> comptime(Type))(
+  atomic(
+    object(
+      _handle : __YO_THREAD_SYNC_TYPE,
+      _value : T
+    )
+  )
+);
+
+// __MutexUnlocker — private object that calls _raw_unlock on Drop.
+// Allocated locally inside with_lock; Yo's drop-on-scope-exit and
+// drop-on-unwind machinery guarantees unlock under both normal return
+// and unwind(...).
+__MutexUnlocker :: (fn(comptime(T) : Type, where(T <: Send)) -> comptime(Type))(
   object(
-    mutex : __YO_THREAD_SYNC_TYPE
+    _mutex : Mutex(T)
   )
 );
 impl(
-  Mutex,
-  new : (fn() -> Self)({
-    return(Self(__yo_mutex_create()));
+  forall(T : Type),
+  where(T <: Send),
+  __MutexUnlocker(T),
+  Dispose(
+    dispose : (fn(self : Self) -> unit)({
+      self._mutex._raw_unlock();
+    })
+  )
+);
+
+impl(
+  forall(T : Type),
+  where(T <: Send),
+  Mutex(T),
+  new : (fn(value : T) -> Self)({
+    return(Self(__yo_mutex_create(), value));
   }),
-  lock : (fn(self : Self) -> unit)({
-    return(__yo_mutex_lock(&(self.mutex)));
+  with_lock : (
+    fn(
+      forall(R : Type),
+      self : Self,
+      body : Impl(Fn(ref(v) : T) -> R)
+    ) -> R
+  )({
+    self._raw_lock();
+    _guard := __MutexUnlocker(T)(self);
+    body(self._value)
   }),
-  unlock : (fn(self : Self) -> unit)({
-    return(__yo_mutex_unlock(&(self.mutex)));
-  })
+  // Internal methods — pragma-only. These are public to the module system
+  // but the _-prefixed naming convention signals "internal API".
+  _raw_lock : (fn(self : Self) -> unit)(
+    __yo_mutex_lock(&(self._handle))
+  ),
+  _raw_unlock : (fn(self : Self) -> unit)(
+    __yo_mutex_unlock(&(self._handle))
+  ),
+  _raw_handle_ptr : (fn(ref(self) : Self) -> *(__YO_THREAD_SYNC_TYPE))(
+    &(self._handle)
+  )
 );
 impl(
-  Mutex,
+  forall(T : Type),
+  where(T <: Send),
+  Mutex(T),
   Dispose(
     dispose : (fn(self : Self) -> unit)({
-      return(__yo_mutex_destroy(&(self.mutex)));
+      return(__yo_mutex_destroy(&(self._handle)));
     })
   )
 );
+
 export(
   __YO_THREAD_SYNC_TYPE,
   mutex_t,
-  Mutex
+  Mutex,
+  __MutexUnlocker
 );

package/std/sync/once.yo

@@ -1,4 +1,5 @@
 //! One-time initialization primitive.
+pragma(Pragma.AllowUnsafe);
 //!
 //! # Example
 //!
@@ -15,43 +16,48 @@
 //! });
 //! ```
 { Mutex } :: import("./mutex");
+{ AtomicBool, MemoryOrder } :: import("./atomic");
+{
+  atomic_bool,
+  atomic_load_explicit,
+  atomic_store_explicit,
+  memory_order_relaxed,
+  memory_order_acquire,
+  memory_order_release
+} :: import("std/libc/stdatomic");
 /// Execute a function exactly once, thread-safely.
 /// Uses atomic reference counting for safe cross-thread sharing.
 Once :: atomic(
   object(
-    _done : bool,
-    _mutex : Mutex
+    _done : atomic_bool,
+    _mutex : Mutex(bool)
   )
 );
 impl(
   Once,
   // Create a new Once.
-  new : (fn() -> Self)(
-    Self(
-      _done : false,
-      _mutex : Mutex.new()
-    )
-  ),
+  new : (fn() -> Self)({
+    v := Self(false, Mutex(bool).new(false));
+    unsafe(atomic_store_explicit(&(v._done), false, memory_order_release));
+    v
+  }),
   // Execute the function exactly once.
   // Subsequent calls are no-ops.
-  // Note: The fast-path read of _done is not strictly atomic, but since _done
-  // is only ever set from false to true and the double-check inside the lock
-  // prevents the function from running twice, this is safe in practice.
   call : (fn(self : Self, f : Impl(Fn() -> unit)) -> unit)({
-    // Fast path: already done
+    // Fast path: already done (atomic_bool with Acquire load)
     cond(
-      self._done => (),
+      (unsafe(atomic_load_explicit(&(self._done), memory_order_acquire)) == true) => (),
       true => {
-        self._mutex.lock();
+        self._mutex._raw_lock();
         // Double-check after acquiring lock
         cond(
-          self._done => {
-            self._mutex.unlock();
+          (unsafe(atomic_load_explicit(&(self._done), memory_order_relaxed)) == true) => {
+            self._mutex._raw_unlock();
           },
           true => {
             f();
-            self._done = true;
-            self._mutex.unlock();
+            unsafe(atomic_store_explicit(&(self._done), true, memory_order_release));
+            self._mutex._raw_unlock();
           }
         );
       }
@@ -59,7 +65,7 @@ impl(
   }),
   // Check if the function has been called.
   is_done : (fn(self : Self) -> bool)(
-    self._done
+    unsafe(atomic_load_explicit(&(self._done), memory_order_acquire)) == true
   )
 );
 export(Once);

package/std/sync/rwlock.yo

@@ -1,4 +1,5 @@
 //! Reader-writer lock allowing multiple concurrent readers or one exclusive writer.
+pragma(Pragma.AllowUnsafe);
 //!
 //! # Example
 //!
@@ -24,7 +25,7 @@ RwLock :: atomic(
   object(
     _readers : i32,
     _writer : bool,
-    _mutex : Mutex,
+    _mutex : Mutex(bool),
     _read_cv : Cond,
     _write_cv : Cond
   )
@@ -36,7 +37,7 @@ impl(
     Self(
       _readers : i32(0),
       _writer : false,
-      _mutex : Mutex.new(),
+      _mutex : Mutex(bool).new(false),
       _read_cv : Cond.new(),
       _write_cv : Cond.new()
     )
@@ -44,39 +45,41 @@ impl(
   // Acquire a read lock. Blocks if a writer holds the lock.
   // Multiple readers can hold the lock simultaneously.
   read_lock : (fn(self : Self) -> unit)({
-    self._mutex.lock();
+    self._mutex._raw_lock();
     while(runtime(self._writer), {
-      self._read_cv.wait(self._mutex);
+      self._read_cv.wait(self._mutex._raw_handle_ptr());
     });
     self._readers = (self._readers + i32(1));
-    self._mutex.unlock();
+    self._mutex._raw_unlock();
   }),
   // Release a read lock.
   read_unlock : (fn(self : Self) -> unit)({
-    self._mutex.lock();
+    self._mutex._raw_lock();
     self._readers = (self._readers - i32(1));
     cond(
       (self._readers == i32(0)) => self._write_cv.signal(),
       true => ()
     );
-    self._mutex.unlock();
+    self._mutex._raw_unlock();
   }),
-  // Acquire a write lock. Blocks until all readers and writers release.
+  // Acquire a write lock. Blocks if readers or a writer hold the lock.
   write_lock : (fn(self : Self) -> unit)({
-    self._mutex.lock();
+    self._mutex._raw_lock();
     while(runtime(self._writer || (self._readers > i32(0))), {
-      self._write_cv.wait(self._mutex);
+      self._write_cv.wait(self._mutex._raw_handle_ptr());
     });
     self._writer = true;
-    self._mutex.unlock();
+    self._mutex._raw_unlock();
   }),
   // Release a write lock.
   write_unlock : (fn(self : Self) -> unit)({
-    self._mutex.lock();
+    self._mutex._raw_lock();
     self._writer = false;
-    self._read_cv.broadcast();
-    self._write_cv.signal();
-    self._mutex.unlock();
+    cond(
+      (self._readers > i32(0)) => self._read_cv.broadcast(),
+      true => self._write_cv.signal()
+    );
+    self._mutex._raw_unlock();
   })
 );
 export(RwLock);

package/std/sync/waitgroup.yo

@@ -1,4 +1,5 @@
 //! Wait for a group of tasks to complete, similar to Go's `sync.WaitGroup`.
+pragma(Pragma.AllowUnsafe);
 //!
 //! # Example
 //!
@@ -20,12 +21,18 @@
 //! ```
 { Mutex } :: import("./mutex");
 { Cond } :: import("./cond");
+{ AtomicI32, MemoryOrder } :: import("./atomic");
 /// Synchronization primitive that blocks until a counter reaches zero.
 /// Uses atomic reference counting for safe cross-thread sharing.
+///
+/// The internal counter is an atomic so `count()` can read without
+/// acquiring the mutex (matches Rust's mpsc query-method idiom). Writes
+/// to the counter still happen under the mutex so the `_count == 0`
+/// observation that triggers `broadcast()` is serialized with `wait()`.
 WaitGroup :: atomic(
   object(
-    _count : i32,
-    _mutex : Mutex,
+    _count : AtomicI32,
+    _mutex : Mutex(bool),
     _cv : Cond
   )
 );
@@ -34,24 +41,26 @@ impl(
   // Create a new WaitGroup with count 0.
   new : (fn() -> Self)(
     Self(
-      _count : i32(0),
-      _mutex : Mutex.new(),
+      _count : AtomicI32(i32(0)),
+      _mutex : Mutex(bool).new(false),
       _cv : Cond.new()
     )
   ),
   // Add delta to the counter (can be negative).
   // If the counter becomes zero, all waiters are woken.
   add : (fn(self : Self, delta : i32) -> unit)({
-    self._mutex.lock();
-    self._count = (self._count + delta);
+    self._mutex._raw_lock();
+    new_count := (self._count.load(MemoryOrder.Relaxed) + delta);
     cond(
-      (self._count <= i32(0)) => {
-        self._count = i32(0);
+      (new_count <= i32(0)) => {
+        self._count.store(i32(0), MemoryOrder.Release);
         self._cv.broadcast();
       },
-      true => ()
+      true => {
+        self._count.store(new_count, MemoryOrder.Release);
+      }
     );
-    self._mutex.unlock();
+    self._mutex._raw_unlock();
   }),
   // Decrement the counter by one (equivalent to add(-1)).
   done : (fn(self : Self) -> unit)(
@@ -59,15 +68,15 @@ impl(
   ),
   // Block until the counter reaches zero.
   wait : (fn(self : Self) -> unit)({
-    self._mutex.lock();
-    while(runtime(self._count > i32(0)), {
-      self._cv.wait(self._mutex);
+    self._mutex._raw_lock();
+    while(runtime(self._count.load(MemoryOrder.Acquire) > i32(0)), {
+      self._cv.wait(self._mutex._raw_handle_ptr());
     });
-    self._mutex.unlock();
+    self._mutex._raw_unlock();
   }),
-  // Get the current count (for debugging).
+  // Get the current count (lock-free atomic load).
   count : (fn(self : Self) -> i32)(
-    self._count
+    self._count.load(MemoryOrder.Acquire)
   )
 );
 export(WaitGroup);