AssetManager async dependency failure propagation and reference counting

Question

AssetManager provides load, get and update APIs for asynchronous asset loading with automatic dependency graph resolution in libGDX core. Reference counting is manual via references; AssetManager.dispose() decrements counts but does not auto-unload assets when count reaches zero, requiring explicit unload calls.

Behavior around failed loads and manual reference management is not fully specified. When a dependency asset fails to load, dependent assets remain in a failed state and the API contract for retry, reset or rollback of the load graph is unclear. The threading model requires update() to be called on the rendering thread while actual loading runs on background threads supplied by the application, with differences across desktop, Android and GWT backends. Behavior is version sensitive across libGDX releases.

The goal is to clarify documented state transitions and reference management for async loads with dependencies under version assumptions.

What state does AssetManager report for a dependent asset when its dependency fails to load, and is that state resettable without re-queueing? Does AssetManager automatically adjust reference counts for dependents on dependency failure, or must unload be performed manually for each asset? Is retry behavior defined after a failed load, and does it require an explicit load call or finishLoading invocation?

Tasadduq Burney · Answer

p>In libGDX, the AssetManager handles complex dependency graphs, but its behavior during partial failures is strict and manual. When a dependency fails to load, the system does not automatically roll back or clean up the graph.

State Transitions and Resets
When a dependency asset fails to load, the dependent asset transitions to a failed state. The AssetManager reports the dependent asset as failed (or keeps it in a loading/pending state depending on the specific version) because its requirements for completion were never met. 
This state is generally not resettable without re-queueing. To attempt a retry, you must:

Explicitly unload the failed dependency and the affected dependents.
  Call load() again for the required assets.
  Ensure update() is called to process the new requests.

Reference Counting Behavior
AssetManager does not automatically adjust reference counts for dependents upon dependency failure. Because reference counting is manual via load() and unload() calls, any count increment by the initial load request remains until manually decremented. You must perform an explicit unload for each asset that was queued to prevent memory leaks or stale references.

Retry and Invocation
Retry behavior is not defined as an automatic process within the AssetManager. If a load fails, the manager does not internally retry the operation. A "retry" requires:

An explicit load() call to re-queue the asset.
  Subsequent invocations of update() on the rendering thread to allow background threads to process the new load task.

Note: This analysis assumes a standard libGDX 1.10+ environment. Differences in internal state reporting may occur in GWT or Android-specific back-threading implementations.

AssetManager async dependency failure propagation and reference counting

1 answer

p>In libGDX, the `AssetManager` handles complex dependency graphs, but its behavior during partial failures is strict and manual. When a dependency fails to load, the system does not automatically roll back or clean up the graph.

State Transitions and Resets

Reference Counting Behavior

Retry and Invocation

Your perspective belongs here.

0 question comments