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.
• JSON: Parsing and Building Without Garbage — the sj.json incremental parser and streaming builder: the one-shot API, then the zero-garbage reuse pattern (parseInto/*Into navigation, a reused JsonBuilder + output buffer).
• 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 ambient-scoping rules and carve-outs, 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.
• Logging — the sj.util.logging framework: fluent API, log levels, file formats (PLAIN/BINARY), roll policies (ROLL/RING), memory-mapped crash-safe writes, custom loggers, and where to find log files.
• 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 Tools: Finding Out What Your Program Is Holding — the diagnosis instruments and the order to use them: memTouchedBytes() and superj test --check-growth to see growth at all, --mem-debug and System.memReport() to attribute it to a source line, and System.memAudit() for the question the others cannot answer — whether the memory is retained (a cache, a static) or merely unscoped garbage, which have opposite fixes. Includes what each tool cannot see, and a worked case study.
• Runtime Environment Variables — every variable a compiled binary reads, and what setting none of them gets you: the arena ceiling SJ_ARENA_MAX (80% of the process's memory budget by default, cgroup limits included) and what a breach prints, the chunk-sizing knobs SJ_ARENA_INITIAL/SJ_ARENA_SOLE_MIN, SUPERJ_STACKTRACE's three states and their measured cost, the --mem-track/--mem-debug log knobs, and SJ_INFLATE_MAX, SJ_NANOTIME, SUPERJ_GPU.
• 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.
• Cryptography — the full crypto SDK: hashing (SHA-256, SHA-512, SHA-384, RIPEMD-160, Keccak-256, BLAKE3), signatures (Ed25519, secp256k1, P-256, P-384, BLS12-381, RSA), key exchange (X25519), symmetric (AES-128-GCM, AES-256-CBC, HMAC, HKDF), encoding (Base58, CBOR, COSE_Sign1), Ethereum (EIP-712, address derivation), and web auth (JWS, CSR, X.509, PEM, TLS 1.3).
• S3-Compatible Multipart Upload — sj.aws/sj.aws.s3: SigV4 request signing over NioAdapter's TLS transport, credentials, the four multipart calls plus the uploadFile orchestration helper, and — before any of that — what endpoints this can and can't actually reach today.