@scriptc/runtime 0.0.0 → 0.0.1

package/src/scr_platform.h

@@ -0,0 +1,119 @@
+/* The platform readiness contract — ONE interface both event backends
+ * implement (kqueue on macOS/BSD, epoll on Linux), designed from how
+ * scr_net.c / scr_dgram.c / scr_child.c use kqueue TODAY. Design notes and
+ * the full macOS-ism audit live in docs/linux-port.md.
+ *
+ * Scope, deliberately: the loop CORE (scr_async.c) is already portable —
+ * its idle sleep is poll(2)/nanosleep over fds the optional units hand it
+ * via the pending/dispatch/pollfd hook triple, and that hook contract is
+ * platform-neutral (an epoll fd polls readable while events pend, exactly
+ * like a kqueue fd). What is NOT portable is the plumbing INSIDE each
+ * unit: kqueue creation, filter add/remove, the idle-timer filter, the
+ * child-exit filter, and the zero-timeout drains. This header names that
+ * plumbing so each unit can call one spelling and link either backend.
+ *
+ * STATUS: LIVE. scr_net.c and scr_dgram.c call this contract; cc.ts
+ * links BOTH backends whenever either unit compiles (scr_loop_kqueue.c —
+ * a stateless spelling of the units' historical inline syscall
+ * sequences, byte-identical on macOS by construction — and
+ * scr_loop_epoll.c; each TU is empty off its platform). The mapping each
+ * backend owes:
+ *
+ *   contract              kqueue backend                 epoll backend
+ *   ------------------    ---------------------------    -------------------------------
+ *   poller fd             the kqueue() fd                the epoll_create1() fd
+ *   watch read on/off     EVFILT_READ EV_ADD/EV_DELETE   EPOLLIN via ADD/MOD/DEL + fd table
+ *   watch write on/off    EVFILT_WRITE EV_ADD/EV_DELETE  EPOLLOUT via ADD/MOD/DEL + fd table
+ *   one-shot timer(key)   EVFILT_TIMER ident=key,        one timerfd_create per armed key,
+ *                         EV_ONESHOT, NOTE_* default ms  TFD_NONBLOCK, registered EPOLLIN
+ *   drain (zero timeout)  kevent(evs, N, {0,0})          epoll_wait(evs, N, 0)
+ *   EOF/error delivery    EV_EOF on the read filter      EPOLLHUP/EPOLLERR/EPOLLRDHUP
+ *                                                        reported as READABLE (+WRITABLE
+ *                                                        when write interest is armed) —
+ *                                                        units learn the truth from
+ *                                                        read()==0 / errno, as today
+ *
+ * (Child-exit wakeups live inline in scr_child.c — see the note at the
+ * bottom of this header.)
+ *
+ * Two epoll-only obligations the kqueue side never had, called out so the
+ * extraction cannot fudge them: (1) epoll keys interest by fd with
+ * ONE mask, so read+write interest on the same fd must merge into a MOD —
+ * the backend keeps a private fd -> (mask, udata) table; kqueue's separate
+ * filters need no such state. (2) closing an fd does NOT reliably remove
+ * it from an epoll set while dup'd references exist — units must call
+ * scrp_forget BEFORE close(2). kqueue drops filters on close, so today's
+ * units don't always bother; the extraction adds the forget calls (a
+ * no-op wrapper on the kqueue side keeps macOS byte-identical in
+ * behavior; the corpus proves it). */
+#ifndef SCR_PLATFORM_H
+#define SCR_PLATFORM_H
+
+#include <stdbool.h>
+#include <stddef.h>
+
+/* ── the fd/timer poller (scr_net.c's and scr_dgram.c's unit kqueues) ── */
+
+typedef struct ScrPoller ScrPoller;
+
+enum {
+  SCRP_READABLE = 1u << 0,
+  SCRP_WRITABLE = 1u << 1,
+  SCRP_TIMER = 1u << 2,
+};
+
+typedef struct {
+  void *udata;     /* the pointer registered at watch/arm time; routing is
+                    * the caller's business (scr_net routes on a leading
+                    * `kind` int, exactly as its kevent udata does today) */
+  unsigned events; /* SCRP_* bits OR'd */
+} ScrPollerEvent;
+
+/* NULL on resource exhaustion — callers report and disable the unit, the
+ * historical kqueue() failure path. */
+ScrPoller *scrp_poller_new(void);
+void scrp_poller_free(ScrPoller *p);
+
+/* The fd the LOOP sleeps on (poll(2), POLLIN): readable while any event
+ * pends, the property both kqueue and epoll fds share. Owned by the
+ * poller — never closed or drained by the caller. */
+int scrp_poller_fd(const ScrPoller *p);
+
+/* Watch/unwatch one direction on an fd. `udata` tags every delivery for
+ * this fd (the LAST registration wins across both directions — matching
+ * how the units pass the same socket pointer to both filters today).
+ * Unwatching a direction that isn't armed is a no-op, like EV_DELETE on a
+ * missing filter is ignored by today's code. */
+bool scrp_watch_read(ScrPoller *p, int fd, void *udata, bool on);
+bool scrp_watch_write(ScrPoller *p, int fd, void *udata, bool on);
+
+/* Drop every registration for fd. MUST precede close(2) of a watched fd
+ * (see the epoll obligation above); safe on unwatched fds. */
+void scrp_forget(ScrPoller *p, int fd);
+
+/* One-shot timer keyed by an arbitrary pointer (scr_net's idle timers:
+ * ident = the socket pointer). Re-arming an armed key replaces its
+ * deadline; delivery reports SCRP_TIMER with udata = key. Cancel of an
+ * unarmed/already-fired key is a no-op (the timer "may already have
+ * fired" comment in scr_net.c today). */
+bool scrp_timer_arm(ScrPoller *p, void *key, double ms, void *udata);
+void scrp_timer_cancel(ScrPoller *p, void *key);
+
+/* Zero-timeout drain of everything pending, at most `max` events (the
+ * units' dispatch-top drains: kevent/epoll_wait with a zero timeout).
+ * Returns the count; EINTR reads as 0 (a spurious pass, as today). */
+int scrp_drain(ScrPoller *p, ScrPollerEvent *out, int max);
+
+/* ── child-exit wakeups: NOT here, deliberately ───────────────────────
+ * scr_child.c keeps its narrow seam INLINE (scr_child_watch /
+ * scr_children_wait / scr_children_wake_fd, plus the stream read-fd
+ * arm/dearm): kqueue EVFILT_PROC NOTE_EXIT + EVFILT_READ on BSD,
+ * pidfd_open + a dedicated epoll on Linux, and the portable
+ * waitpid(WNOHANG)-under-a-~1ms-cap fallback everywhere else. That unit
+ * links into EVERY binary, so routing it through this contract would put
+ * both backends on every link line; its plumbing (wakeups-only, events
+ * discarded, the unit's own unwatched-children accounting) also never
+ * matched the fd/timer poller shape above. Reaping stays the WNOHANG
+ * sweep on every platform — exit events are wakeups only. */
+
+#endif /* SCR_PLATFORM_H */

package/src/scr_readline.c

@@ -0,0 +1,287 @@
+/* node:readline — the question/close slice over the stdin unit
+ * (scr_events.c), linked exactly when the program uses it (the events
+ * gating; rl.* libCalls imply events).
+ *
+ * Model, pinned against Node under pipes (SEMANTICS.md + corpus 1475):
+ * - createInterface({ input: process.stdin, output: process.stdout })
+ *   registers this unit's ONE shared stdin data listener (a consumer: the
+ *   loop watches fd 0 and the process stays alive while any interface is
+ *   open, exactly Node's un-closed readline) and a global 'end' listener.
+ * - Lines split on \n and \r\n (and a bare \r followed by more input);
+ *   a trailing \r holds until the next chunk decides \r\n vs \r.
+ * - question(query, cb) writes the query to stdout (Node writes it under
+ *   pipes too) and delivers the NEXT line's text; a line arriving with no
+ *   pending question is DROPPED (Node emits 'line' that nobody hears).
+ * - close() removes the consumer (the loop stops waiting on fd 0), drops
+ *   a pending question (its callback never fires), and fires the 'close'
+ *   listeners SYNCHRONOUSLY — Node's close() emits inline, which is why
+ *   the portless prompt's close-listener resolve wins over the question
+ *   callback's (oracle-pinned).
+ * - stdin EOF closes every open interface the same way: the buffered
+ *   partial line is DISCARDED (Node), then 'close' fires.
+ * - question() after close() throws Node's ERR_USE_AFTER_CLOSE message.
+ * - An interface created AFTER stdin ended is DEAD (pinned against
+ *   Node): a question still writes its prompt, but nothing ever answers
+ *   and 'close' never fires — Node's process exits with the question
+ *   pending, and the loop exhausts the same way here. */
+#include "scr_runtime.h"
+
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+
+static void scr_rl_oom(void) {
+  fputs("scriptc: out of memory\n", stderr);
+  abort();
+}
+
+typedef struct ScrRl {
+  double id;
+  bool closed;
+  bool dead; /* created after stdin ended: close fires at question() */
+  ScrClosure *q_cb; /* pending question's callback (owned), or NULL */
+  void (*q_fn)(ScrClosure *, ScrStr *);
+  ScrClosure **close_cbs; /* owned zero-arg listeners */
+  size_t n_close, cap_close;
+  char *buf; /* undelivered stdin bytes */
+  size_t len, cap;
+  struct ScrRl *next;
+} ScrRl;
+
+static ScrRl *scr_rls = NULL;
+static double scr_rl_next_id = 1;
+static size_t scr_rl_open = 0;        /* un-closed, un-dead interfaces */
+static ScrClosure *scr_rl_data_cb = NULL; /* the shared consumer (borrowed
+                                            * mirror; the registry owns) */
+static bool scr_rl_end_registered = false;
+
+static ScrRl *scr_rl_find(double id) {
+  for (ScrRl *rl = scr_rls; rl; rl = rl->next) {
+    if (rl->id == id) return rl;
+  }
+  return NULL;
+}
+
+/* Fires the close listeners (snapshot; synchronous, like Node's emit) and
+ * releases everything the interface holds. */
+static void scr_rl_settle_close(ScrRl *rl) {
+  if (rl->closed) return;
+  rl->closed = true;
+  if (!rl->dead && scr_rl_open > 0) scr_rl_open--;
+  if (rl->q_cb) {
+    scr_closure_release(rl->q_cb); /* a pending question never answers */
+    rl->q_cb = NULL;
+  }
+  /* The last open interface leaving detaches the shared consumer so the
+   * loop stops waiting on fd 0 (Node's pause-on-close). */
+  if (scr_rl_open == 0 && scr_rl_data_cb != NULL) {
+    scr_stdin_remove_data(scr_rl_data_cb);
+    scr_rl_data_cb = NULL;
+  }
+  size_t n = rl->n_close;
+  ScrClosure **snap = rl->close_cbs;
+  rl->close_cbs = NULL;
+  rl->n_close = rl->cap_close = 0;
+  for (size_t i = 0; i < n; i++) {
+    if (!scr_exc_pending()) {
+      ((void (*)(ScrClosure *))snap[i]->fn)(snap[i]);
+    }
+    scr_closure_release(snap[i]);
+  }
+  free(snap);
+  free(rl->buf);
+  rl->buf = NULL;
+  rl->len = rl->cap = 0;
+}
+
+/* One complete line off the front of the buffer: *adv is the byte count
+ * consumed (terminator included), *line_len the line's length. False when
+ * no complete line is buffered (a trailing \r holds for the \r\n
+ * decision). */
+static bool scr_rl_scan(const ScrRl *rl, size_t *line_len, size_t *adv) {
+  for (size_t i = 0; i < rl->len; i++) {
+    char c = rl->buf[i];
+    if (c == '\n') {
+      *line_len = i;
+      *adv = i + 1;
+      return true;
+    }
+    if (c == '\r') {
+      if (i + 1 >= rl->len) return false; /* hold: \r\n may straddle chunks */
+      *line_len = i;
+      *adv = rl->buf[i + 1] == '\n' ? i + 2 : i + 1;
+      return true;
+    }
+  }
+  return false;
+}
+
+static void scr_rl_drain(ScrRl *rl) {
+  size_t line_len, adv;
+  while (!rl->closed && scr_rl_scan(rl, &line_len, &adv)) {
+    ScrStr *line = NULL;
+    ScrClosure *cb = rl->q_cb;
+    void (*fn)(ScrClosure *, ScrStr *) = rl->q_fn;
+    if (cb) line = scr_str_new(rl->buf, line_len);
+    memmove(rl->buf, rl->buf + adv, rl->len - adv);
+    rl->len -= adv;
+    if (cb) {
+      rl->q_cb = NULL; /* consumed BEFORE the callback runs (once) */
+      fn(cb, line);    /* the adapter owns the +1 line */
+      scr_closure_release(cb);
+      if (scr_exc_pending()) return;
+    }
+    /* No pending question: the line drops, exactly Node's unheard 'line'. */
+  }
+}
+
+/* The shared stdin data consumer: appends and drains every open
+ * interface (chunks broadcast, like any stdin listener set). */
+static void scr_rl_data_adapter(ScrClosure *cb, ScrBytes *chunk) {
+  (void)cb;
+  for (ScrRl *rl = scr_rls; rl; rl = rl->next) {
+    if (rl->closed || rl->dead) continue;
+    if (rl->len + chunk->len > rl->cap) {
+      rl->cap = (rl->len + chunk->len) * 2 + 64;
+      rl->buf = realloc(rl->buf, rl->cap);
+      if (!rl->buf) scr_rl_oom();
+    }
+    memcpy(rl->buf + rl->len, chunk->data, chunk->len);
+    rl->len += chunk->len;
+    scr_rl_drain(rl);
+    if (scr_exc_pending()) return;
+  }
+}
+
+/* stdin EOF: every open interface closes — the buffered partial line is
+ * DISCARDED (Node; a trailing held \r still terminates its line first). */
+static void scr_rl_end_thunk(ScrClosure *cb) {
+  (void)cb;
+  scr_rl_data_cb = NULL; /* the stdin unit dropped its listeners itself */
+  for (ScrRl *rl = scr_rls; rl; rl = rl->next) {
+    if (rl->closed || rl->dead) continue;
+    if (rl->len > 0 && rl->buf[rl->len - 1] == '\r' && rl->q_cb) {
+      /* "a\r" then EOF: the \r terminates the line (Node's crlfDelay
+       * expiry collapsed to EOF time). */
+      ScrStr *line = scr_str_new(rl->buf, rl->len - 1);
+      ScrClosure *qcb = rl->q_cb;
+      void (*fn)(ScrClosure *, ScrStr *) = rl->q_fn;
+      rl->q_cb = NULL;
+      rl->len = 0;
+      fn(qcb, line);
+      scr_closure_release(qcb);
+      if (scr_exc_pending()) return;
+    }
+    scr_rl_settle_close(rl);
+    if (scr_exc_pending()) return;
+  }
+}
+
+/* Exit-time cleanup (the events-unit precedent, before the RC audit):
+ * whatever an interface still holds — a parked question, close listeners
+ * on a dead interface that never asked — releases here. */
+static void scr_rl_cleanup_atexit(void) {
+  for (ScrRl *rl = scr_rls; rl; rl = rl->next) {
+    if (rl->q_cb) {
+      scr_closure_release(rl->q_cb);
+      rl->q_cb = NULL;
+    }
+    for (size_t i = 0; i < rl->n_close; i++) scr_closure_release(rl->close_cbs[i]);
+    free(rl->close_cbs);
+    rl->close_cbs = NULL;
+    rl->n_close = rl->cap_close = 0;
+    free(rl->buf);
+    rl->buf = NULL;
+    rl->len = rl->cap = 0;
+  }
+}
+
+double scr_rl_create(void) {
+  static bool cleanup_registered = false;
+  if (!cleanup_registered) {
+    cleanup_registered = true;
+    atexit(scr_rl_cleanup_atexit);
+  }
+  ScrRl *rl = calloc(1, sizeof *rl);
+  if (!rl) scr_rl_oom();
+  rl->id = scr_rl_next_id++;
+  rl->next = scr_rls;
+  scr_rls = rl;
+  if (scr_stdin_ended()) {
+    rl->dead = true; /* close fires when a question is asked */
+    return rl->id;
+  }
+  scr_rl_open++;
+  if (scr_rl_data_cb == NULL) {
+    /* One shared consumer + one global end hook. The closures carry no
+     * captures; their fn slots are never invoked directly for the data
+     * one (the registered adapter is), and the end one IS its thunk. */
+    scr_rl_data_cb = scr_closure_new((void *)&scr_rl_data_adapter, 0);
+    scr_stdin_on_data(scr_rl_data_cb, &scr_rl_data_adapter, false);
+  }
+  if (!scr_rl_end_registered) {
+    scr_rl_end_registered = true;
+    scr_stdin_on_end(scr_closure_new((void *)&scr_rl_end_thunk, 0), false);
+  }
+  return rl->id;
+}
+
+void scr_rl_question(double id, const ScrStr *query, ScrClosure *cb /*moves*/,
+                      void (*fn)(ScrClosure *, ScrStr *)) {
+  ScrRl *rl = scr_rl_find(id);
+  if (!rl || rl->closed) {
+    scr_closure_release(cb);
+    /* Node's ERR_USE_AFTER_CLOSE. */
+    scr_throw_error_msg(SCR_ERR_ERROR, "readline was closed", 19);
+    return;
+  }
+  /* The prompt writes to stdout under pipes too (Node's question does);
+   * same stream and buffer as console.log, so ordering holds. */
+  fwrite(query->data, 1, query->len, stdout);
+  if (rl->dead) {
+    /* Created after stdin ended: pinned against Node — the prompt still
+     * writes, but the DESTROYED stream delivers nothing and 'close'
+     * never fires (Node's process exits with the question pending; the
+     * loop exhausts the same way here). The callback releases now. */
+    scr_closure_release(cb);
+    return;
+  }
+  if (rl->q_cb) scr_closure_release(rl->q_cb); /* re-ask replaces (Node) */
+  rl->q_cb = cb;
+  rl->q_fn = fn;
+  scr_rl_drain(rl); /* an already-buffered line answers immediately */
+}
+
+void scr_rl_close(double id) {
+  ScrRl *rl = scr_rl_find(id);
+  if (!rl) return;
+  scr_rl_settle_close(rl); /* twice is a no-op, like Node */
+}
+
+void scr_rl_on_close(double id, ScrClosure *cb /*moves*/) {
+  ScrRl *rl = scr_rl_find(id);
+  if (!rl || rl->closed) {
+    scr_closure_release(cb); /* after 'close' emitted: never fires */
+    return;
+  }
+  if (rl->n_close == rl->cap_close) {
+    rl->cap_close = rl->cap_close ? rl->cap_close * 2 : 2;
+    rl->close_cbs = realloc(rl->close_cbs, rl->cap_close * sizeof *rl->close_cbs);
+    if (!rl->close_cbs) scr_rl_oom();
+  }
+  rl->close_cbs[rl->n_close++] = cb;
+}
+
+/* ── the runtime-provided answer adapters ────────────────────────────── */
+
+/* A zero-param question callback: the answer is ignored. */
+void scr_rl_answer_thunk0(ScrClosure *cb, ScrStr *answer) {
+  scr_str_release(answer);
+  ((void (*)(ScrClosure *))cb->fn)(cb);
+}
+
+/* An (answer: string) callback — owns the +1 answer per the universal
+ * convention. */
+void scr_rl_answer_thunk_str(ScrClosure *cb, ScrStr *answer) {
+  ((void (*)(ScrClosure *, ScrStr *))cb->fn)(cb, answer);
+}