Unity中NativeHashMap为何在主线程调用时抛出Burst编译异常？

Question

在Unity中，NativeHashMap本身是线程安全的原生容器，但**Burst编译器仅支持在Job System调度的、标记为`IJob`或`IJobParallelFor`的作业中使用它**。若在主线程（如`MonoBehaviour.Update()`）直接调用其`TryAdd()`、`ContainsKey()`等方法，虽能通过C#编译，却会在Burst编译阶段报错（如“Cannot use NativeContainer on the main thread”）。根本原因在于：Burst为保证零成本抽象与确定性执行，**强制要求所有NativeContainer（含NativeHashMap）必须绑定有效的`[WriteOnly]`/`[ReadOnly]`权限标签，并由Job系统统一管理生命周期与内存访问权限**——主线程无Job上下文，无法提供该元信息，导致Burst拒绝编译。这不是运行时异常，而是编译期约束。正确做法是将操作封装进Job，并通过`JobHandle.Schedule()`触发；若需主线程交互，应通过`NativeArray`暂存结果后拷贝回托管内存。

Answer 1

```html

一、现象层：编译期报错的直观表现

在 Unity 2021.3+（含 DOTS 1.0+）中，开发者常在 MonoBehaviour.Update() 中直接调用 nativeHashMap.TryAdd(key, value)，C# 编译器静默通过，但 Burst 编译器在构建时抛出明确错误：

CSError: Cannot use NativeContainer on the main thread (NativeHashMap<int, float>)

该错误不触发运行时崩溃，而是在 ILPostProcessor 阶段中断构建流程，导致无法生成高效原生代码。这是绝大多数初学者遭遇的第一个“Burst 黑箱”。

二、机制层：Burst 的内存契约模型

Burst 不是普通 JIT/AOT 编译器，而是基于 LLVM 的确定性零抽象开销编译器。它要求所有 NativeContainer（含 NativeHashMap、NativeArray、NativeList）必须满足以下硬性契约：

• ✅ 绑定显式线程访问标签：[ReadOnly] / [WriteOnly] / [DeallocateOnJobCompletion]
• ✅ 生命周期由 JobHandle 管理（分配 → 调度 → 完成 → 释放）
• ❌ 主线程无 Job 上下文 → 无法注入内存屏障、无法验证别名安全性、无法插入生命周期钩子

三、架构层：NativeHashMap 的双重身份解耦

维度	线程安全层（Runtime）	Burst 可编译层（Compile-time）
本质	底层使用原子操作 + 内存栅栏（如 Atomic.CompareExchange）实现并发安全	依赖 Job System 提供的 JobCompilerContext 注入权限元数据
约束来源	Unity C# Runtime（JobsUtility）	Burst Compiler（Burst.Compiler.IL）

四、实践层：合规接入路径全景图

flowchart TD A[主线程需求] --> B{是否需实时响应？} B -->|否| C[封装为 IJobParallelFor
批量处理键值对] B -->|是| D[封装为 IJob
单次原子操作] C --> E[Schedule() → JobHandle] D --> E E --> F[JobHandle.Complete()
或 JobHandle.Schedule().Complete()] F --> G[NativeArray<Result>
拷贝至托管数组] G --> H[Update UI/State]

五、代码层：最小可运行范式

// ✅ 正确：IJob 封装写入逻辑
public struct HashMapWriteJob : IJob
{
    [WriteOnly] public NativeHashMap<int, float>.Concurrent hashMap;
    public int key; public float value;

    public void Execute() => hashMap.TryAdd(key, value);
}

// ✅ 主线程调度与结果回传
var job = new HashMapWriteJob { 
    hashMap = nativeHashMap.AsConcurrent(), 
    key = 42, value = 3.14f 
};
var handle = job.Schedule(); // 触发 Burst 编译 & 异步执行
handle.Complete(); // 同步等待（生产环境建议用依赖链）

六、进阶层：跨线程交互的三种模式对比

• 模式1（同步阻塞）：主线程调用 JobHandle.Complete() —— 简单但牺牲帧率，适合初始化阶段
• 模式2（异步回调）：用 JobHandle.Schedule(() => OnJobDone()) —— 需配合 Unity.Jobs.LowLevel.Unsafe.JobRanges
• 模式3（双缓冲流水线）：维护两组 NativeArray<Result>，交替读写 —— 实现 100% 无锁帧间通信

七、陷阱层：高频反模式警示

⚠️ 反模式1：在 IJob 中调用 Debug.Log() —— Burst 不支持托管调用，编译失败
⚠️ 反模式2：将 NativeHashMap 字段声明为 public 且未加权限标签 —— Burst 拒绝识别为 NativeContainer
⚠️ 反模式3：在 OnDestroy() 中直接调用 nativeHashMap.Dispose() 而未检查 IsCreated —— 引发 Native Leaks 报警

八、演进层：DOTS 2.0 的新动向

Unity 2023.2+ 引入 EntityCommandBuffer.ParallelWriter 与 SystemAPI.Query，正逐步将 NativeHashMap 的使用场景收敛至：
• 临时计算缓存（如 A* 寻路 OpenSet/ClosedSet）
• 作业间中间状态聚合（替代 Dictionary<TKey, List<TValue>>）
• GPU-CPU 协同键值索引（配合 GraphicsBuffer 映射）
未来版本将通过 UnsafeHashMap 提供更细粒度的内存控制权。

```