SuperJ Manual

User-facing how-to guides for working with SuperJ. (Browse the SDK API with superj doc --list / superj doc <class-fqn>.)

Contents

• Overview (one-page visual) — a single self-contained HTML page demonstrating the language at a glance: the arena memory model, the systems-reach features, the kept/dropped-from-Java ledger, and the performance numbers. Open it in any browser.
• Getting Started — what SuperJ is, why it's "super" Java (not a subset), the design philosophy, and a first build.
• Language Reference — the Java → SuperJ deltas in one scannable page: what's identical, what's removed, what's changed, what's new, and a quick syntax table.
• Building the fastest web server in the world — a step-by-step tutorial: write an HTTP server on the built-in stack (the shipped demo/sj/demo/WebServer.sj), compile it to a single native binary, run it, and load-test it with wrk.
• Writing an LLM Inference Engine — a step-by-step tutorial: load a quantized GGUF model with sj.gpu, prefill + decode in forty lines, benchmark it honestly (the GPU warm-up trap), drop down to the Tensor layer for custom architectures, and the kill-switch + CPU-oracle correctness discipline. The same stack that outruns llama.cpp on Apple Silicon.
• The Build System — the build tool built into superj: superj new/build/run/check/test, the Build.sj manifest, path & git dependencies, workspaces, profiles, build hooks, and feature flags.
• Structs: Zero-Overhead Wire Types — a step-by-step tutorial: SuperJ's native struct — packed little-endian layout that is the wire format, primitive/nested/fixed-array/enum fields, var-length bytes/string, the view()/bindTo() flyweight pattern, and the synthesized API.
• Building a Reusable Library — a step-by-step tutorial: create a library package (no entry), consume it from another project via a path or git dependency, and the workspace (monorepo) alternative.
• Memory Management Best Practices — how to keep a no-GC process flat: the single-thread license (static scratch buffers, no locks), the allocation ladder, arena blocks and their lexical-scoping rules, local stack allocation and its two traps, the scratch-buffer cookbook, and verifying flatness with the memory-event log.
• Coding Guidelines — three style rules learned the hard way: GC-free coding (the allocation ladder, the four warning flags, the review checklist), prefer switch over if/else if chains (jump table vs linear scan, always provide default), and prefer early return to reduce nesting (guard clauses first, safe from arena blocks, free).
• Writing & Running Tests — the sj.test unit-test framework: @Test/@Ignore, the Asserts vocabulary, superj test, and the golden-output suite.
• The Claim Layer — capabilities, architecture rules, and contracts: declare what each package may do, what it may import, and what its methods must guarantee — compiler-enforced, zero cost in release builds. Includes superj capabilities/superj topology, pure/noalloc, and a complete worked example.
• Concurrency: A Thesis — why SuperJ has no threads, why that's correct rather than limiting, and the three impossibility results (undecidable deadlock freedom, FLP, CAP) that make total-order event systems the right primitive instead of shared mutable state.
• Memory Safety & Security — why SuperJ doesn't have a borrow checker: the one class of bug it makes impossible isn't worth the permanent per-line tax for most software, and determinism is the stronger correctness property (every bug reproducible and fixable) versus memory safety's narrower guarantee (one bug class impossible).
• Memory-Event Log — tracking arena growth over time with --mem-track and superj memlog: the three-tier enablement model, reading the replay report (per-arena attribution, leak verdict, malloc-domain counters), live-tail, the in-process System.memReservedBytes() query, and the debug-build per-type histogram.
• Ecosystem — why "no package registry" misses the point: SuperJ is an LLVM language, so the compiled C-ABI core of every LLVM language's ecosystem (crypto, compression, numerical kernels, parsers) links via native for free; the source-ergonomic layer (derive macros, async desugaring) doesn't cross any language boundary, not even to C.