Structure of Coroutine Framwork
coroutine framwork consist of two parts
- Basic Coroutine Library, which is naturally integrated in kotlin language
- Coroutine Application Framwork, which is organized to simplify advanced usage of coroutines
- The first part is really simple, while the next part is larger, and offered by
kotlinx-coroutines-corelibrary
in this chapter, we will talk about the first part, that is, how coroutines really work at underlying level
Nature of Coroutine
coroutine is a code scope that has ability to suspend and resume execution
if a function has a suspend modifier, it is running in coroutine scope, can share the ability of coroutine
in fact, suspend function implictly invole an object with Continuation class, that is how it interact with coroutines
Coroutine States
- NotDecided, created by not suspended
- Suspended, suspend temporally
- Resumed, resume from suspended state, may be running or completed
Composition of Basic Coroutine Library
these classed are important for understanding what coroutines really do
- CoroutineSingletons : coroutine state enumerations
- Result : save suspend function result and error, also can used to save coroutine states
- Continuation : have many functional roles, depend on concrete subclass, start coroutine, coroutine body, coroutine callback
let us take a first look at basic coroutine code frist, then step deeply into Continuation subclassed
Basic Coroutines Usage
fun main() {
val completeContinuation = object : Continuation<Int> {
override val context = EmptyCoroutineContext
override fun resumeWith(result: Result<Int>) {
println(result.getOrThrow()) // ④
}
}
val safeContinuation = suspend {
100 // ③
}.createCoroutine(completeContinuation) // ①
safeContinuation.resume(Unit) // ②
}
suspend fun main() {
val result = suspendCoroutine { continuation ->
continuation.resume(100) // ②
} // ①
println(result) // ③
}
demo 1 show how to create and start a coroutine
demo 2 show how to suspend and resume current coroutine
Continuation Subclasses
- BaseContinuationImpl : abstract class, implement ability of resume
- SuspendLambda : coroutine body, do actual work
- SafeContinuation : check coroutine state, if suspended resume it by delegate, else save result and return
- CompletedContinuation : handle coroutine result callback
- RunSuspend : start a coroutine using main function as coroutine body (suspend block)
resumeWith(result) has various effect in different implementations
- SafeContinuation : start coroutine
- SuspendLambda : execute coroutine body
- CompletedContinuation : handle coroutine callback
Analysis of Demo 1
fun main() {
val completeContinuation = object : Continuation<Int> {
override val context = EmptyCoroutineContext
override fun resumeWith(result: Result<Int>) {
println(result.getOrThrow()) // ④
}
}
val safeContinuation = suspend {
100 // ③
}.createCoroutine(completeContinuation) // ①
safeContinuation.resume(Unit) // ②
}
-
① create coroutine from suspend block, and enter suspended state, then return a SafeContinuation instance
-
② start coroutine, as SafeContinuation do not handle actual work, param is void
-
suspend block will be compiled to a SuspendLambda instance
-
SafeContinuation use SuspendLambda as a delegate object, deliver actual work to SuspendLambda
-
③ SuspendLambda execute block code by
invokeSuspend, and get execution result -
④ SuspendLambda deliver result to CompletedContinuation (completion)
-
if completion is not CompletedContinuation, regard completion as a delegate continuation, and repeat wroks above
-
then a new cycle of circulation begins, forms a hierachical coroutine system
How Does Continuation Resume from Suspended State
let us see BaseContinuationImpl#resumeWith
this is the quintessence of how coroutine works, shuttling between suspended and resumed states
public final override fun resumeWith(result: Result<Any?>) {
var current = this
var param = result
while (true) {
with(current) {
val outcome: Result<Any?> = try {
val outcome = invokeSuspend(param)
if (outcome === COROUTINE_SUSPENDED) return
Result.success(outcome)
} catch (exception: Throwable) {
Result.failure(exception)
}
val completion = completion!!
if (completion is BaseContinuationImpl) {
current = completion
param = outcome
} else {
completion.resumeWith(outcome)
return
}
}
}
}
we can get these conclusions from above
- child coroutine can resume parent coroutine, through looped assignment of
current - when completion is instance of
BaseContinuationImpl, means it is not only a callback, but also the parent coroutine which launch it - result of
invokeSuspendcan be used as input param for parent coroutine - if current coroutine suspend again during
invokeSuspend, function returned, wait next calling ofresumeWith
What Does SafeContinuation Do
public actual override fun resumeWith(result: Result<T>) {
while (true) {
val current = this.result
when {
current === UNDECIDED ->
if (RESULT.compareAndSet(this, UNDECIDED, result.value)) return
current === COROUTINE_SUSPENDED ->
if (RESULT.compareAndSet(this, COROUTINE_SUSPENDED, RESUMED)) {
delegate.resumeWith(result)
return
}
else ->
throw IllegalStateException("Already Resumed")
}
}
}
- if coroutine is not suspended, directly set result
- if coroutine is suspended, resume it through delegate
- if coroutine is resumed, throw error
What Does CompletedContinuation Do
override fun resumeWith(result: Result<Any?>) {
error("This continuation is already complete")
}
do nothing and throw error by default
we must override it by ourself, it is just a callback, not responsible for resume actually
What Does InvokeSuspend Do
try {
val outcome = invokeSuspend(param)
if (outcome === COROUTINE_SUSPENDED) return
Result.success(outcome)
} catch (exception: Throwable) {
Result.failure(exception)
}
invokeSuspend execute code from suspend block
if the block directly run out all lines, return block result
if the block suspended on half way, return coroutine state of COROUTINE_SUSPENDED
What Does CreateCoroutine Do
public fun <T> (suspend () -> T).createCoroutine(
completion: Continuation<T>
): Continuation<Unit> = SafeContinuation(createCoroutineUnintercepted(completion), COROUTINE_SUSPENDED)
create a coroutine, and set its initial state to supsended
two continuations are created here, SuspendLambda and SafeContinuation
their initial states are all COROUTINE_SUSPENDED
When to Suspend and Resume
there are two typical ways to suspend and resume a coroutine
-
Thread Scheduling :
suspend current code, start a thread to handle async work, resume at end of thread
-
Loop Queue :
suspend current code, submit a task to handle async work, resume at end of current task
suspend and resume may happen in same thread, if we use the Loop Queue way
Analysis of Demo 2
we are already clear that, how to start, how to resume, how to callback
but how to suspend during a current code chain, is still a mystery, let us continue
suspend fun main() {
val result = suspendCoroutine { continuation ->
continuation.resume(100) // ②
} // ①
println(result) // ③
}
suspend main can be regard as this
val mainBlock: suspend () -> Unit
val completion: Continuation
mainBlock.createCoroutine(completion).resume(Unit)
completion.await()
the compiler tricked us with a magic, suspend main is actually the suspend block that used to create coroutine
suspend main was running within a hidden method, which was the truly main
Nature of Suspend Main
implementation of suspend main can be found in RunSuspend.kt
internal fun runSuspend(block: suspend () -> Unit) {
val run = RunSuspend()
block.startCoroutine(run)
run.await()
}
private class RunSuspend : Continuation<Unit> {
var result: Result<Unit>? = null
override fun resumeWith(result: Result<Unit>) = synchronized(this) {
this.result = result
notifyAll()
}
fun await() = synchronized(this) {
while (true) {
when (val result = this.result) {
null -> wait()
else -> {
result.getOrThrow()
return
}
}
}
}
}
when this code is compiled to jvm bytecode, its running process can be like this
- JVM launch main function of main Class
- main function create a RunSuspend object, as coroutine completion callback
- main function use code in
suspend mainassuspend blockto create and start a coroutine - main function call completion.await, as result is null, it will wait for lock
- coroutine resumed, completion.resumeWith is called
- completion save result and call notifyAll
- lock is woken up, completion.await returns, program ends
What Does SuspendCoroutine Do
suspend fun main() {
val result = suspendCoroutine { continuation ->
continuation.resume(100) // ②
} // ①
println(result) // ③
}
① suspendCoroutine suspend current coroutine, and start a async code block
② a Continuation object is given to resume coroutine, when async work is finished
as suspendCoroutine is designed to suspend coroutine, it must run in coroutine scope first
③ as current coroutine is suspended, step 3 will be executed after step 2
if code in step 2 is removed, step 3 will never reached, as coroutine is suspened forever
Conclusions
- there is no class called Coroutine
- coroutine present a continuous code block that can suspend and resume
- suspend and resume abilities are implemented through Continuation class
- suspend keyword is not naturally supported by jvm bytecode
- suspend and resume code are converted into jvm bytecode through kotlin compiler
- suspend and resume location can be inferred by saving and restoring coroutine calling stack frame
Trailer
the most roles in kotlin coroutines are :
Continuation class suspend block createCoroutine suspendCoroutine resume function
other concepts and apis are all extended from these ones, they are application framworks, not basic facilities
next, we will talk about how to implement CoroutineStackFrame Suspend and Resume in other topics