# 生命周期

四层对象，从长到短：**Engine → Script → VM → 调用**。搞清楚谁活多久，就知道状态该放哪。

```mermaid
flowchart TD
    E["Engine<br/>进程级"] --> S1["Script<br/>一份编译产物 + VM 池"]
    E --> S2["Script"]
    S1 --> P["VM 池<br/>无状态调用复用"]
    S1 --> I1["Instance<br/>独占 VM，你 Close"]
    S1 --> I2["Instance"]
    P --> V1["vmHandle"]
    P --> V2["vmHandle"]
    I1 --> V3["vmHandle"]
    I2 --> V4["vmHandle"]
```

| 层 | 活多久 | 谁结束它 |
| --- | --- | --- |
| `Engine` | 整个进程 | `Close()` |
| `Script` | 到下次热更新 | 被同名脚本顶替，或 `Engine.Close()` |
| VM（池里） | 不确定 | 出错被丢弃、池满被丢弃、`Script` 关闭 |
| VM（`Instance`） | 到你 `Close()` | **只有你**——本库不代管 |
| 作用域（ctx 里） | 跟着 ctx | 没有生命周期，只是数据载体 |

---

## Engine：只管配置，不追踪实例

Engine 持有白名单、超时策略、Loader、打包选项和编译产物缓存。它**不知道任何 Instance 的存在**——
没有会话注册表、没有按 key 复用、没有空闲回收器。

这是有意的：`New` 出来的实例由你拿着，生命周期归你；Engine 追踪它反而是多余的耦合，还要处理
"调用方忘了 Close 但 Engine 还引用着"导致的泄漏。

`Instance` 也不直接持有 Engine，它通过 `script.engine` 拿配置。

---

## Script：热更新时被顶替

```mermaid
stateDiagram-v2
    [*] --> 已编译: Compile / Loader 加载
    已编译 --> 已编译: 版本号没变，复用
    已编译 --> 新Script: 版本号变了，重新编译
    新Script --> [*]: 旧 Script.Close()
    已编译 --> [*]: Engine.Close()

    note right of 新Script
        旧 Script 上正在跑的调用
        会用旧版本跑完，不受影响
    end note
```

热更新时 Engine 造一个**新的** `Script` 顶替旧的，然后关掉旧的。已经拿着旧 `*Script` 指针的
调用会继续跑完旧版本；旧 `Script` 池里的 VM 被丢弃。

从旧 `Script` `New` 出来的实例不在这条链上——它们会因为 `script.closed` 而在下次调用时报
`ErrClosed`，VM 等 GC 回收。

版本号由 `Loader` 给。`jscriptx/esm` 用的是**参与打包的所有源文件**的 mtime+size 哈希——
所以改了被 `import` 的公共模块也会触发重编译。`node_modules` 里的文件不算在内，改依赖后要
显式 `Rebuild()`。

多层叠放（`WithLoader` 给多个）时，版本号会带上是第几层给的。这一步不能省：覆盖层的
脚本删掉后会落回下面那层，两层的版本号万一撞上，不带层号引擎就看不出脚本已经换了人，
会继续用旧的编译结果。

---

## VM 池：无状态调用

`Script.Call` 走这条。VM 从池里借，用完还回去：

```mermaid
stateDiagram-v2
    [*] --> 借出: newVM()（池里没有就现造）
    池中 --> 借出: borrow() 命中
    借出 --> 池中: release(healthy=true)
    借出 --> 丢弃: release(healthy=false)
    池中 --> 丢弃: Script.Close()
    借出 --> 丢弃: 池满

    note right of 丢弃
        超时、取消、panic 过的 VM
        一律不回池
    end note
```

两个刻意的设计：

**借不到不阻塞**——池空时直接新建一个。池只是复用缓存，不承担限流职责；并发超过池容量时
宁可临时多造几个 VM，也不让请求在这里排队。用完如果池满了，多出来的直接丢弃。

**坏 VM 不回池**——被中断或 panic 过的 VM 状态不确定，重建远比拖着它划算。

这条路径下**脚本里的 `this.xxx` 随时可能归零**：同一个业务流程的连续调用大概率落在不同 VM 上。
而且丢得没规律——低负载时可能一直命中同一个 VM，看着正常，一上量就出问题。

---

## Instance：当普通对象用

```mermaid
stateDiagram-v2
    [*] --> 就绪: New(ctx, args...)
    就绪 --> 执行中: acquire() 加锁
    执行中 --> 就绪: finish(healthy=true) 解锁
    执行中 --> 待重建: finish(healthy=false)
    待重建 --> 就绪: 下次调用惰性重建
    就绪 --> [*]: Close()

    note right of 待重建
        构造参数会重新传一遍
        但 this 上攒的状态归零
        Resets() 能查到次数
    end note
```

`New` 会**立刻建好 VM**，所以 `constructor` 抛异常在 `New` 当场就报（`Func` 字段是
`"constructor"`），不用等到第一次调用。

`acquire` 拿到的锁一直持到 `finish` 才放——这就是"同一实例的调用串行执行"的保证。
goja 的 Runtime 不是并发安全的，多个 goroutine 同时调同一个实例会排队，不同实例之间并行。

**出错会丢状态**：一次超时或 panic 让 VM 被丢弃，下次调用用全新实例重建。这把"状态随时可能丢"
降低成"只在脚本出错时丢"，**不是绝不丢**——真正不能丢的东西放作用域的扩展里（那是 Go 侧对象，
不随 VM 重建）。

**长期持有由你管**：本库没有按 key 复用和空闲回收。要按设备 ID 存着，业务侧自己一个 `sync.Map`，
跟 Go 版 controller 的写法一致。

---

## 作用域：没有生命周期的数据载体

作用域装在 ctx 里，只携带一段业务流程要共享的东西——**它不持有 VM，也不管实例的生死**。

```mermaid
flowchart TD
    CTX["ctx ─ scope"] --> K["key（标识，脚本里 scope.key）"]
    CTX --> G["ScopeGlobals（专属全局）"]
    CTX --> X["Extensions（你创建的对象）"]
    X --> V1["ctrlA 的 VM"]
    X --> V2["ctrlB 的 VM"]
    X --> V3["ctrlC 的 VM"]

    note1["同一份 Go 对象引用<br/>注入到各个 VM"]
    X -.- note1
```

扩展实例**由你创建**，所以 Go 侧和脚本读写的天然是同一份，不用再取回来：

```go
st := store.New()
ctx = jscriptx.WithScope(ctx, jscriptx.ScopeExtensions(st))
// …脚本里 store.Set("k", v)…
st.Get("k")
```

扩展的存活期就是你手里那个变量的存活期——`obj.Close()` 只释放实例的 VM，不碰扩展。

---

## 脚本级钩子：跑在临时 VM 里

`CallStatic` 调的是脚本导出的 class 上的**静态方法**，它跟实例的生命周期是分开的：

```mermaid
flowchart LR
    A["CallStatic(ctx, \"Startup\")"] --> B["建一个临时 VM"]
    B --> C["跑模块顶层"]
    C --> D["调静态方法<br/>**不构造实例**"]
    D --> E["丢弃 VM"]
    E --> F["副作用留在 Go 侧扩展里"]
```

两点跟 `Call` 不同，都是"静态"这个语义要求的：

- **不构造实例**——`constructor` 是"这一次调用的准备"，跟脚本级的初始化无关，跑它是白费
- **VM 用完就丢**，不回池——静态方法一般只在脚本生命周期里跑一两次

所以它**建不出能存活的 JS 对象**。用处是把配置写进 Go 侧的扩展，那些副作用留在 Go 那边，
后续每次调用都读得到。作用域扩展在静态方法里照常可用，这正是它的落点。

脚本没写这个静态方法时返回的错误能被 `errors.Is(err, ErrFuncNotFound)` 匹配——生命周期钩子
多半是可选的，用它区分"没写"和"写了但炸了"。

## 状态该放哪

```mermaid
flowchart TD
    A["要跨调用保持的东西"] --> B{"丢了会怎样"}
    B -->|"只是慢一点"| C["缓存"]
    B -->|"会算错"| D["状态"]
    C --> C1["可以放 this.xxx"]
    D --> D1{"用哪种调用"}
    D1 -->|"Script.Call 池化"| D2["必须放 Go 侧<br/>作用域扩展，或当参数传"]
    D1 -->|"Instance"| D3["可以放 this.xxx<br/>但脚本出错会归零"]
    D3 --> D4["绝对不能丢的<br/>放作用域扩展或落库"]
```

| | 实例生命周期 | 脚本里的 `this.xxx` |
| --- | --- | --- |
| `Script.Call` | = VM 生命周期 | 随时可能归零，**只能当缓存** |
| `Instance` | 由你 `Close` 决定 | 跨调用保持，出错时归零 |
| 作用域扩展 | 你手里的变量活多久 | 不受 VM 重建影响 |

还有一层容易忽略的：**多个脚本 `import` 同一个模块时，模块级状态也不共享**。模块被内联进各自的
产物是一层原因，更根本的是每个实例独占一个 VM，VM 之间不共享任何 JS 状态。公共的纯函数随便
`import`，公共的状态放作用域扩展。

---

## 并发粒度

| 场景 | 能并发吗 | 为什么 |
| --- | --- | --- |
| 不同实例（不同请求、不同设备） | ✅ | 各自独占 VM |
| 同一作用域下的不同 controller | ✅ | 各有各的 VM，只共享 Go 侧的扩展对象 |
| **同一个实例**的多次调用 | ❌ 串行 | Runtime 非并发安全，且要保住 `this.xxx` |
| 不带作用域的池化调用 | ✅ | 池里多个 VM |

只有第三种是串行的，那是必需的——跟 Go 侧用 `sync.Mutex` 保护 struct 字段是一回事。

共享数据靠扩展（Go 侧对象）而不是共用 Runtime：共用 Runtime 会让作用域内所有脚本被迫串行，
那才是真的并发瓶颈。

---

## 内存

每个实例独占一个 VM，3000 个实例的常驻内存实测：

| 配置 | 单实例 | 3000 个 |
| --- | --- | --- |
| 裸 VM | 7.0 KB | 20.5 MB |
| + `console` | 12.5 KB | 36.6 MB |
| + `console` + store 扩展 | 21.8 KB | 64.0 MB |

白名单、console、扩展都只在**建 VM 时**注入，对每次调用零影响。但每个实例一个 VM，这些会
乘以实例数——实例多又不需要脚本日志时，`WithLogger(nil)` 关掉 console 能省约 44%。

而且注入是**惰性**的：建 VM 时只装一个只读的访问器属性，脚本第一次读到那个全局名才把方法集
转成 JS 对象，转完在这个 VM 里缓存。一个脚本通常只用得上少数几个扩展，用不到的那些不该在
每次建 VM 时都付一遍转换成本。所以上表是"全都读到"的上界，实际按脚本用到多少收费。

建一个实例约 4.8 μs。这个数字对"每请求一个实例"的场景直接相关：QPS 1000、每请求 3 个
controller，约 14 ms/s 的 CPU。