runningSideEffect

abstract fun runningSideEffect(key: String, sideEffect: suspend CoroutineScope.() -> Unit)(source)

Ensures sideEffect is running with the given key.

The first render pass in which this method is called, sideEffect will be launched in a new coroutine that will be scoped to the rendering Workflow. Subsequent render passes that invoke this method with the same key will not launch the coroutine again, but let it keep running. Note that if a different function is passed with the same key, the side effect will not be restarted, the new function will simply be ignored. The next render pass in which the workflow does not call this method with the same key, the coroutine running sideEffect will be cancelled.

The coroutine will run with the same CoroutineContext that the workflow runtime is running in. The side effect coroutine will not be started until after the first render call than runs it returns.

Note that there is currently an issue when a runningSideEffect (and thus also runningWorker, or the parent Workflow of either via renderChild) is declared as running (or rendering) in one render pass and then not declared in the next render pass and both those consecutive render passes happen synchronously - i.e. without the CoroutineDispatcher for the Workflow runtime being able to dispatch asynchronously. This is because the jobs for side effects are launched lazily in order to ensure they happen after the render pass, but if the CoroutineScope's job (the parent for all these jobs) is cancelled before these lazy coroutines have a chance to dispatch, then they will never run at all. For more details, and to report problems with this, see the issue. If you need guaranteed execution for some code in this scenario (like for cleanup), please use a SessionWorkflow and the SessionWorkflow.initialState that provides the CoroutineScope which is equivalent to the lifetime of the Workflow node in the tree. The Job can be extracted from that and used to get guaranteed to be executed lifecycle hooks, e.g. via Job.invokeOnCompletion.

Parameters

key

The string key that is used to distinguish between side effects.

sideEffect

The suspend function that will be launched in a coroutine to perform the side effect.