nomen-lang 0.4.0 → 0.5.0

package/core/System/Stream/Tcp.nm

@@ -0,0 +1,441 @@
+// Tcp — non-blocking sockets for Nomen tasks.
+//
+// Sockets are put in non-blocking mode and every wait goes through the
+// runtime's netpoller hook (`__nomen_io_wait`): inside a Fiber the task parks
+// (freeing its worker) until the socket is readable/writable; on a plain
+// thread the hook blocks in poll(). So the same code scales from a handful of
+// connections to thousands, and no call blocks a shared worker while it
+// waits. See ASYNC.md Phase 3.
+//
+// Raw helpers return file descriptors / error codes (int-shaped), so the
+// class wrappers construct the Tcp instances in Nomen. `error` mirrors
+// Http's convention: 0 = ok, 1 = DNS, 2 = socket, 3 = connect, 4 = listen,
+// 5 = closed.
+//
+//	var Tcp server = Tcp.listen(8080, 128)
+//	async {
+//		var Tcp conn = server.accept()
+//		var bool ok = conn.send("hello")
+//		conn.close()
+//	}
+//
+// The method bodies are C (compiled directly on the C backend, and via the
+// linked companion on aarch64) — OS socket/DNS interop, where hand-written
+// per-target assembly is not practical.
+
+/**
+ * A non-blocking TCP socket whose waits park the calling fiber
+ **/
+pub class Tcp : Sendable {
+	// The underlying file descriptor, -1 when closed/failed.
+	pub var int fd = -1
+	// 0 = ok; 1 = DNS, 2 = socket, 3 = connect, 4 = listen, 5 = closed.
+	pub var int error = 0
+
+	pub func #init = (self, int handle) {
+		self.fd = handle
+		self.error = 0
+	}
+
+	pub func #destroy = () {
+		```
+		#arch: c
+		if (self->fd >= 0) {
+			close(self->fd);
+			self->fd = -1;
+		}
+		```
+		```
+		#arch: aarch64_use_c
+		if (self->fd >= 0) {
+			close(self->fd);
+			self->fd = -1;
+		}
+		```
+	}
+
+	pub func close = (ref self) {
+		Tcp.close_fd(self.fd)
+		self.fd = -1
+	}
+
+	pub func is_open = (self, out bool) => self.fd >= 0
+
+	// ---- listening ----
+
+	// Create a listening socket bound to `port` on all interfaces.
+	pub func listen = (int port, int backlog, move out Tcp) {
+		var int handle = Tcp.listen_fd(port, backlog)
+		var Tcp t = Tcp(handle)
+		if handle < 0 {
+			t.error = 4
+		}
+		return t
+	}
+
+	// Accept the next connection, parking the fiber while the backlog is
+	// empty. The returned socket is -1 if the listener was cancelled or
+	// failed.
+	pub func accept = (ref self, move out Tcp) {
+		var int handle = Tcp.accept_fd(self.fd)
+		var Tcp t = Tcp(handle)
+		if handle < 0 {
+			t.error = 5
+		}
+		return t
+	}
+
+	// ---- connecting ----
+
+	// Connect to `host`:`port`. Check `fd >= 0` (or `error == 0`) for success.
+	pub func connect = (string host, int port, move out Tcp) {
+		var int handle = Tcp.socket_fd()
+		if handle < 0 {
+			var Tcp bad = Tcp(-1)
+			bad.error = 2
+			return bad
+		}
+		var int err = Tcp.connect_to(handle, host, port)
+		if err != 0 {
+			Tcp.close_fd(handle)
+			var Tcp bad = Tcp(-1)
+			bad.error = err
+			return bad
+		}
+		return Tcp(handle)
+	}
+
+	// ---- transferring ----
+
+	// Send every byte of `data`. Parks the fiber while the send buffer is
+	// full. Returns false on error or cancellation.
+	pub func send = (ref self, string data, out bool) {
+		return Tcp.send_all(self.fd, data)
+	}
+
+	// Receive up to `max` bytes. Parks the fiber until data arrives; returns
+	// the empty string at end-of-stream, on error, or when cancelled.
+	pub func recv = (ref self, int max, move out string) {
+		return Tcp.recv_some(self.fd, max)
+	}
+
+	// Receive until the peer closes (how Connection: close HTTP works).
+	pub func recv_all = (ref self, move out string) {
+		return Tcp.recv_until_close(self.fd)
+	}
+
+	// ---- raw helpers (int-shaped, so the wrappers above build the Tcp) ----
+
+	func socket_fd = (out int) {
+		```
+		#arch: c
+		#scope: file
+		#include <sys/socket.h>
+		#include <netdb.h>
+		#include <netinet/in.h>
+		#include <arpa/inet.h>
+		#include <fcntl.h>
+		#include <unistd.h>
+		#include <string.h>
+		#include <stdlib.h>
+		#include <errno.h>
+		#include <stdbool.h>
+		```
+		```
+		#arch: c
+		int handle = socket(AF_INET, SOCK_STREAM, 0);
+		if (handle < 0) return -1;
+		fcntl(handle, F_SETFL, fcntl(handle, F_GETFL, 0) | O_NONBLOCK);
+		return handle;
+		```
+		```
+		#arch: aarch64_use_c
+		#scope: file
+		#include <sys/socket.h>
+		#include <netdb.h>
+		#include <netinet/in.h>
+		#include <arpa/inet.h>
+		#include <fcntl.h>
+		#include <unistd.h>
+		#include <string.h>
+		#include <stdlib.h>
+		#include <errno.h>
+		#include <stdbool.h>
+		```
+		```
+		#arch: aarch64_use_c
+		int handle = socket(AF_INET, SOCK_STREAM, 0);
+		if (handle < 0) return -1;
+		fcntl(handle, F_SETFL, fcntl(handle, F_GETFL, 0) | O_NONBLOCK);
+		return handle;
+		```
+	}
+
+	func listen_fd = (int port, int backlog, out int) {
+		```
+		#arch: c
+		int handle = socket(AF_INET, SOCK_STREAM, 0);
+		if (handle < 0) return -1;
+		int one = 1;
+		setsockopt(handle, SOL_SOCKET, SO_REUSEADDR, &one, sizeof(one));
+		struct sockaddr_in addr;
+		memset(&addr, 0, sizeof(addr));
+		addr.sin_family = AF_INET;
+		addr.sin_addr.s_addr = htonl(INADDR_ANY);
+		addr.sin_port = htons((unsigned short)port);
+		if (bind(handle, (struct sockaddr *)&addr, sizeof(addr)) < 0) {
+			close(handle);
+			return -1;
+		}
+		if (listen(handle, backlog) < 0) {
+			close(handle);
+			return -1;
+		}
+		fcntl(handle, F_SETFL, fcntl(handle, F_GETFL, 0) | O_NONBLOCK);
+		return handle;
+		```
+		```
+		#arch: aarch64_use_c
+		int handle = socket(AF_INET, SOCK_STREAM, 0);
+		if (handle < 0) return -1;
+		int one = 1;
+		setsockopt(handle, SOL_SOCKET, SO_REUSEADDR, &one, sizeof(one));
+		struct sockaddr_in addr;
+		memset(&addr, 0, sizeof(addr));
+		addr.sin_family = AF_INET;
+		addr.sin_addr.s_addr = htonl(INADDR_ANY);
+		addr.sin_port = htons((unsigned short)port);
+		if (bind(handle, (struct sockaddr *)&addr, sizeof(addr)) < 0) {
+			close(handle);
+			return -1;
+		}
+		if (listen(handle, backlog) < 0) {
+			close(handle);
+			return -1;
+		}
+		fcntl(handle, F_SETFL, fcntl(handle, F_GETFL, 0) | O_NONBLOCK);
+		return handle;
+		```
+	}
+
+	func accept_fd = (int listener, out int) {
+		```
+		#arch: c
+		for (;;) {
+			int handle = accept(listener, NULL, NULL);
+			if (handle >= 0) {
+				fcntl(handle, F_SETFL, fcntl(handle, F_GETFL, 0) | O_NONBLOCK);
+				return handle;
+			}
+			if (errno != EAGAIN && errno != EWOULDBLOCK && errno != EINTR) return -1;
+			if (!__nomen_io_wait(listener, 0)) return -1;
+		}
+		```
+		```
+		#arch: aarch64_use_c
+		for (;;) {
+			int handle = accept(listener, NULL, NULL);
+			if (handle >= 0) {
+				fcntl(handle, F_SETFL, fcntl(handle, F_GETFL, 0) | O_NONBLOCK);
+				return handle;
+			}
+			if (errno != EAGAIN && errno != EWOULDBLOCK && errno != EINTR) return -1;
+			if (!__nomen_io_wait(listener, 0)) return -1;
+		}
+		```
+	}
+
+	// Returns 0 on success, or an error code (1 = DNS, 3 = connect).
+	func connect_to = (int handle, string host, int port, out int) {
+		```
+		#arch: c
+		char portstr[16];
+		snprintf(portstr, sizeof(portstr), "%d", port);
+		struct addrinfo hints, *res = NULL;
+		memset(&hints, 0, sizeof(hints));
+		hints.ai_family = AF_INET;
+		hints.ai_socktype = SOCK_STREAM;
+		if (getaddrinfo(host.ptr, portstr, &hints, &res) != 0) return 1;
+		int rc = connect(handle, res->ai_addr, res->ai_addrlen);
+		freeaddrinfo(res);
+		if (rc == 0) return 0;
+		if (errno != EINPROGRESS) return 3;
+		if (!__nomen_io_wait(handle, 1)) return 3;
+		int so_err = 0;
+		socklen_t so_len = sizeof(so_err);
+		if (getsockopt(handle, SOL_SOCKET, SO_ERROR, &so_err, &so_len) < 0) return 3;
+		return so_err == 0 ? 0 : 3;
+		```
+		```
+		#arch: aarch64_use_c
+		char portstr[16];
+		snprintf(portstr, sizeof(portstr), "%d", port);
+		struct addrinfo hints, *res = NULL;
+		memset(&hints, 0, sizeof(hints));
+		hints.ai_family = AF_INET;
+		hints.ai_socktype = SOCK_STREAM;
+		if (getaddrinfo(host.ptr, portstr, &hints, &res) != 0) return 1;
+		int rc = connect(handle, res->ai_addr, res->ai_addrlen);
+		freeaddrinfo(res);
+		if (rc == 0) return 0;
+		if (errno != EINPROGRESS) return 3;
+		if (!__nomen_io_wait(handle, 1)) return 3;
+		int so_err = 0;
+		socklen_t so_len = sizeof(so_err);
+		if (getsockopt(handle, SOL_SOCKET, SO_ERROR, &so_err, &so_len) < 0) return 3;
+		return so_err == 0 ? 0 : 3;
+		```
+	}
+
+	func send_all = (int handle, string data, out bool) {
+		```
+		#arch: c
+		long off = 0;
+		while (off < data.len) {
+			ssize_t n = send(handle, data.ptr + off, (size_t)(data.len - off), 0);
+			if (n > 0) {
+				off += (long)n;
+				continue;
+			}
+			if (errno == EAGAIN || errno == EWOULDBLOCK) {
+				if (!__nomen_io_wait(handle, 1)) return false;
+				continue;
+			}
+			if (errno == EINTR) continue;
+			return false;
+		}
+		return true;
+		```
+		```
+		#arch: aarch64_use_c
+		long off = 0;
+		while (off < data.len) {
+			ssize_t n = send(handle, data.ptr + off, (size_t)(data.len - off), 0);
+			if (n > 0) {
+				off += (long)n;
+				continue;
+			}
+			if (errno == EAGAIN || errno == EWOULDBLOCK) {
+				if (!__nomen_io_wait(handle, 1)) return false;
+				continue;
+			}
+			if (errno == EINTR) continue;
+			return false;
+		}
+		return true;
+		```
+	}
+
+	func recv_some = (int handle, int max, move out string) {
+		```
+		#arch: c
+		long cap = max > 0 ? max : 1;
+		char *buf = (char *)malloc((size_t)cap);
+		for (;;) {
+			ssize_t n = recv(handle, buf, (size_t)cap, 0);
+			if (n > 0) return (nomen_string){ buf, (long)n };
+			if (n == 0) {
+				free(buf);
+				return (nomen_string){ strdup(""), 0 };
+			}
+			if (errno == EAGAIN || errno == EWOULDBLOCK) {
+				if (!__nomen_io_wait(handle, 0)) {
+					free(buf);
+					return (nomen_string){ strdup(""), 0 };
+				}
+				continue;
+			}
+			if (errno == EINTR) continue;
+			free(buf);
+			return (nomen_string){ strdup(""), 0 };
+		}
+		```
+		```
+		#arch: aarch64_use_c
+		long cap = max > 0 ? max : 1;
+		char *buf = (char *)malloc((size_t)cap);
+		for (;;) {
+			ssize_t n = recv(handle, buf, (size_t)cap, 0);
+			if (n > 0) return (nomen_string){ buf, (long)n };
+			if (n == 0) {
+				free(buf);
+				return (nomen_string){ strdup(""), 0 };
+			}
+			if (errno == EAGAIN || errno == EWOULDBLOCK) {
+				if (!__nomen_io_wait(handle, 0)) {
+					free(buf);
+					return (nomen_string){ strdup(""), 0 };
+				}
+				continue;
+			}
+			if (errno == EINTR) continue;
+			free(buf);
+			return (nomen_string){ strdup(""), 0 };
+		}
+		```
+	}
+
+	func recv_until_close = (int handle, move out string) {
+		```
+		#arch: c
+		long cap = 4096, len = 0;
+		char *buf = (char *)malloc((size_t)cap);
+		for (;;) {
+			if (len + 1 >= cap) {
+				cap *= 2;
+				buf = (char *)realloc(buf, (size_t)cap);
+			}
+			ssize_t n = recv(handle, buf + len, (size_t)(cap - len - 1), 0);
+			if (n > 0) {
+				len += (long)n;
+				continue;
+			}
+			if (n == 0) break;
+			if (errno == EAGAIN || errno == EWOULDBLOCK) {
+				if (!__nomen_io_wait(handle, 0)) break;
+				continue;
+			}
+			if (errno == EINTR) continue;
+			break;
+		}
+		buf[len] = 0;
+		return (nomen_string){ buf, len };
+		```
+		```
+		#arch: aarch64_use_c
+		long cap = 4096, len = 0;
+		char *buf = (char *)malloc((size_t)cap);
+		for (;;) {
+			if (len + 1 >= cap) {
+				cap *= 2;
+				buf = (char *)realloc(buf, (size_t)cap);
+			}
+			ssize_t n = recv(handle, buf + len, (size_t)(cap - len - 1), 0);
+			if (n > 0) {
+				len += (long)n;
+				continue;
+			}
+			if (n == 0) break;
+			if (errno == EAGAIN || errno == EWOULDBLOCK) {
+				if (!__nomen_io_wait(handle, 0)) break;
+				continue;
+			}
+			if (errno == EINTR) continue;
+			break;
+		}
+		buf[len] = 0;
+		return (nomen_string){ buf, len };
+		```
+	}
+
+	func close_fd = (int handle) {
+		```
+		#arch: c
+		if (handle >= 0) close(handle);
+		```
+		```
+		#arch: aarch64_use_c
+		if (handle >= 0) close(handle);
+		```
+	}
+}

package/core/System/Task.nm

@@ -14,9 +14,10 @@
 // See ASYNC.md for the design.
 
 /**
- * A handle to an asynchronously-running computation, backed by a shared thread pool
+ * A handle to an asynchronously-running computation, backed by a shared thread pool.
+ * Conforms to `Awaitable`: `.wait()` may park the current execution context.
  **/
-pub class Task<T> : Sendable {
+pub class Task<T> : Sendable, Awaitable {
 	pub var uint64 handle = 0
 	pub var done = false
 	pub var uint64 result_slot = 0
@@ -164,13 +165,23 @@ pub class Task<T> : Sendable {
 	pub func cancel = (ref self) {
 		```
 		#arch: c
-		if (self->cancel_flag) {
+		// Sets the flag and wakes any fiber parked on this task's future, so
+		// a parked task comes back to observe the cancellation.
+		if (self->future) {
+			__nomen_future_cancel((struct nomen_future *)self->future);
+		} else if (self->cancel_flag) {
 			*(unsigned long long *)self->cancel_flag = 1;
 		}
 		```
 		```
 		#arch: aarch64
-		// if (self->cancel_flag) *(self->cancel_flag) = 1
+		// if (self->future) __nomen_future_cancel(self->future);
+		// else if (self->cancel_flag) *(self->cancel_flag) = 1
+		ldr x0, [x19, #40]
+		cbz x0, .Lcancel_flag_path
+		bl ___nomen_future_cancel
+		b .Lcancel_done
+		.Lcancel_flag_path:
 		ldr x0, [x19, #32]
 		cbz x0, .Lcancel_done
 		mov x1, #1
@@ -244,6 +255,94 @@ pub class Task<T> : Sendable {
 		```
 	}
 
+	// ---- User-defined async primitive seam (ASYNC.md, "User-defined async
+	// primitives") ----
+	// The construction sugar stores the packed-task machinery in a user
+	// class's plain uint64 fields (task / result_slot / cancel_flag /
+	// future); these statics are the library boundary its own launch
+	// methods drive the runtime through — the same calls the generated
+	// Thread/Fiber launch code makes, so a user primitive parks fibers,
+	// deadlocks correctly, and frees exactly like a library spawn. The
+	// handles are opaque: the only contract is the field NAMES the sugar
+	// writes and these calls read.
+
+	// Submit a packed task closure (the `task` field's value) to the shared
+	// worker pool. The closure must come from a construction of an
+	// Awaitable-conforming class — it is not callable.
+	pub func pool_submit = (uint64 closure) {
+		```
+		#arch: c
+		__nomen_pool_submit((struct nomen_closure *)(void *)closure);
+		```
+		```
+		#arch: aarch64
+		// x0 = closure
+		bl ___nomen_pool_submit
+		```
+	}
+
+	// Park until the task completes (in a fiber this parks the fiber and
+	// frees its worker; on a raw thread it blocks). Idempotent once done.
+	pub func future_wait = (uint64 future) {
+		```
+		#arch: c
+		__nomen_future_wait((struct nomen_future *)(void *)future);
+		```
+		```
+		#arch: aarch64
+		// x0 = future
+		bl ___nomen_future_wait
+		```
+	}
+
+	// Read the uint64 result the task stored. The launch's ref accounting
+	// must still hold a reference (see future_set_refs) — read BEFORE the
+	// final release, which frees the slot.
+	pub func future_result_uint64 = (uint64 future, out uint64) {
+		```
+		#arch: c
+		return *(unsigned long long *)(void *)((struct nomen_future *)(void *)future)->result_slot;
+		```
+		```
+		#arch: aarch64
+		// x0 = future; result_slot at #128
+		ldr x0, [x0, #128]
+		ldr x0, [x0]
+		```
+	}
+
+	// Set the future's reference count before submitting. The construction
+	// leaves one reference (the value's own); a launch that parks on the
+	// future holds the wait-side reference: set_refs(f, 2), submit, and the
+	// running task's completion drops one; the join drops the last (the
+	// future frees its slot, flag, and packed closure at zero).
+	pub func future_set_refs = (uint64 future, int refs) {
+		```
+		#arch: c
+		((struct nomen_future *)(void *)future)->refs = refs;
+		```
+		```
+		#arch: aarch64
+		// x0 = future, x1 = refs (refs is at #116)
+		str w1, [x0, #116]
+		```
+	}
+
+	// Drop one reference to the future. At the last reference the future is
+	// freed along with the result slot, cancel flag, and packed task closure
+	// it owns. After a release the handle's fields are gone: zero them.
+	pub func future_release = (uint64 future) {
+		```
+		#arch: c
+		__nomen_future_release((struct nomen_future *)(void *)future);
+		```
+		```
+		#arch: aarch64
+		// x0 = future
+		bl ___nomen_future_release
+		```
+	}
+
 	// Release this handle's reference to the future. The future owns the
 	// result slot and cancel flag; it (and they) are freed only when the
 	// last reference — this handle, the running trampoline, or a tracking

package/core/System/Thread.nm

@@ -0,0 +1,83 @@
+// Thread — a task running on the shared worker pool (CLOSURE.md
+// Phase 3b). `Thread(fn(args))` constructs a Thread value: the arguments are
+// evaluated eagerly and packed into a task closure (a heap closure
+// descriptor over the pooled-args environment — the same ABI every lambda
+// lowers to); `.start()` submits that closure to the worker pool and yields
+// a `Task<T>` handle; `.detach()` runs it as an unjoinable daemon.
+//
+// Because the construction is a real value, it can be STORED and started
+// later:
+//
+//     var t = Thread(work(n))
+//     ...later...
+//     var Task<uint64> handle = t.start()
+//
+// The pool starts at a configurable size (default 4, via Task.set_pool_size
+// before the first spawn) and grows on demand up to 64 workers when every
+// worker is busy, preventing deadlocks from nested spawns. The pool drains
+// and joins all workers at process exit; Task.shutdown_pool does this
+// explicitly.
+//
+// The pool infrastructure (types, worker loop, submit, shutdown, cancel
+// thread-local) lives in build_spawn_node and is emitted as file-scope C
+// on the first spawn — not in Thread's own methods — so that Thread can be
+// generic without duplicating the pool per instantiation.
+//
+// MUST-START: a Thread value that is destroyed without ever being started
+// is a programming error — #destroy reports it and aborts. start/detach
+// (and nursery.start) transfer ownership of the packed task out of the
+// value, so a started Thread destroys as a no-op.
+//
+// See ASYNC.md for the design.
+
+/**
+ * A deferred function call, startable on the shared worker pool
+ **/
+pub class Thread<T> : Sendable {
+	// The packed task closure (a `struct nomen_closure *`); owned by this
+	// value until start/detach/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() / .detach() / nursery.start.
+	pub var started = false
+
+	// Destroying an unstarted Thread is a programming error (the wrapped
+	// call would silently never run) — report it and abort. A started
+	// Thread 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, .Lthr_started
+		bl ___nomen_spawn_must_start_abort
+		.Lthr_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, .Lthr_done
+		bl ___nomen_future_release
+		str xzr, [x19, #32]
+		str xzr, [x19, #16]
+		str xzr, [x19, #24]
+		.Lthr_done:
+		```
+	}
+}