1
// 具体到代码层面：
2
UCLASS()
3
class UMyObject : public UObject
4
{
5
public:
6
    UPROPERTY()
7
    int32 Value;  // ← 没有任何 mutex 保护！
8

9
    void Modify()
10
    {
11
        Value++;  // ← 这不是原子操作！
12
        // 在多线程下：读 → 加 1 → 写，三步之间可能被其他线程打断
13
    }
14
};
15

16
// GameThread 的严格约束是 Epic 做的一个 工程权衡：
17
// 单线程假设 → 代码更简单 → 更容易维护千万行引擎代码
18
// 代价 → 你需要学会如何把非 UObject 的工作分发到其他线程
19

20
// ==== 引擎如何在底层强制拦截跨线程访问？====
21
// 1. check(IsInGameThread()) —— 散布在核心逻辑（物理更新、组件注册、
22
//    Actor 生成等）中的断言大闸。如果你在后台线程触发了这些代码，
23
//    Development 构建中直接断言崩溃，精确定位违规位置。
24
// ★ Shipping 警告：check() 在 SHIPPING=1 时被完全抽离（Compile Out）——
25
//    跨线程非法篡改 UObject 在 Shipping 中不会断言崩溃，而是直接引发
26
//    随机内存损坏（Memory Corruption）或间歇性闪退，极难排查！
27
// 2. checkNoReentry —— 防重入保护，防止同一函数在同一线程上递归调用
28
//    导致的栈溢出或逻辑混乱。
29
// 3. 渲染线程侧：ENQUEUE_RENDER_COMMAND 内部不仅不能碰 UObject，
30
//    如果涉及图形硬件交互，必须确保 GDynamicRHI 已初始化完毕。
31
//    （在引擎启动的早期阶段，GDynamicRHI 可能为 nullptr）

1
// ===== 定义工作线程 =====
2
class FMyWorker : public FRunnable
3
{
4
public:
5
    FMyWorker()
6
        : bShouldStop(false)
7
    {
8
        // 创建事件用于线程间信号——默认非信号态，手动重置
9
        WorkReadyEvent = FPlatformProcess::CreateSynchEvent(false);
10

11
        Thread = FRunnableThread::Create(
12
            this,                      // FRunnable 实例
13
            TEXT("MyWorkerThread"),    // 线程名（调试器可见）
14
            0,                         // 栈大小（0 = 默认）
15
            TPri_Normal                // 优先级
16
        );
17
    }
18

19
    virtual ~FMyWorker()
20
    {
21
        // 析构前必须确保线程已停止
22
        Stop();
23
        if (Thread)
24
        {
25
            Thread->WaitForCompletion();  // 等待线程结束
26
            delete Thread;
27
        }
28
        // 删除事件，释放内核资源
29
        if (WorkReadyEvent)
30
        {
31
            FPlatformProcess::DeleteSynchEvent(WorkReadyEvent);
32
            WorkReadyEvent = nullptr;
33
        }
34
    }
35

36
    // 线程启动时调用一次——做初始化
37
    virtual bool Init() override
38
    {
39
        return true;  // 返回 true = 初始化成功，线程继续
40
                      // 返回 false = 线程中止
41
    }
42

43
    // 线程的主循环——事件驱动，不轮询
44
    virtual uint32 Run() override
45
    {
46
        while (!bShouldStop)
47
        {
48
            // ✗ 业余写法：FPlatformProcess::Sleep(0.01f);
49
            //    固定 Sleep 10ms → 数据响应延迟高达 10ms！
50
            //    在高频传感器、网络 I/O 等场景中不可接受
51

52
            // ✓ 工业级写法：事件驱动——通过 FEvent 阻塞等待
53
            WorkReadyEvent->Wait();  // 无开销的阻塞挂起
54
            //   ↑ 主线程调用 WorkReadyEvent->Trigger() 时瞬间唤醒
55

56
            // 处理工作...
57
            DoWork();
58
        }
59
        return 0;
60
    }
61

62
    // 只有在无法挂起的极少数高频死循环中，才允许：
63
    // FPlatformProcess::Sleep(0.0f);  // 仅让出当前 CPU 时间片
64

65
    // 请求停止——通常在析构时调用
66
    virtual void Stop() override
67
    {
68
        bShouldStop = true;
69
        // 触发事件唤醒线程——否则线程可能挂在 Wait() 上永远不出来
70
        if (WorkReadyEvent)
71
        {
72
            WorkReadyEvent->Trigger();
73
        }
74
    }
75

76
private:
77
    FRunnableThread* Thread = nullptr;
78
    FThreadSafeBool bShouldStop;     // 用 FThreadSafeBool，不是普通 bool！
79
    FEvent* WorkReadyEvent = nullptr; // 事件——用于线程间唤醒
80
};
81

82
// ===== 使用 =====
83
FMyWorker* Worker = new FMyWorker();
84
// Worker 在后台运行...
85
// 不再需要时：
86
delete Worker;  // 析构函数中调用了 Stop() + WaitForCompletion()

1
#include "Tasks/Task.h"
2

3
// ===== 提交一个任务到后台线程 =====
4
UE::Tasks::Launch(TEXT("MyHeavyComputation"), []() {
5
    // 在这里做纯计算——不要碰 UObject！
6
    TArray<FVector> Results;
7
    for (int i = 0; i < 100000; i++)
8
    {
9
        Results.Add(HeavyComputation(i));
10
    }
11

12
    // ✓ 计算完成后，回到 GameThread 安全地更新 UObject：
13
    AsyncTask(ENamedThreads::GameThread, [Results = MoveTemp(Results)]() {
14
        // 注意：回到 GameThread 的跳转仍可用 AsyncTask（这是它唯一合理的场景）
15
        for (AActor* Actor : SomeActors)
16
        {
17
            Actor->SetActorLocation(Results[0]);  // ✓ 安全！
18
        }
19
    });
20
});
21

22
// ===== 带依赖关系的任务链 =====
23
UE::Tasks::FTask TaskA = UE::Tasks::Launch(TEXT("StepA"), []() {
24
    // 第一步计算
25
    return LoadRawData();
26
});
27

28
UE::Tasks::FTask TaskB = UE::Tasks::Launch(TEXT("StepB"), []() {
29
    // 第二步计算（依赖 TaskA 的结果）
30
}, UE::Tasks::Prerequisites(TaskA));  // ← TaskB 在 TaskA 完成后才执行
31

32
// ===== 等待所有任务完成 =====
33
TArray<UE::Tasks::FTask> Tasks;
34
for (int i = 0; i < 100; i++)
35
{
36
    Tasks.Add(UE::Tasks::Launch(TEXT("BatchTask"), [i]() {
37
        ProcessBatch(i);
38
    }));
39
}
40
UE::Tasks::Wait(Tasks);  // 阻塞直到所有任务完成

1
// ===== 任务线程类型（ENamedThreads::Type）=====
2

3
// GameThread — 主线程，唯一可以操作 UObject 的线程
4
ENamedThreads::GameThread
5

6
// 渲染线程 — 处理渲染命令（不要直接在上面做游戏逻辑）
7
ENamedThreads::ActualRenderingThread  // ★ 注意：不是 RendererThread！
8

9
// RHI 线程 — 图形 API 调用（DirectX/Vulkan），比渲染线程更底层
10
ENamedThreads::RHIThread
11

12
// 后台线程池 — 通用后台工作
13
ENamedThreads::AnyBackgroundThreadNormalTask   // 普通优先级
14
ENamedThreads::AnyBackgroundHiPriTask          // 高优先级
15

16
// 你通常只关心两个：
17
// → GameThread（回到主线程更新 UObject）
18
// → AnyBackgroundThreadNormalTask（分发纯计算到后台）

1
// 如果你在维护 UE4 升级上来的老项目，可能还会看到：
2
#include "Async/Async.h"
3

4
// 旧版用法——不推荐在新代码中使用：
5
AsyncTask(ENamedThreads::AnyBackgroundThreadNormalTask, []() {
6
    DoWork();
7
});
8

9
// 旧版 Async(TFuture) 的返回值处理：
10
TFuture<int32> Future = Async(EAsyncExecution::ThreadPool, []() -> int32 {
11
    return HeavyComputation();
12
});
13
int32 Result = Future.Get();  // ⚠️ 阻塞调用线程！不要在 GameThread 上做
14

15
// 新代码请改用 UE::Tasks::Launch

1
UCLASS()
2
class UMyComponent : public UActorComponent
3
{
4
    void DoAsync()
5
    {
6
        // ✗ 危险！this 可能在 Lambda 执行前被 Destroy
7
        UE::Tasks::Launch(TEXT("BadTask"), [this]() {
8
            // this 指向的 UMyComponent 可能已经被 GC 回收了！
9
        });
10

11
        // ✓ 安全方式：用 TWeakObjectPtr
12
        TWeakObjectPtr<UMyComponent> WeakThis(this);
13
        UE::Tasks::Launch(TEXT("GoodTask"), [WeakThis]() {
14
            // 后台线程中 不能 调用 WeakThis.IsValid()！
15
            // IsValid() 内部查 GUObjectArray，有线程冲突风险
16
            // → 后台只做纯计算，不接触 UObject 和 IsValid()
17
            int32 Result = Compute();
18

19
            // 回到 GameThread 后 才能 安全调用 IsValid()：
20
            AsyncTask(ENamedThreads::GameThread, [WeakThis, Result]() {
21
                if (WeakThis.IsValid())  // ← 只在 GameThread 上调用！
22
                {
23
                    WeakThis->ApplyResult(Result);  // ✓ 安全
24
                }
25
            });
26
        });
27
    }
28
};

1
// ParallelFor：将一个 for 循环的工作自动拆分成多个线程并行执行
2
// 适用条件：每次迭代是独立的、不依赖其他迭代的结果
3

4
TArray<FVector> Vertices;
5
Vertices.SetNum(100000);  // 先分配好大小！
6

7
// ===== 最简形式 =====
8
ParallelFor(Vertices.Num(), [&](int32 Index) {
9
    // Index 从 0 到 Vertices.Num() - 1
10
    // 不同的 Index 可能在不同线程上同时执行！
11
    Vertices[Index] = ComputeVertex(Index);
12
});
13
// ParallelFor 返回时，所有迭代都已完成
14

15
// ===== 控制并行粒度 =====
16
// 标准 ParallelFor 第三参数接受 EParallelForFlags 或 bool，不接受纯 int
17
ParallelFor(Vertices.Num(), [&](int32 Index) {
18
    Vertices[Index] = Normalize(Vertices[Index]);
19
}, EParallelForFlags::None);
20
// 如需精细控制分块大小，使用 ParallelForWithPreInit 或手动按批次 dispatch
21

22
// ===== TArray 的并发写入在逻辑上是安全的 =====
23
// 因为每个线程写不同的索引位置（无竞争），所以不需要加锁：
24
ParallelFor(Vertices.Num(), [&](int32 Index) {
25
    Vertices[Index] = Process(Vertices[Index]);
26
    // ✓ 逻辑安全：不同 Index 写入不同内存位置，无数据竞争
27
});
28

29
// ⚠️ 但有一个隐藏的性能杀手——伪共享（False Sharing）
30
// 当多个线程同时写入连续且尺寸较小的元素（如 float、int32）时，
31
// 如果相邻索引落在同一个 CPU 缓存行（Cache Line，通常 64 字节）内：
32
//
33
//   | 线程 A 写 [0] | 线程 B 写 [1] | 线程 C 写 [2] | ...
34
//   |←—————— 同一个 Cache Line (64B) ——————→|
35
//
36
// → 各核心的 L1/L2 缓存频繁发生 Cache Invalidation Bounce
37
// → CPU 在硬件层面反复拉锯等待
38
// → ParallelFor 反而比单线程还慢！
39
//
40
// 规避方式：
41
// 1. 手动按批次 dispatch（如每 256 个元素一组），增大每次迭代的工作量
42
// 2. 用局部变量缓冲计算结果，最后一次性写回
43
// 3. 处理大尺寸元素（如 FVector/FMatrix）时通常不受影响
44

45
### 7.4.2 ⚠️ ParallelFor 内不能做的事
46

47
```cpp
48
ParallelFor(1000, [&](int32 Index) {
49
    // ✗ 不能访问 UObject！
50
    // SomeActor->SetActorLocation(...);  // 崩溃！
51

52
    // ✗ 不能 Add 到同一个 TArray——这不是线程安全的
53
    // SharedArray.Add(Index);  // 数据竞争！需要加锁
54

55
    // ✗ 不能访问非原子的共享变量
56
    // SharedCounter++;  // 数据竞争！
57

58
    // ✓ 读取不会变的共享数据
59
    float Val = ReadOnlyConfig[Index];  // 只要 ReadOnlyConfig 不被改变
60

61
    // ✓ 写入预分配好的不同索引位置
62
    PreallocatedArray[Index] = Result;  // 每个线程写不同的位置
63
});

1
#include "HAL/CriticalSection.h"
2

3
class FThreadSafeCounter
4
{
5
    FCriticalSection CriticalSection;  // = std::mutex
6
    int32 Value = 0;
7

8
public:
9
    void Increment()
10
    {
11
        FScopeLock Lock(&CriticalSection);  // = std::lock_guard
12
        // ↑ 构造时自动 Lock()，析构时自动 Unlock()
13
        //   即使函数中途 return 或抛异常，也会安全释放
14
        Value++;
15
    }
16

17
    int32 GetValue()
18
    {
19
        FScopeLock Lock(&CriticalSection);
20
        return Value;
21
    }
22
};
23

24
// ===== 等价的标准 C++ 写法 =====
25
// FCriticalSection   = std::mutex（UE4 时代的标准锁）
26
// FScopeLock          = std::lock_guard<std::mutex>
27
// FScopeTryLock       = std::try_lock
28

29
// ===== 现代 UE5 推荐：UE::FMutex（Misc/Mutex.h）=====
30
// UE::FMutex 是 UE5 引入的现代轻量级互斥锁，建议逐步替代 FCriticalSection：
31
//
32
// #include "Misc/Mutex.h"
33
// UE::FMutex MyMutex;
34
// {
35
//     std::lock_guard<UE::FMutex> Lock(MyMutex);  // 兼容 C++ 标准锁接口！
36
//     SharedValue++;
37
// }
38
//
39
// 优势：与 std::unique_lock / std::lock_guard 原生兼容，开销更低，
40
//       避免了 FCriticalSection 的平台特化实现差异（Windows 临界区 vs Unix pthread）

1
#include "HAL/PlatformAtomics.h"
2

3
// TAtomic = std::atomic<T>
4
// 不需要加锁的线程安全操作，开销远小于 FCriticalSection
5

6
TAtomic<int32> Counter(0);
7

8
// 原子递增
9
++Counter;               // 前置递增（原子），返回新值（TAtomic 对齐 std::atomic，用运算符）
10
int32 Old = Counter++;   // 后置递增（原子），返回旧值
11

12
// 原子递减（TAtomic 无 Increment/Decrement 方法，用运算符）
13
--Counter;               // 前置递减（原子）
14

15
// 原子读写
16
Counter.Store(42);       // 等价于 Counter = 42（原子写入）
17
int32 Val = Counter.Load();  // 原子读取
18

19
// 原子比较交换（CAS，无锁编程的核心原语）：
20
int32 Expected = 0;
21
int32 Desired = 1;
22
if (Counter.CompareExchange(Expected, Desired))
23
{
24
    // CAS 成功：Counter 之前是 0，现在被设为 1
25
}
26
else
27
{
28
    // CAS 失败：Counter 之前不是 0，Expected 被更新为 Counter 的当前值
29
}
30

31
// ===== FThreadSafeBool / FThreadSafeCounter =====
32
// 引擎的便捷包装，底层用的就是 TAtomic
33
FThreadSafeBool bIsRunning(true);
34
FThreadSafeCounter CompletedTaskCount;

1
// FEvent = 条件变量 + 事件的 UE 封装
2
// 用于一个线程等待另一个线程的信号
3

4
// 创建事件（RAII 自动管理：构造中 CreateSynchEvent，析构中 DeleteSynchEvent）
5
FScopedEvent Event;
6

7
// 工作线程——等待信号
8
void WorkerThread(FEvent* Event)
9
{
10
    while (true)
11
    {
12
        Event->Wait();           // 阻塞，直到被 Trigger
13
        // 收到信号，处理工作...
14
        DoWork();
15
        Event->Reset();          // 清除信号，准备下一次等待
16
    }
17
}
18

19
// 主线程——发送信号
20
void MainThread(FEvent* Event)
21
{
22
    // 准备数据...
23
    PrepareWork();
24
    Event->Trigger();            // 发送信号，唤醒工作线程
25
}

1
#include "RenderingThread.h"
2

3
// 渲染线程是独立于 GameThread 的——你不能直接在 GameThread 上
4
// 操作渲染资源（纹理、网格缓冲等），必须通过渲染命令：
5

6
// ===== 发送一个命令到渲染线程 =====
7
ENQUEUE_RENDER_COMMAND(FMyRenderCommand)(
8
    [](FRHICommandListImmediate& RHICmdList)
9
    {
10
        // 这段代码在渲染线程中执行
11
        // 可以安全地操作渲染资源
12
        // 不能访问 UObject（除了特别允许的渲染相关类型）
13
    }
14
);
15
// ENQUEUE_RENDER_COMMAND 立即返回，Lambda 稍后在渲染线程执行