//workflow/com.squareup.workflow1/renderWorkflowIn

renderWorkflowIn

[jvm]
Content
fun <PropsT, OutputT, RenderingT> renderWorkflowIn(workflow: Workflow<PropsT, OutputT, RenderingT>, scope: CoroutineScope, props: StateFlow<PropsT>, initialSnapshot: TreeSnapshot? = null, interceptors: List<WorkflowInterceptor> = emptyList(), onOutput: suspend (OutputT) -> Unit): StateFlow<RenderingAndSnapshot<RenderingT>>
More info

Launches the workflow in a new coroutine in scope and returns a StateFlow of its renderings and snapshots. The workflow tree is seeded with initialSnapshot and the current value value of props. Subsequent values emitted from props will be used to re-render the workflow.

This is the primary low-level entry point into the workflow runtime. If you are writing an app, you should probably be using a higher-level entry point that will also let you define UI bindings for your renderings.

Initialization

When this function is called, the workflow runtime is started immediately, before the function even returns. The current value of the props is used to perform the initial render pass. The result of this render pass is used to initialize the StateFlow of renderings and snapshots that is returned.

Once the initial render pass is complete, the workflow runtime will continue executing in a new coroutine launched in scope.

Scoping

The workflow runtime makes use of structured concurrency.

The runtime is started in scope, which defines the context for the entire workflow tree – most importantly, the Job that governs the runtime’s lifetime and exception reporting path, and the CoroutineDispatcher that decides on what thread(s) to run workflow code. Note that if the scope’s dispatcher executes on threads different than the caller, then the initial render pass will occur on the current thread but all subsequent render passes, and actions, will be executed on that dispatcher. This shouldn’t affect well-written workflows, since the render method should not perform side effects anyway.

All workers that are run by this runtime will be collected in coroutines that are children of scope. When the root workflow emits an output, onOutput will be invoked in a child of scope.

To stop the workflow runtime, simply cancel scope. Any running workers will be cancelled, and if onOutput is currently running it will be cancelled as well.

Error handling

If the initial render pass throws an exception, that exception will be thrown from this function. Any exceptions thrown from the runtime (and any workflows or workers) after that will bubble up and be handled by scope (usually by cancelling it).

Since the onOutput function is executed in scope, any exceptions it throws will also bubble up to scope. Any exceptions thrown by subscribers of the returned StateFlow will not cancel scope or cancel the runtime, but will be handled in the CoroutineScope of the subscriber.

Return

A StateFlow of RenderingAndSnapshots that will emit any time the root workflow creates a new rendering.

Parameters

jvm

workflow	The root workflow to render.
scope	The CoroutineScope in which to launch the workflow runtime. Any exceptions thrown in any workflows, after the initial render pass, will be handled by this scope, and cancelling this scope will cancel the workflow runtime and any running workers. Note that any dispatcher in this scope will not be used to execute the very first render pass.
props	Specifies the initial PropsT to use to render the root workflow, and will cause a re-render when new props are emitted. If this flow completes after emitting at least one value, the runtime will not fail or stop, it will continue running with the last-emitted input. To only pass a single props value, simply create a MutableStateFlow with the value.
initialSnapshot	If not null or empty, used to restore the workflow. Should be obtained from a previous runtime’s RenderingAndSnapshot.
interceptors	An optional list of WorkflowInterceptors that will wrap every workflow rendered by the runtime. Interceptors will be invoked in 0-to-length order: the interceptor at index 0 will process the workflow first, then the interceptor at index 1, etc.
onOutput	A function that will be called whenever the root workflow emits an OutputT. This is a suspend function, and is invoked synchronously within the runtime: if it suspends, the workflow runtime will effectively be paused until it returns. This means that it will propagate backpressure if used to forward outputs to a Flow or Channel, for example.