SuperJ 手册

面向用户的 SuperJ 实操指南。（用 superj doc --list / superj doc <class-fqn> 浏览 SDK API。）

目录

• 总览（单页可视化） — 一个自包含的 HTML 页面，一眼展示这门语言：arena 内存模型、系统级能力特性、保留/弃用 Java 特性的清单，以及性能数据。在任何浏览器中打开即可。
• 快速开始 — SuperJ 是什么、为什么它是"super"的 Java（而非子集）、设计哲学，以及第一次构建。
• 语言参考 — Java → SuperJ 的差异点，一页可扫读：哪些相同、哪些移除、哪些改变、哪些新增，以及一张速查语法表。
• 构建世界上最快的 Web 服务器 — 一份分步教程：在内置网络栈上写一个 HTTP 服务器（随附的 demo/sj/demo/WebServer.sj），编译成单个原生二进制，运行它，并用 wrk 做压测。
• 编写 LLM 推理引擎 — 一份分步教程：用 sj.gpu 加载一个量化 GGUF 模型，四十行内完成 prefill + decode，诚实地基准测试（GPU 预热陷阱），下探到 Tensor 层做自定义架构，以及 kill switch + CPU 预言机的正确性纪律。同一套栈在 Apple Silicon 上跑赢 llama.cpp。
• 构建系统 — 内置于 superj 的构建工具：superj new/build/run/check/test、Build.sj 清单、路径与 git 依赖、工作区、profile、构建钩子与 feature flag。
• Struct：零开销线上类型 — 一份分步教程：SuperJ 的原生 struct — 紧凑小端布局就是线上格式、原语/嵌套/定长数组/enum 字段、变长 bytes/string、view()/bindTo() flyweight 模式，以及合成的 API。
• 构建可复用库包 — 一份分步教程：创建一个库包（无 entry），通过路径或 git 依赖从另一个项目消费它，以及工作区（monorepo）替代方案。
• 内存管理最佳实践 — 如何让无 GC 进程的内存保持平坦：单线程许可（static scratch 缓冲区、无锁）、分配阶梯、arena 块及其词法作用域规则、local 栈分配及其两个陷阱、scratch 缓冲区手册，以及用内存事件日志验证平坦性。
• 编码规范 — 三条吃亏后才学到的风格规则：无 GC 编码（分配阶梯、四个告警标志、审查清单）、优先 switch 而非 if/else if 链（跳转表 vs 线性扫描、总是提供 default）、以及优先提前返回以减少嵌套（守卫子句优先、从 arena 块提前返回安全、零成本）。
• 编写与运行测试 — sj.test 单元测试框架：@Test/@Ignore、Asserts 断言词汇、superj test，以及 golden-output（期望输出）测试套件。
• Claim 层 — capabilities、architecture 规则与 contracts：声明每个包可以做什么、可以 import 什么、其方法必须保证什么 — 编译器强制、release 构建零开销。包括 superj capabilities/superj topology、pure/noalloc，以及一个完整实例。
• 并发：一个论点 — 为什么 SuperJ 没有线程、为什么这是正确的选择而非限制，以及三个不可能性结论（不可判定的死锁自由、FLP、CAP）让全序事件系统成为比共享可变状态更合适的原语。
• 内存安全与安全 — 为什么 SuperJ 没有借用检查器：它所消除的那一类 bug，对大多数软件而言不值得为之付出永久的逐行税；而确定性是更强的正确性属性（每个 bug 都可复现、可修复），相比之下内存安全只是更窄的保证（一类 bug 不可能发生）。
• 内存事件日志 — 用 --mem-track 与 superj memlog 追踪 arena 随时间的增长：三层启用模型、读回放报告（每 arena 归因、泄漏判定、malloc 域计数器）、实时 tail、进程内 System.memReservedBytes() 查询，以及 debug 构建的逐类型直方图。
• 生态 — 为什么"没有包注册中心"没抓住要点：SuperJ 是一门 LLVM 语言，因此每个 LLVM 语言生态中编译后的 C-ABI 核心（加密、压缩、数值内核、解析器）都可以通过 native 免费链接；而源码人体工学层（derive 宏、async 脱糖）任何语言边界都跨不过去，连到 C 也不行。