Coroutines support

[czyzby]

• Add ktx-async module.
• Implement coroutine context for LibGDX applications that executes tasks on the main rendering thread, using Gdx.app.postRunnable to resume coroutines executed on other threads.
• Implement utility functions for asynchronous tasks based on coroutines executed on a configurable AsyncExecutor instance.
• Add HttpRequest utilities based on coroutines.
• Simplify LibGDX Timer API. Currently it does not support lambdas.
• Add suspending delay method, which does not block the main rendering thread using LibGDX Timer.
• skipFrame suspending method that resumes on the next frame using Gdx.app.postRunnable API.
• Implement tasks cancellation.
• Documentation with usage examples.

---

Implement ktx-async module with asynchronous operations utilities and Kotlin 1.1 coroutines support.

[czyzby]

@kotcrab Sweet. LibGDX HttpResponse implementation is not thread-safe and does not care if the underlying connection was closed, silently ignoring all exceptions. Here I was, wondering why my implementation of asynchronous HTTP requests always returns empty content - I debugged LibGDX code and now I'm surprised it even works in the first place.

[czyzby]

@sreich @kotcrab How should I call the most commonly used method that gives you access to KTX coroutines context and allows to execute code on the main rendering thread? onMainThread, execute?

[kotcrab]

No idea. execute is too vague in my opinion. onMainThread or onGdxThread is ok-ish. I probably like most postRunnable, same as Gdx.app.postRunnable. Maybe just post but that seems vague if it's a global method.

[czyzby]

postRunnable might be misleading, as coroutine can be executed on the same thread right after you start it, and it can create more than a single task objects under the hood. onMainThread isn't ideal either, as your coroutine might never do anything significant on the main thread. Maybe something more explicit like gdxCoroutine or ktxCoroutine?

The official method for creating coroutines with a context is launch. Our method would basically be a convenience wrapper over launch(KtxAsync). Any particular names with launch sound good?

[kotcrab]

I see. Nothing really strikes my mind though. I guess something like ktxAsync is not ideal either?

[czyzby]

Not ideal, but simple and obvious. Not only does it match the module name, but also does not suggest where the code is executed (onMainThread) - only that it can be executed asynchronously. It's so trivial to add such method or simply use KtxAsync context directly with launch, that I don't think ktxAsync method will be harmful.

[yhslai]

I personally +1 for onMainThread because when one use this kind of behavior he has to be aware of which thread the tasks will be executed.

Or onNextFrame, maybe? "Frame" sort of implies the thread that can render frames, a.k.a. main thread. Just my 2 cents.

[czyzby]

But that's the thing: it does not have to be executed on the main thread. If you're using coroutines in the first place, chances are half of the instructions will be executed elsewhere. Only the processing of async operations results and non-suspending methods are invoked on the rendering thread. It might give you a false impressions that time consuming methods will block your rendering.

onMainThread {
  val httpResponse = httpRequest(url = "example.com", method = "GET") // Net executor.
  delay(1) // Timer.
  val result = asynchronous { someTask() } // Context's AsyncExecutor. 
}

[sreich]

Only the processing of async operations results and non-suspending methods are invoked on the rendering thread

I don't think you meant to say "non suspending methods". Suspending methods can be on any thread including the render thread and it can be useful to use them on the rendering thread to mask state.

Or am I misunderstanding here?

[czyzby]

That's right, I oversimplified. I should have said non-suspending methods and suspending methods that can be executed on the main thread. KtxAsync context always tries to execute everything on the main rendering thread, besides the obvious cases where the actual work is delegated to other threads.

[czyzby]

@kotcrab @sreich @raincole @MrPlow442 Can you take a look at the new module implementation and API? #57 I want your approval before merging and releasing this.

[yhslai]

I'm heading for ludum dare this weekend. If no one else does I can help review it next week.

[czyzby]

It's OK. Good luck. ; )

[czyzby]

@kotcrab Thanks for the #57 code review. There's already a lot of changes since the last version, so I'm going to release 1.9.6-b2 now and move KTX to the new repository. Coroutines-based asset loader is postponed to the next release.