Rewrite AssetStorage to the new ktx-async API

[czyzby]

• Add ktx-assets-async module.
• AssetStorage rewrite.
• Usage documentation.
• Restore ktx-freetype-async, update to new API.
• Restore TextAssetLoader, move to ktx-assets.

---

AssetStorage was removed during the ktx-async overhaul in 1.9.9-b1 due to reliance on old coroutines API and threading issues. The goal of this task is to rewrite AssetStorage in a fully thread-safe way, without reliance on specific coroutines dispatchers for asynchronous tasks.

[amitkot]

I'm making changes to a project I created two years ago in which I used the previous version of ktx-async which depended on the experimental coroutines, and specifically AssetStorage.

I see that AssetStorage is no longer available in KTX.

Would you say the wise move right now is to switch to using ktx-assets's AssetManager instead of AssetStorage?

[czyzby]

@amitkot For now, yes. There were some issues with thread safety and unstable coroutines API usage, and I'm afraid AssetStorage needs a complete rewrite. Sorry.

[czyzby]

@Quillraven @cypherdare @Jkly @maltaisn @jcornaz @amitkot

I finally decided to rewrite the good old AssetStorage. While I still have to write usage examples and update ktx-freetype-async, at this point I'm happy with the AssetStorage implementation and its test suite.

To be honest, this is probably among top 5 most fun, challenging and complex pieces of code I've written. The initial implementation would definitely not pass the extensive tests I've written this time, including concurrent assets loading and unloading on multiple threads and coroutines.

I think the current implementation is fully thread-safe and non-blocking. Unless the user of the API blocks the rendering or loading threads manually with runBlocking and whatnot, it should handle anything you throw at it without deadlocks or unexpected exceptions. I've run hundreds of thousands of concurrent loading and unloading requests of assets with nested dependencies - I encourage you to play with should handle stress test test in storageTest.kt to try to break it.

Anyway, I would appreciate it very much if you took the time to try AssetStorage out as a replacement for AssetManager or even go through the sources and do some code review. I know it's a huge pull request, but even superficial review would help a lot. If you're interested and have some time:

• ktx-assets-async - KTX module.
• Asynchronous coroutines-based asset manager: AssetStorage #258 - pull request.
• ktx-assets-async version 1.9.10-SNAPSHOT should be available in the snapshots repository.

I'll leave the pull request open awaiting suggestions while I focus on the documentation and ktx-freetype-async.

Thanks.

[czyzby]

ktx-freetype-async is now updated to the new AssetStorage API and available via snapshot releases.

[czyzby]

Ironically, after implementing this I found this obscure feature called LoadedCallback in AssetLoaderParameters, where you can actually add a callback that will be invoked after the asset is loaded by a AssetManager, which means coroutines support can be added to the original LibGDX manager relatively easy (well, easier than writing AssetStorage was).

AssetStorage still makes sense, of course, as it allows for true parallel asset loading, but I'm thinking we could also add coroutines support to AssetManager. loadAsync extension could return a Deferred reference to an asset that you can await for.

---

Edit: other than having to make the parameters nullable and create them dynamically for supported asset types, this would be as easy as:

import com.badlogic.gdx.assets.AssetLoaderParameters
import com.badlogic.gdx.assets.AssetLoaderParameters.LoadedCallback
import com.badlogic.gdx.assets.AssetManager
import kotlinx.coroutines.CompletableDeferred
import kotlinx.coroutines.Deferred

inline fun <reified T> AssetManager.loadAsync(
  path: String, parameters: AssetLoaderParameters<T>
): Deferred<T> {
  val result = CompletableDeferred<T>()
  parameters.loadedCallback = LoadedCallback { assetManager, fileName, type ->
    @Suppress("UNCHECKED_CAST") val assetClass = type as Class<T>
    try {
      result.complete(assetManager.get(fileName, assetClass) as T)
    } catch (exception: Throwable) {
      result.completeExceptionally(exception)
    }
  }
  load(path, T::class.java, parameters)
  return result
}

Oh well.

[czyzby]

I believe the current AssetStorage available on develop is feature-complete and can be used as a replacement for AssetManager for the majority of use cases. @Quillraven also reported notable performance improvements, especially on mobile (see discussion in #258).

I want to thank @Quillraven again for testing and review of the new asset manager. I'd ship a lot less features and a clunky API if not for the input and feature requests.

Since there were no further comments, I'm closing this issue for now. If you'd like you make a feature request or comment regarding the AssetStorage API, use issue #259.

[cypherdare]

@czyzby I have been on a bit of LibGDX hiatus for the past three months. I looked this over briefly and it looks slick. I don't currently have a project in need of this feature to try it out in currently, though.