nomen-lang 0.4.0 → 0.6.0

package/core/System/Fiber.nm

@@ -0,0 +1,201 @@
+// Fiber — a stackful coroutine (ASYNC.md Phase 1). Fibers multiplex
+// over the worker pool's threads: a parked fiber frees its worker instead of
+// blocking it, so thousands of waiting tasks cost stacks (~64 KB each), not
+// threads (~MB each).
+//
+// `Fiber(fn(args)).start()` mirrors `Thread(fn(args)).start()` — same eager
+// arg packing into a task closure, same future, same Task<T> handle — but
+// the wrapped call runs on a fiber stack under the fiber scheduler. While
+// it waits (Task.result/wait, Channel.receive), the fiber parks and the
+// worker moves on; `Fiber.yield()` cooperatively hands the worker to the
+// next runnable fiber.
+//
+// Like Thread, a Fiber construction is a real value: it can be stored and
+// started later (`var f = Fiber(work(n))`, then `f.start()` or
+// `f.start_on(buf)`), and destroying an unstarted Fiber is a programming
+// error that #destroy reports and aborts on (must-start — the library
+// pattern from ASYNC.md).
+//
+// `Fiber(fn(args)).start_on(buf)` runs the fiber on a caller-provided
+// fixed-size array stack (>= 16 KB) — the embedded/no-heap path.
+//
+// `Fiber.set_cooperative(true)` (before the first spawn) runs fibers on the
+// calling thread and never starts worker threads — a cooperative,
+// single-threaded runtime for bare-metal targets.
+//
+// The constructor and `.start_on(buf)` are compiler-special-cased (they
+// need the per-site spawn/trampoline machinery and the buffer's compile-time
+// byte size); `.start()` is a regular method over the runtime seam — it
+// reads the packed handles from the instance's fields and drives the
+// scheduler. The runtime (scheduler, context switch) lives in the build's
+// emitted companion C — see build_fiber_spawn.
+
+// The launch surface's return type (ASYNC.md: the dependency is
+// declared by the library file, not inferred from user-source tokens).
+import Task
+
+/**
+ * A stackful coroutine: lightweight, cooperatively scheduled, parks instead of blocking
+ **/
+pub class Fiber<T> : Sendable, Spawnable<T> {
+	// The construction hook (see Thread.nm): the deferred-call special form.
+	#spawn = () {
+	}
+
+	// The packed task closure (a `struct nomen_closure *`); owned by this
+	// value until start/start_on/nursery.start transfers it to the runtime.
+	pub var uint64 task = 0
+	// Result-slot / cancel-flag / future handles for the (single) launch.
+	pub var uint64 result_slot = 0
+	pub var uint64 cancel_flag = 0
+	pub var uint64 future = 0
+	// Must-start flag: set by .start() / .start_on(buf) / nursery.start.
+	pub var started = false
+	// LEXICAL NURSERY CAPTURE (ASYNC.md): the tracking slots of the
+	// `async` block that lexically encloses the CONSTRUCTION, or 0 when the
+	// construction is outside any block. `.start()` registers the future
+	// through these stored pointers — registration follows the scope that
+	// created the deferred call, not the one that happens to start it. See
+	// Thread.nm's matching fields.
+	pub var uint64 nursery_futures = 0
+	pub var uint64 nursery_count = 0
+	pub var uint64 nursery_cap = 0
+
+	// Start the deferred call on the fiber scheduler and yield the Task<T>
+	// handle. Same shape as Thread.start: consume the machinery, register
+	// with the construction-time nursery (if captured), transfer the handles
+	// out of the instance (started; #destroy no-ops), return the handle.
+	// While the fiber waits, it parks and frees its worker instead of
+	// blocking it.
+	pub func start = (ref self, move out Task<T>) {
+		```
+		#arch: c
+		struct nomen_future *_f = (struct nomen_future *)self->future;
+		_f->refs = self->nursery_futures ? 3 : 2;
+		__nomen_fiber_spawn((struct nomen_closure *)self->task, _f);
+		if (self->nursery_futures) {
+			__nomen_nursery_track((void **)self->nursery_futures, (int *)self->nursery_count, (int *)self->nursery_cap, _f);
+		}
+		```
+		```
+		#arch: aarch64
+		// x19 = self. f = self->future (#32); nursery_futures at #48.
+		ldr x0, [x19, #32]
+		ldr x1, [x19, #48]
+		mov w2, #2
+		cbz x1, .Lnomen_fstart_refs
+		mov w2, #3
+		.Lnomen_fstart_refs:
+		str w2, [x0, #116]
+		// __nomen_fiber_spawn(self->task, f)
+		ldr x0, [x19, #8]
+		ldr x1, [x19, #32]
+		bl ___nomen_fiber_spawn
+		// if (self->nursery_futures) __nomen_nursery_track(futures, count, cap, f)
+		ldr x0, [x19, #48]
+		cbz x0, .Lnomen_fstart_notrack
+		ldr x1, [x19, #56]
+		ldr x2, [x19, #64]
+		ldr x3, [x19, #32]
+		bl ___nomen_nursery_track
+		.Lnomen_fstart_notrack:
+		```
+		var t = Task<T>()
+		t.result_slot = self.result_slot
+		t.cancel_flag = self.cancel_flag
+		t.future = self.future
+		// Transfer the handles out of the instance: the runtime owns
+		// everything now, and #destroy must not touch (or must-start-abort).
+		self.task = 0
+		self.future = 0
+		self.result_slot = 0
+		self.cancel_flag = 0
+		self.started = true
+		return t
+	}
+
+	// Run the deferred call fire-and-forget (the Spawnable daemon role).
+	// The fiber is launched exactly like start, but the handle is dropped
+	// immediately: the future's refs are released as the discarded Task is
+	// reclaimed, and the fiber completes into the void — nothing joins it.
+	pub func detach = (ref self) {
+		self.start()
+	}
+
+	// Destroying an unstarted Fiber is a programming error (the wrapped
+	// call would silently never run) — report it and abort. A started
+	// Fiber owns nothing: the launch transferred the task closure, result
+	// slot, cancel flag, and future to the runtime, and cleared the fields.
+	pub func #destroy = () {
+		```
+		#arch: c
+		if (!self->started) {
+			__nomen_spawn_must_start_abort();
+		}
+		if (self->future) {
+			__nomen_future_release((struct nomen_future *)self->future);
+			self->future = 0;
+			self->result_slot = 0;
+			self->cancel_flag = 0;
+		}
+		```
+		```
+		#arch: aarch64
+		// if (!self->started) __nomen_spawn_must_start_abort()
+		ldrb w0, [x19, #40]
+		cbnz w0, .Lfb_started
+		bl ___nomen_spawn_must_start_abort
+		.Lfb_started:
+		// if (self->future) { release it (an unstarted task's future is
+		// unshared — refs == 1 — so this tears down slot + flag + future);
+		// zero the fields }
+		ldr x0, [x19, #32]
+		cbz x0, .Lfb_done
+		bl ___nomen_future_release
+		str xzr, [x19, #32]
+		str xzr, [x19, #16]
+		str xzr, [x19, #24]
+		.Lfb_done:
+		```
+	}
+
+	// Hand the worker to the next runnable fiber. No-op outside a fiber.
+	pub func yield = () {
+		```
+		#arch: c
+		__nomen_fiber_yield();
+		```
+		```
+		#arch: aarch64
+		bl ___nomen_fiber_yield
+		```
+	}
+
+	// Is the calling code running inside a fiber? True when Fiber.yield or
+	// fiber parking would take effect.
+	pub func is_fiber = (out bool) {
+		```
+		#arch: c
+		return __nomen_fiber_is_active();
+		```
+		```
+		#arch: aarch64
+		bl ___nomen_fiber_is_active
+		```
+	}
+
+	// Run fibers on the calling thread and never start worker threads. Must
+	// be called before the first fiber spawn; intended for single-threaded
+	// (bare-metal) targets. In cooperative mode a fiber that parks on an
+	// event only another thread could fire will never resume.
+	pub func set_cooperative = (bool on) {
+		```
+		#arch: c
+		__nomen_fiber_set_cooperative(on ? 1 : 0);
+		```
+		```
+		#arch: aarch64
+		bl ___nomen_fiber_set_cooperative
+		```
+	}
+}

package/core/System/Graph.nm

@@ -7,7 +7,7 @@
  * A graph of values connected by edges
  **/
 pub struct Graph<T>: Enumerable {
-	var Buffer<T> values = Buffer<T>()
+	var values = Buffer<T>()
 	var head_edge = Buffer<int>()
 	var edge_target = Buffer<int>()
 	var edge_next = Buffer<int>()

package/core/System/LinkedList.nm

@@ -7,7 +7,7 @@
  * A doubly-linked list of values
  **/
 pub struct LinkedList<T>: Enumerable {
-	var Buffer<T> values = Buffer<T>()
+	var values = Buffer<T>()
 	var nexts = Buffer<int>()
 	var prevs = Buffer<int>()
 	var int head = -1

package/core/System/List.nm

@@ -3,7 +3,7 @@
  **/
 pub struct List<T>: Viewable {
 	var length = 0
-	var Buffer<T> items = Buffer<T>()
+	var items = Buffer<T>()
 
 	pub func push = (ref self, move T value) {
 		if self.length >= self.items.cap {
@@ -70,8 +70,8 @@ pub struct List<T>: Viewable {
 	// never re-checked, so it can't rely on check-time call-arg hoisting for
 	// struct element types.
 	pub func copy = (self, out List<T>) {
-		var List<T> dst = List<T>()
-		var int i = 0
+		var dst = List<T>()
+		var i = 0
 		while i < self.length {
 			var T v = self.at(i)
 			dst.push(v)

package/core/System/Map.nm

@@ -10,8 +10,8 @@
  **/
 pub struct Map<TK: Hashable + Equatable, TV> {
 	var length = 0
-	var Buffer<TK> keys = Buffer<TK>()
-	var Buffer<TV> values = Buffer<TV>()
+	var keys = Buffer<TK>()
+	var values = Buffer<TV>()
 	var used = Buffer<int>()
 
 	// Variadic-tuple constructor: Map<string, int>(["a", 1], ["b", 2]) or

package/core/System/Mutex.nm

@@ -3,6 +3,12 @@
 // Default stance in Nomen is "no shared mutable state" — communicate by moving
 // Sendable values (or via Channel<T>). Mutex exists for when you genuinely
 // need shared mutability. See ASYNC.md.
+//
+// A fiber that would block on a contended lock parks instead of blocking its
+// worker (both models), and unlock wakes the parked fibers. Cancellation
+// while waiting never returns without the lock — a waiter keeps waiting and
+// observes the cancel flag at its next checkpoint after acquiring — so a
+// matching unlock is always sound.
 
 /**
  * A pthread-backed mutual-exclusion lock for protecting shared mutable state
@@ -11,68 +17,58 @@ pub class Mutex: Sendable {
 	pub var uint64 handle = 0
 
 	pub func #init = (self) {
-		```
-		#arch: c
-		#scope: file
-		#include <pthread.h>
-		```
-		```
-		#arch: c
-		self->handle = (unsigned long long)malloc(sizeof(pthread_mutex_t));
-		pthread_mutex_init((pthread_mutex_t *)self->handle, NULL);
-		```
-		```
-		#arch: aarch64
-		mov x0, #64
-		bl _malloc
-		str x0, [x19, #8]
-		mov x1, #0
-		bl _pthread_mutex_init
-		```
+	```
+	#arch: c
+	self->handle = (unsigned long long)__nomen_mutex_create();
+	```
+	```
+	#arch: aarch64
+	bl ___nomen_mutex_create
+	str x0, [x19, #8]
+	```
 	}
 
 	pub func lock = (self) {
-		```
-		#arch: c
-		pthread_mutex_lock((pthread_mutex_t *)self->handle);
-		```
-		```
-		#arch: aarch64
-		ldr x0, [x19, #8]
-		bl _pthread_mutex_lock
-		```
+	```
+	#arch: c
+	// Fibers park instead of blocking the worker (both models); other
+	// contexts take the pthread lock directly.
+	__nomen_mutex_lock((void *)self->handle);
+	```
+	```
+	#arch: aarch64
+	ldr x0, [x19, #8]
+	bl ___nomen_mutex_lock
+	```
 	}
 
 	pub func unlock = (self) {
-		```
-		#arch: c
-		pthread_mutex_unlock((pthread_mutex_t *)self->handle);
-		```
-		```
-		#arch: aarch64
-		ldr x0, [x19, #8]
-		bl _pthread_mutex_unlock
-		```
+	```
+	#arch: c
+	__nomen_mutex_unlock_wake((void *)self->handle);
+	```
+	```
+	#arch: aarch64
+	ldr x0, [x19, #8]
+	bl ___nomen_mutex_unlock_wake
+	```
 	}
 
 	pub func #destroy = () {
-		```
-		#arch: c
-		if (self->handle) {
-			pthread_mutex_destroy((pthread_mutex_t *)self->handle);
-			free((void *)self->handle);
-			self->handle = 0;
-		}
-		```
-		```
-		#arch: aarch64
-		ldr x0, [x19, #8]
-		cbz x0, .Lmutex_destroy_end
-		bl _pthread_mutex_destroy
-		ldr x0, [x19, #8]
-		bl _free
-		str xzr, [x19, #8]
-		.Lmutex_destroy_end:
-		```
+	```
+	#arch: c
+	if (self->handle) {
+		__nomen_mutex_dispose((void *)self->handle);
+		self->handle = 0;
+	}
+	```
+	```
+	#arch: aarch64
+	ldr x0, [x19, #8]
+	cbz x0, .Lmutex_destroy_end
+	bl ___nomen_mutex_dispose
+	str xzr, [x19, #8]
+	.Lmutex_destroy_end:
+	```
 	}
 }

package/core/System/Nursery.nm

@@ -5,18 +5,19 @@
 // An `async` block names its nursery (`async pool { }`), binding a Nursery
 // variable in scope. That variable is passed to helper functions with `ref`
 // and is the receiver of `pool.spawn(fn(args))`. The Nursery wraps the
-// per-invocation tracking state of the `async { }` block — a pointer to the
-// futures array and a pointer to the count slot, both on the async block's
-// stack frame — so it is only valid for the lifetime of its enclosing block
-// (which is exactly the structured-concurrency invariant: the block cannot
-// exit until every spawned task, including those spawned through a passed
-// Nursery, has finished).
+// per-invocation tracking state of the `async { }` block — pointers to the
+// futures list's storage slot, the registered count, and the capacity (the
+// list starts empty and grows by realloc; the compiler's registration helper
+// writes through these pointers) — so it is only valid for the lifetime of
+// its enclosing block (which is exactly the structured-concurrency
+// invariant: the block cannot exit until every spawned task, including those
+// spawned through a passed Nursery, has finished).
 //
 // Config rides on the declaration: `async pool = Nursery(timeout: 2000) { }`.
 //
 // `name.spawn(fn(args))` is special-cased by the compiler (it needs the spawn
-// trampoline machinery), so it is NOT a regular method declared here. The two
-// fields are the full runtime contract.
+// trampoline machinery), so it is NOT a regular method declared here. The
+// three fields are the full runtime contract.
 
 /**
  * The capability for spawning into a caller's `async` block; owns and tracks its tasks
@@ -24,4 +25,5 @@
 pub struct Nursery: Sendable {
 	pub var uint64 futures_ptr = 0
 	pub var uint64 count_ptr = 0
+	pub var uint64 cap_ptr = 0
 }

package/core/System/Option.nm

@@ -1,4 +1,4 @@
 pub enum Option<T> {
-    case some(T value)
-    case none
+	case some(T value)
+	case none
 }

package/core/System/Random.nm

@@ -0,0 +1,67 @@
+// Random — a small, fast pseudo-random generator (splitmix64).
+//
+// Splitmix64 steps a 64-bit state by the golden ratio, then runs two
+// multiply-xor rounds. Streams from nearby seeds are fully decorrelated
+// (each seed is its own stream), so `Random()` — seeded from the wall
+// clock — is safe to construct repeatedly in quick succession (e.g. one
+// per spawned task, all starting within the same microsecond).
+//
+// Not cryptographically secure; `below`/`range` have slight modulo bias
+// for very large bounds.
+//
+//	var Random rng = Random()
+//	var uint64 roll = rng.below(6)          // 0..5
+//	var uint64 ms = rng.range(1000, 10000)  // 1000..10000, inclusive
+//
+import Time
+
+/**
+ * A fast splitmix64 pseudo-random number generator
+ **/
+pub class Random {
+	// The raw 64-bit generator state (seeded from the wall clock by the
+	// no-arg constructor, or an explicit seed for reproducible sequences).
+	pub var uint64 state = 0
+
+	// Seed from the wall clock (nanoseconds since the epoch).
+	pub func #init = (self) {
+		self.state = Time.now_ns()
+	}
+
+	// Seed from an explicit value — reproducible sequences for tests.
+	pub func #init = (self, uint64 seed) {
+		self.state = seed
+	}
+
+	// The next 64-bit value (splitmix64: golden-ratio step, then two
+	// multiply-xor rounds). Pure Nomen — the 64-bit arithmetic, bitwise
+	// operators, and hex literals all lower directly. The aarch64 codegen is
+	// a little looser than a hand-written `#arch` body would be (constant
+	// materialization, field reloads, non-immediate shift counts); see
+	// FOLLOWUP.md if this ever needs to be hot.
+	pub func next = (ref self, out uint64) {
+		self.state = self.state + 0x9E3779B97F4A7C15
+		var uint64 z = self.state
+		z = (z ^ (z >> 30)) * 0xBF58476D1CE4E5B9
+		z = (z ^ (z >> 27)) * 0x94D049BB133111EB
+		return z ^ (z >> 31)
+	}
+
+	// The next value in [0, bound). A bound of 0 returns 0. Slight modulo
+	// bias for very large bounds — irrelevant at demo scale.
+	pub func below = (ref self, uint64 bound, out uint64) {
+		if bound == 0 {
+			return 0
+		}
+		return self.next() % bound
+	}
+
+	// The next value in [lo, hi], both ends inclusive. A hi <= lo
+	// returns lo.
+	pub func range = (ref self, uint64 lo, uint64 hi, out uint64) {
+		if hi <= lo {
+			return lo
+		}
+		return lo + self.below(hi - lo + 1)
+	}
+}

package/core/System/Result.nm

@@ -1,4 +1,4 @@
 pub must_use enum Result<T, E> {
-    case ok(T value)
-    case error(E error)
+	case ok(T value)
+	case error(E error)
 }

package/core/System/Set.nm

@@ -9,7 +9,7 @@
  **/
 pub struct Set<T: Hashable + Equatable> {
 	var length = 0
-	var Buffer<T> slots = Buffer<T>()
+	var slots = Buffer<T>()
 	var used = Buffer<int>()
 
 	pub func add = (ref self, move T value) {

package/core/System/Spawnable.nm

@@ -0,0 +1,18 @@
+// Spawnable — the trait role of a deferred-work LAUNCHER (the C# shape;
+// see docs/ASYNC.md, "Design decisions"). A Spawnable class packs a deferred unit of work
+// (the construction special form) and its `start` submits it, yielding the
+// library-owned `Task<T>` handle — so the await half is guaranteed by the
+// return type and each type carries exactly one role: `Thread<T>`/`Fiber<T>`
+// are spawnable, `Task<T>` is awaitable. `Awaitable` stays non-generic (its
+// `wait` does not mention T); `Spawnable` is generic because `start`'s
+// return type does.
+//
+// `detach` is the daemon role: run the work unjoinable, statement only.
+
+/**
+ * A class that can launch a deferred call and hand back its Task<T> handle
+ **/
+pub trait Spawnable<T> {
+	func start = (ref self, move out Task<T>)
+	func detach = (ref self)
+}

package/core/System/Stream/File.nm

@@ -39,7 +39,7 @@ pub struct File {
 	pub var eof = false
 	// errno of the last operation; 0 = success. Raw #arch bodies set it,
 	// the Result-returning wrappers map it to FileError.
-	var int error = 0
+	var error = 0
 
 	// Maps an errno to its FileError case.
 	func error_of = (int err, out FileError) {
@@ -569,7 +569,7 @@ pub struct File {
 	// (static) Read the entire contents of `path` in one open/read/close.
 	pub func read_all = (string path, out Result<string, FileError>) {
 		var Result<string, FileError> result = .error(FileError.other)
-		var File f = File()
+		var f = File()
 		match f.open(path, "r") {
 			case .ok(did) {
 				match f.readAll() {
@@ -594,7 +594,7 @@ pub struct File {
 	// be deliberate).
 	pub func write_all = (string path, string data, out Result<bool, FileError>) {
 		var Result<bool, FileError> result = .error(FileError.other)
-		var File f = File()
+		var f = File()
 		match f.open(path, "w") {
 			case .ok(did) {
 				match f.writeAll(data) {