Ue Async Threading

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.

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;  // TArray<FGraphEventRef, TInlineAllocator<4>>
Prerequisites.Add(SomePriorEvent);

FGraphEventRef TaskEvent = TGraphTask<FMyGraphTask>::CreateTask(&Prerequisites)
    .ConstructAndDispatchWhenReady(42);  // args forwarded to constructor

FTaskGraphInterface::Get().WaitUntilTaskCompletes(TaskEvent, ENamedThreads::GameThread);

Quick dispatch (no custom class needed):

AsyncTask(ENamedThreads::GameThread, [this]()
{
    MyActor->UpdateHealth(NewValue); // safe — runs on game thread
});

UE::Tasks::Launch (Modern Preferred API)

Recommended for new code (UE 5.0+). Simpler syntax than TaskGraph, automatic thread pool dispatch, built-in chaining.

#include "Tasks/Task.h"

UE::Tasks::TTask<int32> Task = UE::Tasks::Launch(
    UE_SOURCE_LOCATION,
    []() { return ExpensiveComputation(); }
);
int32 Result = Task.GetResult(); // blocks until complete

// With prerequisites
UE::Tasks::TTask<FVector> TaskA = UE::Tasks::Launch(UE_SOURCE_LOCATION,
    []() { return ComputePosition(); });

UE::Tasks::TTask<void> TaskB = UE::Tasks::Launch(UE_SOURCE_LOCATION,
    [&TaskA]() { ProcessPosition(TaskA.GetResult()); },
    UE::Tasks::Prerequisites(TaskA)
);

TTask<T> API: GetResult() blocks and returns result. IsCompleted() non-blocking. Wait() / Wait(FTimespan) for timed blocking. TryRetractAndExecute() runs inline if not yet started (work stealing).

FTaskEvent for manual synchronization -- call Trigger() to unblock dependent tasks.

Async, TFuture, and TPromise

Async() is the most flexible one-shot dispatch. Returns TFuture<T> with execution context control.

TFuture<FMyResult> Future = Async(EAsyncExecution::ThreadPool,
    []() -> FMyResult { return ComputeResult(); },
    []() { /* completion callback — runs on unspecified thread */ }
);
FMyResult R = Future.Get(); // blocks, does NOT invalidate (unlike std::future)

EAsyncExecution modes:

Convenience: AsyncPool(GThreadPool, Lambda), AsyncThread(Lambda, StackSize, Priority).

TFuture<T> API

Key difference from std::future: Get() does not invalidate. Call it multiple times safely. Consume() invalidates like std::future::get().

• IsReady() -- non-blocking check