Resource-scoped coroutine scope helpers

[tKe]

I'm not entirely certain if there's some hidden nuance on these, but the intent is to provide "unwrapped" coroutine scopes bound to the resourceScope lifecycle that could then be passed/composed into other resources.

[kyay10]

Beautiful! I believe Simon had something similar in mind in #3443.

[serras]

What is the use case of those functions? I'm a bit worried about making the API too big.

[tKe]

I suppose the only real use-case is if you had a CompletableJob from elsewhere you wanted to complete in an onRelease block or such.

It probably makes sense to make it private for now. I left it public as it felt useful for composition, but I can't see many reasons to create a completable job that aren't already covered by the scopes in this PR.

I did consider additionally adding something like

public fun ResourceScope.cancelAndJoinOnRelease(job: Job) {
  onRelease { exitCase ->
    when(exitCase) {
      is ExitCase.Cancelled -> job.cancel(exitCase.exception)
      is ExitCase.Failure -> job.cancel("Resource scope failure", exitCase.failure)
      ExitCase.Completed -> job.cancel()
    }
    job.join()
  }
}

which would cover tying any job lifecycle (for example, kafka/channel consumer, flow producer) into the resource scope, which I've used as a pattern in a number of services. It's simple to do as a local extension in each service but seems like something that might be available out of the box for resource management.

I'll mark the completeWith functions as private for now, and if viable raise another PR for the cancelAndJoinOnRelease function for discussion.

[tKe]

@kyay10 do you see any value in keeping the completeWith and completeWithAndJoin helpers public?

[serras]

This is more of a style thing, but may you (literally) inline this function into its (single) usage below. I think that it would made for a simpler codebase.

[tKe]

Sure - I split it to mirror Job's cancel and cancelWithJoin but as it's not exposed now there's no benefit.

[serras]

Suggested change

	onRelease { job.completeWithAndJoin(it) }
	onRelease { exitCase ->
	job.completeWith(exitCase)
	job.join()
	}

[serras]

The coroutineScope and supervisorScope functions use continuation style. It think we should follow the same pattern, or change their names, to avoid surprises.

[serras]

My suggestion is to use something like managedCoroutineScope, acquireCoroutineScope, or something along those lines.

[tKe]

I think I was relying on the difference between passing a lambda or not. I also questioned whether they should inherit the currentCoroutineContext() by default as coroutineScope{} does but decided these are analogous of the CoroutineScope() "constructor" and should therefore imply no default context (you can always use coroutineScope(coroutineContext) as needed).

Maybe managed prefix makes sense though as it's otherwise not as easy to distinguish either by lack of lambda or lack of capitalisation alone.

[kyay10]

Just a suggestion. I'm worried this breaks structured concurrency because it doesn't automatically inherit the current coroutine scope. Maybe a contextual version of it could be nice to have? As in, it takes in CoroutineScope as a context, and uses it as the basis for its context, with extras passed in as the argument. This is analogous to coroutineScope and supervisorScope, but maybe there's something I'm missing here

[tKe]

I intended this to be analogous to the CoroutineScope "constructor" which doesn't automatically inherit context, but with its lifecycle coupled to the containing resource scope.

Given the nature of resource scope, structured concurrency should be maintained even without the job inheritance.

One could always passcurrentCoroutineContext() if truly desired.

[serras]

I misunderstood the use case here then. I would suggest to emphasize the "constructorness" by naming it ManagedCoroutineScope instead. Given the potential for confusion, I also suggest to add an OptIn annotation, and describe in the documentation the expected use case.