Skip to main content
Version: Next

Thread Boundaries of FStreamableManager Async Callbacks

FStreamableManager::RequestAsyncLoad is the most common entry point for async asset loading. It does not by itself decide which thread the callback runs on — that semantics is decided jointly by how the caller binds the delegate and by the dispatch path taken when loading completes. Getting the boundary right is the precondition for reasoning about UObject lifetime during loading.

Request and handle​

A typical request returns a TSharedPtr<FStreamableHandle>, which is both the cancellation entry point and the reference that keeps the request alive:

TSharedPtr<FStreamableHandle> Handle = StreamableManager.RequestAsyncLoad(
AssetSoftPath,
FStreamableManagerDelegate::CreateUObject(this, &UMyLoader::OnLoaded),
FStreamableManager::AsyncLoadHighPriority
);
StateHandle behaviourWatch out for
LoadingIsLoadingInProgress() is trueYou must hold the handle, or the request may be released early
CompletedHasLoadCompleted() is trueThe callback has been dispatched; the handle can still query the loaded asset
CancelledAfter CancelHandle()The callback is no longer guaranteed to fire; clean up the waiting state yourself

Thread semantics of the callback​

Key conclusion: do not read "async load" as "the callback runs on a background thread". Dispatch depends on the delegate binding and on the loading policy at the call site. In production code, collapse that uncertainty like this:

void UMyLoader::OnLoaded()
{
// Assume the callback may arrive off the game thread: only hand off thread-safely
AsyncTask(ENamedThreads::GameThread, [WeakThis = TWeakObjectPtr<UMyLoader>(this)]()
{
if (WeakThis.IsValid())
{
WeakThis->ApplyLoadedAssets();
}
});
}

There are three reasons:

  1. Reflected access on UObject, GC-related work and most engine subsystems require the game thread.
  2. A race exists between load completion and object destruction; a weak reference lets you re-check liveness after the hand-off.
  3. Concentrating "which thread owns this" in one place is far easier to audit than assuming it separately in every callback.

Lifetime risks​

The most common async failure is not a failed load — it is the callback arriving after the target is gone. Typical combinations: a level transition calls CancelHandle() while business code still holds a raw pointer to a destroyed object; or the handle itself is released, the completion notification is dropped, and the waiting state never ends.

Countermeasures:

  • Make ownership explicit with TWeakObjectPtr / TSharedPtr; never capture a raw this in a callback.
  • Cancel and null the handle in one place — BeginDestroy or an explicit Cancel().
  • Model "loading" as a queryable state instead of relying on the callback always arriving.

Relationship to the cache layer​

A completed load only brings the asset into memory; it does not mean references stay held. Unbounded caches such as SkeletalMeshCache / StaticMeshCache that only grow will keep pushing resident memory up in long-running sessions; that analysis belongs to the cache series under the memory management group. This page only fixes the thread boundary of the load callback, which that analysis depends on.