visaljs 0.0.0-stage → 0.0.2

package/runtime/include/js_gc.h

@@ -0,0 +1,195 @@
+/*
+ * js_gc.h — heap and garbage collector (ADR 0002).
+ *
+ * Non-moving mark-sweep. Cells come from 64 KiB aligned blocks, one size
+ * class per block, or from the large-object space. Mark and allocation bits
+ * live in side bitmaps in the block header, never in the cell.
+ */
+#ifndef JS_GC_H
+#define JS_GC_H
+
+#include <assert.h>
+#include <stddef.h>
+#include <stdint.h>
+#if defined(_MSC_VER) && !defined(__clang__)
+#include <intrin.h>
+#endif
+
+#include "jscell.h"
+#include "jsvalue.h"
+
+typedef struct JSRuntime JSRuntime;
+typedef struct JSContext JSContext;
+
+/* ---- Blocks and size classes ------------------------------------------- */
+
+#define JS_BLOCK_SIZE       ((size_t)64 * 1024)
+#define JS_CELL_ALIGN       16
+#define JS_MAX_SMALL_SIZE   8192
+#define JS_NUM_SIZE_CLASSES 32
+#define JS_BLOCK_MAX_CELLS  (JS_BLOCK_SIZE / JS_CELL_ALIGN)
+#define JS_BITMAP_WORDS     (JS_BLOCK_MAX_CELLS / 64)
+
+/* Collection policy (ADR 0002). */
+#define JS_GC_MIN_HEAP      ((size_t)4 << 20)  /* never collect before this much is allocated */
+#define JS_EMPTY_POOL_MAX   32                 /* empty blocks kept; the rest go back to the OS */
+
+typedef struct JSFreeCell { struct JSFreeCell *next; } JSFreeCell;
+
+/* The header of a 64 KiB block of same-size cells, or of a large object:
+ * a 64 KiB-aligned mapping holding exactly one cell (is_large). Either way
+ * js_block_of(cell) finds it. */
+typedef struct JSBlock {
+    struct JSBlock *next;        /* in its size class's list, or in the empty pool */
+    size_t   map_size;           /* JS_BLOCK_SIZE, or the large object's mapping */
+    uint32_t cell_size;
+    uint32_t cell_count;
+    uint8_t  size_class;
+    uint8_t  is_large;
+    uint8_t  unswept;            /* marked by the last GC, not swept yet */
+    uint8_t  has_finalizable;
+    uint8_t  pad_[4];
+    uint64_t mark_bits[JS_BITMAP_WORDS];
+    uint64_t alloc_bits[JS_BITMAP_WORDS];  /* exact only while the world is stopped */
+} JSBlock;
+
+#define JS_BLOCK_FIRST_CELL \
+    ((sizeof(JSBlock) + JS_CELL_ALIGN - 1) & ~(size_t)(JS_CELL_ALIGN - 1))
+
+static inline JSBlock *js_block_of(const void *p) {
+    return (JSBlock *)((uintptr_t)p & ~(uintptr_t)(JS_BLOCK_SIZE - 1));
+}
+
+/* Cell size of each class: 16…128 in steps of 16, then 4 classes per doubling up to 8192. */
+extern const uint16_t js_size_class_bytes[JS_NUM_SIZE_CLASSES];
+
+/* The class for 1 <= size <= JS_MAX_SMALL_SIZE. Folds to a constant for constant sizes. */
+static inline unsigned js_size_class(size_t size) {
+    if (size <= 128) return (unsigned)((size + 15) / 16) - (size != 0);
+    unsigned s = (unsigned)size - 1;
+#if defined(_MSC_VER) && !defined(__clang__)
+    unsigned long b;
+    _BitScanReverse(&b, s);
+#else
+    unsigned b = 31 - (unsigned)__builtin_clz(s);  /* floor(log2(s)): 7…12 */
+#endif
+    return 8 + (unsigned)(b - 7) * 4 + ((s >> (b - 2)) - 4);
+}
+
+/* ---- Heap -------------------------------------------------------------- */
+
+typedef struct JSHeap {
+    JSFreeCell *free[JS_NUM_SIZE_CLASSES];  /* hot: popped by the inline fast path */
+    JSBlock *current[JS_NUM_SIZE_CLASSES];  /* the block `free` points into */
+    JSBlock *blocks[JS_NUM_SIZE_CLASSES];   /* every block of the class */
+    JSBlock **sweep_link[JS_NUM_SIZE_CLASSES]; /* link to the next block to sweep lazily */
+    JSBlock *empty;                         /* pool of empty blocks, any class */
+    size_t   block_count;
+    size_t   empty_count;
+    JSBlock **large;                        /* large objects, sorted by address (malloc'd) */
+    size_t   large_count;
+    size_t   large_cap;
+    size_t   large_bytes;
+
+    /* Precise roots (malloc'd arrays). */
+    struct JSRootTable { JSValue *slots; size_t n; } *root_tables;
+    size_t   root_table_count, root_table_cap;
+    JSValue **roots;
+    size_t   root_count, root_cap;
+
+    /* Conservative pointer test (ADR 0002). */
+    uintptr_t *block_set;                   /* open addressing over block addresses; 0 = empty */
+    size_t   block_set_cap, block_set_count;
+    uint64_t block_bloom[4];                /* 256-bit Bloom filter over block_set */
+    uintptr_t min_addr, max_addr;           /* bounds of every mapping the heap made */
+    void    *stack_base;                    /* highest stack address of the owning thread */
+
+    JSCell **mark_stack;                    /* malloc'd; reused across collections */
+    size_t   mark_stack_cap;
+    size_t   gc_count;
+    int      in_gc;
+
+    /* Policy: collect when allocated_since_gc > max(min_heap, live_after_gc). */
+    size_t   allocated_since_gc;            /* bytes handed to the allocator */
+    size_t   live_after_gc;                 /* bytes marked by the last collection */
+    size_t   min_heap;
+    size_t   heap_limit;                    /* 0 = unlimited; env JS_HEAP_LIMIT_MB */
+    size_t   stress_interval, stress_counter;  /* JS_GC_STRESS builds; env JS_GC_STRESS_INTERVAL */
+} JSHeap;
+
+/* ---- Cell classes and tracing ---------------------------------------- */
+
+typedef struct JSTracer JSTracer;
+
+typedef struct JSCellClass {
+    const char *name;
+    void (*visit)(JSCell *cell, JSTracer *trc);      /* trace every JSValue the cell holds */
+    void (*finalize)(JSRuntime *rt, JSCell *cell);   /* NULL for almost all kinds */
+} JSCellClass;
+
+/* Ignores non-cells and static cells. */
+void js_trace_value(JSTracer *trc, JSValue v);
+void js_trace_cell(JSTracer *trc, JSCell *cell);
+
+/* ---- Allocation -------------------------------------------------------- */
+
+/* Any size. Returns a zero-filled cell with its header set. Never NULL. */
+JSCell *js_alloc_cell(JSContext *ctx, JSCellKind kind, size_t size);
+
+void *js_alloc_slow(JSContext *ctx, unsigned size_class);
+
+/* JS_CELL_VALUE_ARRAY: a fixed-length JSValue array, all JS_EMPTY initially. */
+typedef struct JSValueArray {
+    JSCell  cell;       /* aux = length */
+    JSValue values[];
+} JSValueArray;
+
+JSValueArray *js_alloc_value_array(JSContext *ctx, uint32_t length);
+
+/* JS_CELL_HOST: `size` bytes, starting with a JSHostCell, traced and finalized by `cls`. */
+typedef struct JSHostCell {
+    JSCell cell;
+    const JSCellClass *cls;
+} JSHostCell;
+
+JSHostCell *js_alloc_host_cell(JSContext *ctx, const JSCellClass *cls, size_t size);
+
+/* ---- Stores into heap cells (ABI hook, ADR 0002) ---------------------- */
+
+/* Every store of a JSValue into a cell that may already be reachable.
+ * A plain store today; a generational or incremental barrier goes here. */
+static inline void js_store(JSContext *ctx, JSCell *owner, JSValue *slot, JSValue v) {
+    (void)ctx;
+    (void)owner;
+    assert(!js_is_exception(v) && "JS_EXCEPTION stored into a cell (ADR 0004, invariant 3)");
+    *slot = v;
+}
+
+/* Initializing store into a cell allocated with no allocation in between. */
+static inline void js_init_slot(JSValue *slot, JSValue v) { *slot = v; }
+
+/* Keeps `v` visibly live to the conservative scan up to this point. */
+#if defined(__GNUC__) || defined(__clang__)
+#define js_keep_alive(v) __asm__ volatile("" ::"r"((v).bits))
+#else
+#define js_keep_alive(v) ((void)*(volatile uint64_t *)&(v).bits)
+#endif
+
+/* ---- Roots ------------------------------------------------------------- */
+
+void js_register_roots(JSRuntime *rt, JSValue *slots, size_t n);  /* module globals, once */
+/* A JSValue in malloc'd memory. It must hold a valid value (e.g. JS_UNDEFINED)
+ * before it's added: any allocation may collect and read it. */
+void js_add_root(JSRuntime *rt, JSValue *slot);
+void js_remove_root(JSRuntime *rt, JSValue *slot);
+
+/* ---- Control ----------------------------------------------------------- */
+
+void js_gc(JSContext *ctx);  /* full collection */
+
+/* Exits with "heap limit reached" when the cells would need more than `bytes`. 0 = no limit. */
+void js_set_heap_limit(JSRuntime *rt, size_t bytes);
+/* Bytes currently mapped for cells: blocks (including empty ones) and large objects. */
+size_t js_heap_size(const JSRuntime *rt);
+
+#endif /* JS_GC_H */

package/runtime/include/js_generator.h

@@ -0,0 +1,96 @@
+/*
+ * js_generator.h — generators (ECMAScript §27.5; ADR 0007).
+ *
+ * The compiler turns a function* into an entry (its prologue, which ends by creating the
+ * generator with js_generator_new) and a resume function: a state machine that saves the
+ * values live across each pause point into the generator's frame.
+ */
+#ifndef JS_GENERATOR_H
+#define JS_GENERATOR_H
+
+#include "js_object.h"
+
+typedef struct JSGenerator JSGenerator;
+
+/* Runs from the pause point g->state to the next one (returns the yielded value, status
+ * SUSPENDED) or to the end (returns the result or JS_EXCEPTION, status still EXECUTING). */
+typedef JSValue (*JSGeneratorResume)(JSContext *ctx, JSGenerator *g, JSValue sent, int mode);
+
+enum { JS_RESUME_NEXT, JS_RESUME_THROW, JS_RESUME_RETURN };
+enum {
+    JS_GEN_START, JS_GEN_SUSPENDED, JS_GEN_EXECUTING, JS_GEN_COMPLETED,
+    JS_GEN_AWAITING,         /* async: paused at an await (still running, to the async generator's queue) */
+    JS_GEN_AWAITING_RETURN,  /* async generator: awaiting a return(v)'s value after completing */
+};
+enum { JS_GEN_SYNC, JS_GEN_ASYNC_FUNCTION, JS_GEN_ASYNC_GENERATOR };  /* JSGenerator.kind */
+
+struct JSGenerator {
+    JSObject          obj;
+    JSGeneratorResume resume;
+    JSValue           frame;   /* a value array: the saved live values; undefined once completed */
+    JSValue           driver;  /* async functions: the promise the call returned */
+    uint32_t          state;   /* the pause point to resume at: 0 = the start of the body */
+    uint8_t           status;  /* JS_GEN_* */
+    uint8_t           raw;     /* the last pause handed on yield*'s inner result object as it is */
+    uint8_t           kind;    /* JS_GEN_SYNC, ASYNC_FUNCTION, ASYNC_GENERATOR */
+};
+
+static inline JSGenerator *js_as_generator(JSValue v) { return (JSGenerator *)js_as_object(v); }
+
+/* The entry's last step: a generator whose prototype is callee.prototype (or the realm's
+ * %GeneratorPrototype%), with `slots` frame slots. */
+JSValue js_generator_new(JSContext *ctx, JSValue callee, JSGeneratorResume resume, uint32_t slots);
+
+static inline void js_generator_save(JSContext *ctx, JSGenerator *g, uint32_t slot, JSValue v) {
+    JSValueArray *f = (JSValueArray *)js_as_cell(g->frame);
+    js_store(ctx, &f->cell, &f->values[slot], v);
+}
+static inline JSValue js_generator_load(JSGenerator *g, uint32_t slot) {
+    return ((JSValueArray *)js_as_cell(g->frame))->values[slot];
+}
+
+/* yield* (§15.5.5): the inner iterator as a record, one step forwarding a resume (mode as a
+ * number) to it, and that step's outcome: 0 yield the value (an inner result object),
+ * 1 done (the value is yield*'s), 2 return the value from the generator. */
+JSValue js_yield_star_start(JSContext *ctx, JSValue iterable);
+JSValue js_yield_star_step(JSContext *ctx, JSValue rec, JSValue received, JSValue mode);
+JSValue js_yield_star_status(JSValue rec);
+
+/* ---- Async functions (§27.7; ADR 0007) ------------------------------------------------- */
+
+/* An async call's state: a generator-like object nothing in JS can reach. */
+JSValue js_async_new(JSContext *ctx, JSGeneratorResume resume, uint32_t slots);
+/* The entry's last step: runs the body to its first await (or the end) and returns the
+ * promise, which the body's outcome settles. Never throws. */
+JSValue js_async_start(JSContext *ctx, JSGenerator *g);
+/* await v: registers the resume on PromiseResolve(v); 0 (paused: status AWAITING), or -1
+ * if PromiseResolve threw (the exception is pending, at the await). */
+JS_WARN_UNUSED int js_await(JSContext *ctx, JSGenerator *g, JSValue v);
+/* Resumes a paused async call or async generator (a promise reaction job): mode NEXT with
+ * the value, THROW with the reason. */
+void js_async_resume(JSContext *ctx, JSGenerator *g, JSValue value, int mode);
+
+/* ---- Async generators and async iteration (§27.6, §27.1; async_iter.c) ---------------- */
+
+/* The entry's last step for an async function*: like js_generator_new. */
+JSValue js_async_generator_new(JSContext *ctx, JSValue callee, JSGeneratorResume resume, uint32_t slots);
+void js_async_generator_resume(JSContext *ctx, JSGenerator *g, JSValue value, int mode);
+/* for await: GetIterator(v, async) as a record (a sync iterator is wrapped,
+ * CreateAsyncFromSyncIterator); next() called; the awaited result's value (EMPTY when done);
+ * return() called (EMPTY: none, or the record is done); an awaited return() result checked. */
+JSValue js_async_iter_start(JSContext *ctx, JSValue v);
+JSValue js_async_iter_next(JSContext *ctx, JSValue rec);
+JSValue js_async_iter_value(JSContext *ctx, JSValue rec, JSValue result);
+JSValue js_async_iter_return(JSContext *ctx, JSValue rec);
+JSValue js_async_iter_check(JSContext *ctx, JSValue result);
+/* yield* in an async generator: a step (mode as a number) gives a value to await; settling
+ * it with the awaited value gives the outcome: status 0 yield it, 1 done (yield*'s value),
+ * 2 return it from the generator, 3 await it and settle again. */
+JSValue js_async_yield_star_step(JSContext *ctx, JSValue rec, JSValue received, JSValue mode);
+JSValue js_async_yield_star_settled(JSContext *ctx, JSValue rec, JSValue awaited);
+JSValue js_async_yield_star_status(JSValue rec);
+void js_async_iter_realm_init(JSContext *ctx);
+
+void js_generator_realm_init(JSContext *ctx);
+
+#endif /* JS_GENERATOR_H */

package/runtime/include/js_host.h

@@ -0,0 +1,19 @@
+/* js_host.h — the host's layer 1 in the runtime (ADR 0012): console, process and global,
+ * installed before the program runs, and what host packages (node/) build on. Host packages
+ * declare their own primitives (node/include/js_node.h); the generated code declares the ones
+ * it uses. */
+#ifndef JS_HOST_H
+#define JS_HOST_H
+
+#include "js_function.h"
+
+/* process.c: console, process and global, installed before the program runs (main);
+ * the exit status (process.exitCode) unless the program failed; a process warning on stderr */
+int js_host_init(JSContext *ctx, int argc, char **argv);
+int js_host_exit_code(void);
+void js_emit_warning(JSContext *ctx, JSValue message, const char *type, const char *code);
+
+/* cwd(): the working directory (process.cwd()), also a host primitive of node:path; -errno on failure. */
+JSValue js_host_cwd(JSContext *ctx, JSValue callee, JSValue this_val, uint32_t argc, const JSValue *argv, JSValue new_target);
+
+#endif /* JS_HOST_H */

package/runtime/include/js_jobs.h

@@ -0,0 +1,84 @@
+/*
+ * js_jobs.h — the job queue and the event loop (ADR 0008).
+ *
+ * Layer 1 (spec): microtasks, run at checkpoints when no JS is on the stack, then the
+ * unhandled rejections are processed. Layer 2 (host): the event loop that runs the
+ * main script, then runs timers, one per iteration with a checkpoint after each, until
+ * nothing is pending.
+ */
+#ifndef JS_JOBS_H
+#define JS_JOBS_H
+
+#include "jsvalue.h"
+
+typedef struct JSContext JSContext;
+typedef struct JSRuntime JSRuntime;
+
+enum {
+    JS_JOB_PROMISE_REACTION,  /* a: reaction record, b: argument, c: int32 settled state */
+    JS_JOB_RESOLVE_THENABLE,  /* a: promise to resolve, b: thenable, c: its then */
+    JS_JOB_CALLBACK,          /* a: function (queueMicrotask), b: an array of its arguments, or undefined */
+};
+
+/* Every queued job's values are precise GC roots. */
+typedef struct JSJob {
+    uint8_t    kind;
+    JSContext *realm;  /* set by js_enqueue_microtask: the realm that queued it */
+    JSValue    a, b, c;
+} JSJob;
+
+typedef struct JSJobQueue {
+    JSJob *items;      /* a ring buffer (malloc'd) */
+    size_t head, count, cap;
+} JSJobQueue;
+
+/* A setTimeout / setInterval (ADR 0008). Its values are GC roots. */
+typedef struct JSTimer {
+    uint64_t   deadline;   /* in the loop's milliseconds */
+    uint64_t   seq;        /* creation order: breaks ties */
+    uint32_t   id;         /* what setTimeout returned: a positive integer */
+    uint32_t   repeat;     /* setInterval: its delay in ms; 0 for setTimeout */
+    uint8_t    unref;      /* doesn't keep the program alive (AbortSignal.timeout's) */
+    JSContext *realm;
+    JSValue    fn;
+    JSValue    args;       /* an array of the extra arguments, or undefined */
+} JSTimer;
+
+typedef struct JSTimers {
+    JSTimer *heap;         /* a min-heap on (deadline, seq) (malloc'd) */
+    size_t   count, cap;
+    uint64_t now;          /* the loop's clock, cached like libuv's: refreshed only when nothing is due */
+    uint64_t seq;
+    uint32_t next_id;
+    size_t   refed;        /* timers that keep the program alive: those not unref'd */
+    uint32_t running;      /* the interval whose callback is running, or 0 */
+    uint8_t  running_cleared;
+} JSTimers;
+
+/* What a checkpoint does with promises still rejected and unhandled at its end. */
+typedef enum JSRejectionMode {
+    JS_REJECTIONS_STRICT,  /* the default: print "Uncaught (in promise) …", stop, exit status 1 */
+    JS_REJECTIONS_WARN,    /* print the same, keep running */
+    JS_REJECTIONS_NONE,    /* ignore them */
+} JSRejectionMode;
+
+void js_enqueue_microtask(JSContext *ctx, const JSJob *job);
+/* The checkpoint: runs every queued job (and the ones they queue), then processes
+ * unhandled rejections. A nested call does nothing. 0, or -1 after an uncaught error
+ * or a strict unhandled rejection (already reported). */
+int js_run_microtasks(JSContext *ctx);
+void js_set_rejection_mode(JSRuntime *rt, JSRejectionMode mode);
+
+/* HostPromiseRejectionTracker (§27.2.1.9): `rejected` true for "reject" (a promise was
+ * rejected with no handler), false for "handle" (a handler was added later). */
+void js_track_rejection(JSContext *ctx, JSValue promise, bool rejected);
+
+/* A one-shot timer from C: fn() after `delay` ms (clamped as setTimeout clamps it). An unref'd
+ * one doesn't keep the program alive, as Node's timer.unref(). Its id (clearTimeout's). */
+uint32_t js_add_timer(JSContext *ctx, JSValue fn, double delay, bool unref);
+
+/* Runs the program after its main script returned `main_result`: reports an uncaught
+ * error, else checkpoints until nothing is pending. The process exit status. */
+int js_run_event_loop(JSContext *ctx, JSValue main_result);
+
+#endif /* JS_JOBS_H */

package/runtime/include/js_module.h

@@ -0,0 +1,16 @@
+/* js_module.h — module-level host behavior (ADR 0009): import.meta and import(). */
+#ifndef JS_MODULE_H
+#define JS_MODULE_H
+
+#include "js_function.h"
+
+/* import.meta of the original module at `file` (an absolute path): created on first use and
+ * kept in *cache (a module slot, so the GC sees it), with null prototype and Node's
+ * properties dirname, filename, main, resolve and url. */
+JSValue js_import_meta(JSContext *ctx, JSValue *cache, const char *file, bool main);
+
+/* import(specifier, options) in the module at `importer`, for a specifier the bundler left in
+ * the program: a promise, rejected (ERR_MODULE_NOT_FOUND unless an argument check fails). */
+JSValue js_dynamic_import(JSContext *ctx, JSValue specifier, JSValue options, const char *importer);
+
+#endif /* JS_MODULE_H */