A few years into Kotlin and Coroutines -- starting in backend/server now also in android -- I still struggle with a fundamental design problem - how to 'cross the coroutine divide' ... Its a simple and complex problem : Given: one shouldn't make all functions suspend - therefore you will have a mix of suspend and non-suspend functions calling *each other * Given: <in my current domians> -- the 'majority/main' application is not 'coroutine based' -- its "traditional". Coroutines are added as needed, but the scale of existing code (custom and 3rd party, java/JVM and kotlin) is such that its not practical (yet) to have a coherant coroutine architecture and convention everything follows: Given: one should 'Avoid GlobalScope' -- and given its not trivial to create app coroutine scopes such that they are all self-contained -- real world code is not that pretty. Given: It is not obvious or easy to to tell if a non-suspend function was called by a suspend function, or is 'running in a coroutine' without passing down a CoroutineScope or context to every function (see 2.) Given: 'traditional' non-coroutine aware functions expect functions to only return when complete -- quite often you have to (and should) scope coroutine calls so they are blocking from the perspective of the parent non-coroutine-aware caller. This all leads to the need to have a good convention to follow for: How to create blocking scopes from within non-coroutine-aware functions. (without GlobalScope?) How to know if a non-suspend function is in fact in the call-chain of a suspend function or coroutine, so for example, you could call a suspend function without having to launch a new coroutine -- in what scope ? ( presuming the the caller is non-coroutine-aware it will not generally pass in a coroutine scope for you to use --) A few examples: Android: in onCreate() {} I need to call a suspend function (maybe it pre-existed as a suspend even if I dont need suspension for this call, 'suspend' is in it signature) -- But -- I should not return from onCreate until all its work is done. How ? <what scope>?.<what builder> { call suspend function } return // Do NOT return until above is complete If I have a scope (like lifecycleScope) life is easier -- Much, but if not, Then I have to make or borrow one, and then arrange somehow so its scope/lifecycle is well behaved. Could use GlobalScope. shouldnt probably but maybe 'this time' ? What builder? both launch and async -- are async so I have to wait for them. I cant do that outside the scope (the return statement) -- so where? Punt to yet another scope (as seen in sample code) val job = <scope>.launch { .. } <????> { job.join() } // This solves nothing -- Now I need to know how to wait for ??? Is 'runBlocking' the answer ? Its 'to be avoided' -- but precisely under which conditions? ------ Server side: A web request is processed and calls some "doGET" method -- from legacy java code expecting blocking behaviour. fun doGET() { // same question .. what scope ? launch/async ? runBlocking? } ----- The BIGGER problem In comes 'typical mature application' of some thousands of functions written over a decade by different people long gone .. Kotlin/Coroutines was introduced by some a while ago, haphazardly, Now we have a mess because its not at all clear which non-suspend functions are called by suspend functions upstream top() { module() library(callback) callback() --->| back to module onCallback() -> library() subsystem() -> Fancy Coroutine Stuff over blocking IO --> callback() // Developer comment about #@#%% old code and so on -- at any given point maybe a suspend fun maybe not, with no easy/quick way of telling if it was or could be called* by a coroutine or suspend func, or downstream, is there some 5 level deep suspend func calling back into the module without its context to hang on to ? Can one block the thread ? what other choice is there ? I end up having to solve these one by one ad-hoc with no real global architecture or understanding of what could go wrong. e.g. how bad is this in a library function: fun someFunHasToCallASuspendFun() { GlobalScope.runBlocking{ aQuickSuspendFunc() } } To avoid that Ive had to make massive invasive changes to pass in the appropriate scope from 5 levels up and then that can have a huge blast radius (let alone the ire of my teammates for such a huge change for a 'simple fix') Alternatively .. I've added a few 'suspend' modifiers to the fun and its parents etc. But the effect is very much like C++ "const rot" Once you add one suspend, then its parent has to be suspend, then everything that calls it has to also, then their parents -- it can and does explode quickly until often ALL methods have to be suspend just to call 1 10 levels deep. Another idiom: try to establish some well named 'global scopes' that are not 'GlobalScope' -- at some point this just seems silly -- inventing all these scopes just to avoid 1 -- when they do nothing different. It also requires opening up all libraries and modules to more dependencies, to the point sometimes of having to combine libraries just to share a common scope. The closest 'to ideal' I have found is Android Only, and UI Thread Only, <scope>.launch( Dispatchers.Main.immediate ){} If Im really careful I don't have to wait for this -- it inherently blocks the caller -- with some care even child coroutines are managed. But it seems so wrong that this is subtle and complicated -- surely this is the key difficulty in integrating coroutines -- yet most of the docs are written in a way that presumes everything is already coroutine aware - leaving the 'corner cases' as minor issues someone else can work out. Any commentary welcome - am I missing something big here ? Surely theres a good strategy to manage this problem

Hi David, I am far too less experience in giving answers to your questions, but I found your post interesting. One thing that that keeps occurring in the post is how to know non suspending functions are called in coroutine scoped function. Shouldn’t IDEs like IntelliJ help you with that ? Or did you mean at runtime ? (Which is even curious case) Nonetheless, my understanding is, marking a function suspend doesn’t make it async. It gives this function capabilities to achieve async and parallel behaviour. Let’s say you have the top function main which is not marked as suspend. On an app running on jvm, main function will run on main thread. And all the function inside it will also run on same thread unless mentioned otherwise. Now you can call your suspend function by wrapping it in runBlocking scope without “GlobalScope”. If you haven’t at any other place in the call chain, mentioned any different coroutine context, everything will run on main thread.

if you must block non-suspending code from returning, your only choice is

runBlocking

or equivalent

You also mention which scope to use and where. First of all, you don’t need to pass the scope down at all. That the beauty of this framework, that the child coroutine is aware of parents coroutine context and runs in the same unless stated otherwise. So unless you have changed the coroutine context somewhere down the call chain, all the coroutines should run in the same context. So let’s say your parent function is running on Dispatchers.IO, all the functions called by parent will run in Dispatchers.IO If you change context somewhere down the call, that will run in the given context but eventually return to its parent’s context.

I would split this answer into two parts: • on Android, where you do have things you need to dispatch to the main UI thread, you simply must make everything coroutine-aware. yes, this means you can't make wait for suspending calls from framework methods like

onCreate

, and that may require restructuring your app so that you can start the work but finish it later. but the alternative is painful debugging when you do end up deadlocking. • on the server side, most existing frameworks are thread-per-request. in that case

runBlocking

to adapt between the suspending and non-suspending worlds is safer. your suspend funs should

withContext

to move themselves into an appropriate dispatcher (e.g.

<http://Dispatchers.IO|Dispatchers.IO>

or

Dispatchers.Default

) instead of pushing that knowledge into the caller.

If you have a function that suspends and appears to block for the caller, use

coroutineScope

+1 to what @ephemient said above.

runBlocking {}

is something that should appear at very coarse-grained boundaries and very infrequently. Usually these are entry points, like

fun main() = runBlocking { ... }

or

@Test
fun myCodeBehavesAsExpected() = runBlocking {
  // test code
}

and yes, sometimes you might have exactly one

runBlocking

right at the beginning of handling a request for a thread-per-request server framework.

Appreciate the response ! Thanks! (but ...) I dont understand most of them as they simply 'do not work' -- or as I understand them. Example:

If you have non-coroutines code that blocks the calling thread on external IO, you can wrap them in suspend using withContext(Dispatchers.IO) to dedicate a temporary thread to the blocking call.

Um, no, that does not work. withContext() can NOT be called from "non-coroutine code" Please prove Im wrong, that would make my day x 10000 fun nonCoroutineCode() { withContext( Dispatcher.IO ) { ---- DOES NOT COMPILE } } And that is the crux of the problem -- all these great methods only work if your within a suspend fun

Another example:

That the beauty of this framework, that the child coroutine is aware of parents coroutine context and runs in the same unless stated otherwise.

So unless you have changed the coroutine context somewhere down the call chain, all the coroutines should run in the same context.

Um, no. fun coroutineCode() { scope.launch { fun1() } } ---- some other module fun fun1() { fun2() } fun fun2() { launch { } // DOES NOT COMPILE (or any other builder ) - } If you leave the lexical scope of an in scope CoroutineScope or you are in a a non-suspend fun - your out of luck -- no coroutines for you unless you aquire a scope somehere (which is not hard -- but -- I''d LIKE it to be the CALLERS scope -- but it cant be withoujt passing it down becuase its not a suspend fun so no 'scope is in scope' ---------- This answer is the only one that I belive is correct:

if you must block non-suspending code from returning, your only choice is 

runBlocking

 or equivalent

this is the sort of thing you have to had thought of before too, though? if you were using Rx or Loaders for async, blocking in onCreate is still a no-go, even if the compiler wasn't preventing you from doing so

It sounds like the missing piece for your setup here is that when you're working with suspend, you generally jump into suspending code early at something resembling an entry point and stay there to manage things that need to happen over time. To use the onCreate example, launch into your lifecycleScope, then manage sequence and contract in suspend-land. For example,

override fun onCreate(savedInstanceState: Bundle?) {
  super.onCreate(savedInstanceState)
  lifecycleScope.launch {
    performSuspendingInit()
    doThingsThatRequireSuspendingInitToBeComplete()
  }
}

If you are in a suspend function and you need to launch something, use

coroutineScope {}

instead of going hunting for another external scope to launch into:

suspend fun myFunction() {
  coroutineScope {
    launch { doThingOne() }
    launch { doThingTwo() }
  }
}

structured concurrency means async behavior is always opt-in; launching into your caller's scope is an antipattern because it "leaks" running operations into your caller. By writing it as the above, the caller can wrap it in their own

launch {}

call if they want it to happen concurrently with something else they're doing, and they can use exactly the same

coroutineScope {}

pattern to get a scope.

Very good suggestions, thanks. As motioned this isn't unique to coroutines, the problem ( for me ) tends to come up most when augmenting existing code that was not (or poorly) 'coroutine aware' "Crossing the boundry" between coroutines and non-coroutines may really just be another face of 'Crossing the boundary' between 2 entirely different architectural patterns. So in a real sense (and I believe intentional) the specific 'rules' of kotlin coroutines have been designed and tuned over time to make it hard to screw up -- by making it a compile time error for the most part to 'cross the boundary' easily. It may be a fundamental design anti-pattern to mix these 2 styles other then 'from the edges' where the behaviour is well defined. This gets massively harder when you 'swerve over the lines' vs 'cross'. e.g. This pattern is very hard to get right. Imagine these functions in different compilation units ( so they do NOT share the same 'scope' in any meaning) Also imagine they were written at different times by different people.

main() {

normalFunction()

}

fun normalFunction() {

someScope.launch {

callSuspend()

}

callNonSuspend()

}

suspend fun callSuspend() {

callNonSuspend()

}

----------------------------->>> >HERE

fun callNonSuspend() {

// Imagine Today I want to ADD a call some to suspend fun --

whatToDoToCallSuspend()

}

------------ Certainly there are many was to do this -- but the problem isnt so much how, but what. It makes a difference if 'callNonSuspend' was called 'from a coroutine' or not. Things like exception handling - should they be propagated to the caller scope or not, if a coroutine is launched but not waited for, who is going to manage it , whether its 'OK to Block Thread' -- which can lead to deadlock not just inefficiency. These are not fundamentally different then other architectural questions - but they add a whole new dimension to 'WTF' -- If your adding coroutines to an existing program then its unlikely the previous authors thought about coroutines at all, or in the same way. The variety and effect of interaction between otherwise unrelated code is substantial when you add coroutines. However one other factor makes this more specific to both kotlin and coroutines. The heavy use of Scope* conventions. By this I mean the kind of "DSL Scope" that coroutine builders use, similar to the more idiomatic scope functions (let, with, use, apply etc). These leverage the compiler in ways that are profoundly powerful -- but *only work when the entire call chain is in scope e.g This works MyScope.launch { async { coroutineScope { launch { async { ... } } } } All very nicely and cleanly hide the implicit scope so they 'just work" But when the same exact code gets distributed across files and modules -- it falls apart dramatically. There is no implicit scope, or its the wrong one. What was enforce/supplied by the compiler is gone. You have to explicitly recreate the implicit scope and carry it through everything. No different then other kotlin scope usage -- yet fundamentally different in that the current version of coroutine APIs require it -- you end up having to explicitly implement the receivers to every level of function call just to use it 1 time 10 levels deeper. All the hard work of the library authors vanishes the moment you leave the lexical scope. Building the scaffolding back up is not trivial. An approach I have not yet tried but may -- is using the newly supported ThreadLocal coroutine context. This could help a LOT -- but I havent fully walked through all the details. https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/-thread-context-element/index.html https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/as-context-element.html Basic concept

fun CoroutineScope.topLevel() {

put "this" into a thread local

fun2()

}

....

fun fun100() {

Look for scope or context from thread local

with( myThreadLocalScope ) {

Yea Life is restored

}

}

step in the wrong direction. you do not want to be passing the scope around like that, which enables callees to break out of structured concurrency.

Yes I get that - and have been bit. BUT -- what else is there that can be done if suspend F1() calls non-suspend F2() ... F10() What options do you have to run a coroutine in F10() ? ( assuming F10 is not in the same compilation unit or inline or otherwise not have direct acess tot he scoping functions) A). F10 can call runBlocking() -- Uses the thread global scope B). F10 can have its own created-on-the-fly scope C). F10 can use the scope of its caller (F1) passed to it somehow what else is there ? All of them suffer from 'break out of structured concurrency' *except C which atleast F10 would share the same structured scope as F1 and thus the same cancelable lifecycle. What is the 'right direction' if these are 'the wrong one' -- > that is my still-unanswered puzzle. Easy to say 'dont do that' not so easy to say ' do THIS instead'

don't make both F1() and F10() suspend until you've converted the interior calls - either start from the top and work your way down the call tree, or maybe vice versa

At the end - the requirement is that all function calls between any 2 calls using coroutines must be suspend calls OR pass the scope or context The std lib has pleanty of cases (and docs that suggest it) that passing CoroutineContext or CoroutineScope as either a receiver or a parameter is a reasonable alternative to using suspend (in some cases prefered). Given a complex app, where coroutines are being introduced and where it is not viable to rewrite all the paths between any 2 calls -- Using the coroutine supported version of thread local accomplishes the exact same thing as passing a context or coroutine scope as a parameter. suspendfun f( c: CoroutineScope ) { put c in coroutine impl of thread local f1() } fun f1() { f2() } ..... fun f10(){ val scope : CoroutineScope = get from thread local scope.launch { This uses the same context safely as f() } }