/ue-async-threading

name: ue-async-threading
description: "Use this skill when working with Unreal Engine async operations, threading, parallel execution, or concurrency. Also use when the user mentions 'FRunnable', 'FAsyncTask', 'TaskGraph', 'UE::Tasks', 'ParallelFor', 'TFuture', 'TPromise', 'Async()', 'thread safety', 'FCriticalSection', 'FRWLock', 'background thread', 'game thread dispatch', or 'thread pool'. For networking async (RPCs, replication), see ue-networking-replication. For asset streaming, see ue-data-assets-tables."
metadata:
  version: 1.0.0

UE Async and Threading

You are an expert in Unreal Engine's threading model, async task systems, and concurrent programming patterns.

Context Check

Read `.agents/ue-project-context.md` before proceeding. Engine version matters: `UE::Tasks::Launch` is the modern preferred API (UE 5.0+), while `FAsyncTask` and TaskGraph remain fully supported. Determine: What work needs to be offloaded? Is UObject access required? What latency/throughput tradeoff is acceptable?

Information Gathering

Ask the user if unclear:

• **Offload type** — CPU-bound computation, I/O wait, or periodic background work?
• **UObject interaction** — Does the background work need to read/write UObject state?
• **Lifetime** — One-shot task, recurring work, or long-lived thread?
• **Result delivery** — Fire-and-forget, or does the game thread need results back?

---

UE Threading Model

UE runs several named threads plus a scalable worker pool. Understanding which thread owns what prevents the most common threading bugs.

**Named threads:**

• **Game Thread** — All UObject access, Blueprint execution, gameplay logic. Check with `IsInGameThread()`.
• **Render Thread** — Render commands, scene proxy updates. `IsInRenderingThread()`.
• **RHI Thread** — GPU command submission (platform-dependent).
• **Worker Threads** — Unnamed pool threads for task dispatch. Count scales with CPU cores.

**The golden rule:** UObjects are game-thread-only. No UPROPERTY reads, no UFUNCTION calls, no `GetWorld()`, no spawning from background threads. Violating this causes intermittent crashes that depend on GC timing and are extremely difficult to diagnose.

---

Pattern Selection Guide

Choose the simplest API that fits your needs.

| Pattern | Best For | Lifetime | Result? | |---------|----------|----------|---------| | `AsyncTask(GameThread, Lambda)` | Dispatch to game thread from background | One-shot | No | | `UE::Tasks::Launch` | General async work (preferred, UE5+) | One-shot | `TTask<T>` | | `Async(EAsyncExecution, Lambda)` | Flexible dispatch with `TFuture` | One-shot | `TFuture<T>` | | `FAsyncTask<T>` | Reusable pooled work units | Reusable | Via `GetTask()` | | `FAutoDeleteAsyncTask<T>` | Fire-and-forget pooled work | One-shot | No | | `TGraphTask<T>` | Complex dependency graphs | One-shot | `FGraphEvent` | | `ParallelFor` | Data-parallel loops | Blocking | No | | `FRunnable` + `FRunnableThread` | Long-lived dedicated threads | Persistent | Manual |

---

FRunnable and FRunnableThread

Use `FRunnable` only when you need a **dedicated, long-lived thread** -- a socket listener, a file watcher, or a continuous processing loop. For one-shot work, prefer `UE::Tasks::Launch` or `FAsyncTask`.

**Lifecycle:** `Init()` (new thread) -> `Run()` (new thread) -> `Exit()` (new thread, after Run returns). `Stop()` is called externally to request shutdown.

**FRunnableThread::Create** signature: `static FRunnableThread* Create(FRunnable*, const TCHAR* ThreadName, uint32 StackSize = 0, EThreadPriority = TPri_Normal, uint64 AffinityMask, EThreadCreateFlags)`.

**Key points:** `Stop()` signals the thread -- it does not block. `Kill(true)` calls `Stop()` then waits for completion. Always `delete` the `FRunnableThread*` after `Kill`. Use `std::atomic<bool> bShouldStop` in `Run()` loop, set it in `Stop()`.

See `references/threading-patterns.md` for a complete `FRunnable` subclass template with proper shutdown.

---

FAsyncTask and FAutoDeleteAsyncTask

For **reusable work units** on the engine thread pool (`GThreadPool`). Subclass `FNonAbandonableTask` and implement `DoWork()` + `GetStatId()`.

class FMyComputeTask : public FNonAbandonableTask
{
    friend class FAsyncTask<FMyComputeTask>;
    int32 Result = 0;
    TArray<int32> InputData;

    FMyComputeTask(TArray<int32> InData) : InputData(MoveTemp(InData)) {}

    void DoWork()
    {
        for (int32 Val : InputData) { Result += Val; }
    }

    FORCEINLINE TStatId GetStatId() const
    {
        RETURN_QUICK_DECLARE_CYCLE_STAT(FMyComputeTask, STATGROUP_ThreadPoolAsyncTasks);
    }
};

**Usage:**

// Reusable — you manage lifetime
auto* Task = new FAsyncTask<FMyComputeTask>(MoveTemp(Data));
Task->StartBackgroundTask();          // dispatches to GThreadPool
Task->EnsureCompletion();             // blocks or runs inline if not started
int32 R = Task->GetTask().Result;
delete Task;

// Fire-and-forget — auto-deletes on completion
(new FAutoDeleteAsyncTask<FMyComputeTask>(MoveTemp(Data)))->StartBackgroundTask();

`IsWorkDone()` is the non-blocking completion check. `Cancel()` prevents execution if not yet started. `StartSynchronousTask()` runs inline on the calling thread.

---

TaskGraph

For work with **complex dependency chains**. Each task declares prerequisites; the scheduler handles ordering.

class FMyGraphTask
{
public:
    FMyGraphTask(int32 InValue) : Value(InValue) {}

    static ESubsequentsMode::Type GetSubsequentsMode()
    { return ESubsequentsMode::TrackSubsequents; }

    ENamedThreads::Type GetDesiredThread()
    { return ENamedThreads::AnyThread; }

    TStatId GetStatId() const
    { RETURN_QUICK_DECLARE_CYCLE_STAT(FMyGraphTask, STATGROUP_TaskGraphTasks); }

    void DoTask(ENamedThreads::Type CurrentThread, const FGraphEventRef& MyCompletionGraphEvent)
    { /* work here */ }

private:
    int32 Value;
};

**Dispatching with prerequisites:**

FGraphEventArray Prerequisites;