Add an Interceptor Method for the result of runtime loop tick (Skip, UpdateRendering)

Author: steve-the-edwards

workflow-runtime/api/workflow-runtime.api

@@ -4,6 +4,7 @@ public final class com/squareup/workflow1/NoopWorkflowInterceptor : com/squareup
 	public fun onPropsChanged (Ljava/lang/Object;Ljava/lang/Object;Ljava/lang/Object;Lkotlin/jvm/functions/Function3;Lcom/squareup/workflow1/WorkflowInterceptor$WorkflowSession;)Ljava/lang/Object;
 	public fun onRender (Ljava/lang/Object;Ljava/lang/Object;Lcom/squareup/workflow1/BaseRenderContext;Lkotlin/jvm/functions/Function3;Lcom/squareup/workflow1/WorkflowInterceptor$WorkflowSession;)Ljava/lang/Object;
 	public fun onRenderAndSnapshot (Ljava/lang/Object;Lkotlin/jvm/functions/Function1;Lcom/squareup/workflow1/WorkflowInterceptor$WorkflowSession;)Lcom/squareup/workflow1/RenderingAndSnapshot;
+	public fun onRuntimeLoopTick (Lcom/squareup/workflow1/WorkflowInterceptor$RuntimeLoopOutcome;)V
 	public fun onSessionStarted (Lkotlinx/coroutines/CoroutineScope;Lcom/squareup/workflow1/WorkflowInterceptor$WorkflowSession;)V
 	public fun onSnapshotState (Ljava/lang/Object;Lkotlin/jvm/functions/Function1;Lcom/squareup/workflow1/WorkflowInterceptor$WorkflowSession;)Lcom/squareup/workflow1/Snapshot;
 	public fun onSnapshotStateWithChildren (Lkotlin/jvm/functions/Function0;Lcom/squareup/workflow1/WorkflowInterceptor$WorkflowSession;)Lcom/squareup/workflow1/TreeSnapshot;
@@ -32,6 +33,7 @@ public class com/squareup/workflow1/SimpleLoggingWorkflowInterceptor : com/squar
 	public fun onPropsChanged (Ljava/lang/Object;Ljava/lang/Object;Ljava/lang/Object;Lkotlin/jvm/functions/Function3;Lcom/squareup/workflow1/WorkflowInterceptor$WorkflowSession;)Ljava/lang/Object;
 	public fun onRender (Ljava/lang/Object;Ljava/lang/Object;Lcom/squareup/workflow1/BaseRenderContext;Lkotlin/jvm/functions/Function3;Lcom/squareup/workflow1/WorkflowInterceptor$WorkflowSession;)Ljava/lang/Object;
 	public fun onRenderAndSnapshot (Ljava/lang/Object;Lkotlin/jvm/functions/Function1;Lcom/squareup/workflow1/WorkflowInterceptor$WorkflowSession;)Lcom/squareup/workflow1/RenderingAndSnapshot;
+	public fun onRuntimeLoopTick (Lcom/squareup/workflow1/WorkflowInterceptor$RuntimeLoopOutcome;)V
 	public fun onSessionStarted (Lkotlinx/coroutines/CoroutineScope;Lcom/squareup/workflow1/WorkflowInterceptor$WorkflowSession;)V
 	public fun onSnapshotState (Ljava/lang/Object;Lkotlin/jvm/functions/Function1;Lcom/squareup/workflow1/WorkflowInterceptor$WorkflowSession;)Lcom/squareup/workflow1/Snapshot;
 	public fun onSnapshotStateWithChildren (Lkotlin/jvm/functions/Function0;Lcom/squareup/workflow1/WorkflowInterceptor$WorkflowSession;)Lcom/squareup/workflow1/TreeSnapshot;
@@ -54,6 +56,7 @@ public abstract interface class com/squareup/workflow1/WorkflowInterceptor {
 	public abstract fun onPropsChanged (Ljava/lang/Object;Ljava/lang/Object;Ljava/lang/Object;Lkotlin/jvm/functions/Function3;Lcom/squareup/workflow1/WorkflowInterceptor$WorkflowSession;)Ljava/lang/Object;
 	public abstract fun onRender (Ljava/lang/Object;Ljava/lang/Object;Lcom/squareup/workflow1/BaseRenderContext;Lkotlin/jvm/functions/Function3;Lcom/squareup/workflow1/WorkflowInterceptor$WorkflowSession;)Ljava/lang/Object;
 	public abstract fun onRenderAndSnapshot (Ljava/lang/Object;Lkotlin/jvm/functions/Function1;Lcom/squareup/workflow1/WorkflowInterceptor$WorkflowSession;)Lcom/squareup/workflow1/RenderingAndSnapshot;
+	public abstract fun onRuntimeLoopTick (Lcom/squareup/workflow1/WorkflowInterceptor$RuntimeLoopOutcome;)V
 	public abstract fun onSessionStarted (Lkotlinx/coroutines/CoroutineScope;Lcom/squareup/workflow1/WorkflowInterceptor$WorkflowSession;)V
 	public abstract fun onSnapshotState (Ljava/lang/Object;Lkotlin/jvm/functions/Function1;Lcom/squareup/workflow1/WorkflowInterceptor$WorkflowSession;)Lcom/squareup/workflow1/Snapshot;
 	public abstract fun onSnapshotStateWithChildren (Lkotlin/jvm/functions/Function0;Lcom/squareup/workflow1/WorkflowInterceptor$WorkflowSession;)Lcom/squareup/workflow1/TreeSnapshot;
@@ -64,6 +67,7 @@ public final class com/squareup/workflow1/WorkflowInterceptor$DefaultImpls {
 	public static fun onPropsChanged (Lcom/squareup/workflow1/WorkflowInterceptor;Ljava/lang/Object;Ljava/lang/Object;Ljava/lang/Object;Lkotlin/jvm/functions/Function3;Lcom/squareup/workflow1/WorkflowInterceptor$WorkflowSession;)Ljava/lang/Object;
 	public static fun onRender (Lcom/squareup/workflow1/WorkflowInterceptor;Ljava/lang/Object;Ljava/lang/Object;Lcom/squareup/workflow1/BaseRenderContext;Lkotlin/jvm/functions/Function3;Lcom/squareup/workflow1/WorkflowInterceptor$WorkflowSession;)Ljava/lang/Object;
 	public static fun onRenderAndSnapshot (Lcom/squareup/workflow1/WorkflowInterceptor;Ljava/lang/Object;Lkotlin/jvm/functions/Function1;Lcom/squareup/workflow1/WorkflowInterceptor$WorkflowSession;)Lcom/squareup/workflow1/RenderingAndSnapshot;
+	public static fun onRuntimeLoopTick (Lcom/squareup/workflow1/WorkflowInterceptor;Lcom/squareup/workflow1/WorkflowInterceptor$RuntimeLoopOutcome;)V
 	public static fun onSessionStarted (Lcom/squareup/workflow1/WorkflowInterceptor;Lkotlinx/coroutines/CoroutineScope;Lcom/squareup/workflow1/WorkflowInterceptor$WorkflowSession;)V
 	public static fun onSnapshotState (Lcom/squareup/workflow1/WorkflowInterceptor;Ljava/lang/Object;Lkotlin/jvm/functions/Function1;Lcom/squareup/workflow1/WorkflowInterceptor$WorkflowSession;)Lcom/squareup/workflow1/Snapshot;
 	public static fun onSnapshotStateWithChildren (Lcom/squareup/workflow1/WorkflowInterceptor;Lkotlin/jvm/functions/Function0;Lcom/squareup/workflow1/WorkflowInterceptor$WorkflowSession;)Lcom/squareup/workflow1/TreeSnapshot;
@@ -83,6 +87,18 @@ public final class com/squareup/workflow1/WorkflowInterceptor$RenderContextInter
 	public static fun onRunningSideEffect (Lcom/squareup/workflow1/WorkflowInterceptor$RenderContextInterceptor;Ljava/lang/String;Lkotlin/jvm/functions/Function1;Lkotlin/jvm/functions/Function2;)V
 }
 
+public final class com/squareup/workflow1/WorkflowInterceptor$RenderPassSkipped : com/squareup/workflow1/WorkflowInterceptor$RuntimeLoopOutcome {
+	public static final field INSTANCE Lcom/squareup/workflow1/WorkflowInterceptor$RenderPassSkipped;
+}
+
+public final class com/squareup/workflow1/WorkflowInterceptor$RenderPassesComplete : com/squareup/workflow1/WorkflowInterceptor$RuntimeLoopOutcome {
+	public fun <init> (Lcom/squareup/workflow1/RenderingAndSnapshot;)V
+	public final fun getRenderingAndSnapshot ()Lcom/squareup/workflow1/RenderingAndSnapshot;
+}
+
+public abstract interface class com/squareup/workflow1/WorkflowInterceptor$RuntimeLoopOutcome {
+}
+
 public abstract interface class com/squareup/workflow1/WorkflowInterceptor$WorkflowSession {
 	public abstract fun getIdentifier ()Lcom/squareup/workflow1/WorkflowIdentifier;
 	public abstract fun getParent ()Lcom/squareup/workflow1/WorkflowInterceptor$WorkflowSession;

workflow-runtime/src/commonMain/kotlin/com/squareup/workflow1/RenderWorkflow.kt

@@ -2,6 +2,8 @@ package com.squareup.workflow1
 
 import com.squareup.workflow1.RuntimeConfigOptions.CONFLATE_STALE_RENDERINGS
 import com.squareup.workflow1.RuntimeConfigOptions.RENDER_ONLY_WHEN_STATE_CHANGES
+import com.squareup.workflow1.WorkflowInterceptor.RenderPassSkipped
+import com.squareup.workflow1.WorkflowInterceptor.RenderPassesComplete
 import com.squareup.workflow1.internal.WorkflowRunner
 import com.squareup.workflow1.internal.chained
 import kotlinx.coroutines.CancellationException
@@ -129,7 +131,9 @@ public fun <PropsT, OutputT, RenderingT> renderWorkflowIn(
   // coroutine to calculate the initial rendering.
   val renderingsAndSnapshots = MutableStateFlow(
     try {
-      runner.nextRendering()
+      runner.nextRendering().also {
+        chainedInterceptor.onRuntimeLoopTick(RenderPassesComplete(it))
+      }
     } catch (e: Throwable) {
       // If any part of the workflow runtime fails, the scope should be cancelled. We're not in a
       // coroutine yet however, so if the first render pass fails it won't cancel the runtime,
@@ -169,7 +173,9 @@ public fun <PropsT, OutputT, RenderingT> renderWorkflowIn(
     conflationHasChangedState: Boolean = false
   ): Boolean {
     return runtimeConfig.contains(RENDER_ONLY_WHEN_STATE_CHANGES) &&
-      actionResult is ActionApplied<*> && !actionResult.stateChanged && !conflationHasChangedState
+      actionResult is ActionApplied<*> &&
+      !actionResult.stateChanged &&
+      !conflationHasChangedState
   }
 
   scope.launch {
@@ -180,6 +186,7 @@ public fun <PropsT, OutputT, RenderingT> renderWorkflowIn(
       var actionResult: ActionProcessingResult = runner.processAction()
 
       if (shouldShortCircuitForUnchangedState(actionResult)) {
+        chainedInterceptor.onRuntimeLoopTick(RenderPassSkipped)
         sendOutput(actionResult, onOutput)
         continue@outer
       }
@@ -207,6 +214,7 @@ public fun <PropsT, OutputT, RenderingT> renderWorkflowIn(
               conflationHasChangedState = conflationHasChangedState
             )
           ) {
+            chainedInterceptor.onRuntimeLoopTick(RenderPassSkipped)
             sendOutput(actionResult, onOutput)
             continue@outer
           }
@@ -219,7 +227,9 @@ public fun <PropsT, OutputT, RenderingT> renderWorkflowIn(
       }
 
       // Pass on the rendering to the UI.
-      renderingsAndSnapshots.value = nextRenderAndSnapshot
+      renderingsAndSnapshots.value = nextRenderAndSnapshot.also {
+        chainedInterceptor.onRuntimeLoopTick(RenderPassesComplete(it))
+      }
 
       // Emit the Output
       sendOutput(actionResult, onOutput)

workflow-runtime/src/commonMain/kotlin/com/squareup/workflow1/WorkflowInterceptor.kt

@@ -12,10 +12,10 @@ import kotlin.reflect.KType
  * Provides hooks into the workflow runtime that can be used to instrument or modify the behavior
  * of workflows.
  *
- * This interface's methods mirror the methods of [StatefulWorkflow]. It also has one additional
- * method, [onSessionStarted], that is notified when a workflow is started. Each method returns the
- * same thing as the corresponding method on [StatefulWorkflow], and receives the same parameters
- * as well as two extra parameters:
+ * This interface's methods mirror the methods of [StatefulWorkflow], and two additional methods,
+ * explained below.
+ * Each method returns the same thing as the corresponding method on [StatefulWorkflow], and
+ * receives the same parameters as well as two extra parameters:
  *
  *  - **`proceed`** – A function that _exactly_ mirrors the corresponding function on
  *    [StatefulWorkflow], accepting the same parameters and returning the same thing. An interceptor
@@ -28,6 +28,16 @@ import kotlin.reflect.KType
  *
  * All methods have default no-op implementations.
  *
+ * ## Additional Methods
+ *
+ * There are 2 more methods in this interface:
+ *
+ *  1. [onSessionStarted] - called when a new [WorkflowSession] is created the first time a
+ *     workflow is rendered with the [CoroutineScope] for that session.
+ *  1. [onRuntimeLoopTick] - Called to report the [RuntimeLoopOutcome] of each tick of the runtime
+ *     loop. In the simplest case this is the application of one action and one render pass, but
+ *     optimizations can change that. See [onRenderingUpdated] for more.
+ *
  * ## On Profiling
  *
  * Note that the [WorkflowInterceptor]'s methods will call the actual methods with the proceed
@@ -129,6 +139,29 @@ public interface WorkflowInterceptor {
     session: WorkflowSession
   ): Snapshot? = proceed(state)
 
+  /**
+   * Called to report the [outcome] of each tick of the runtime loop. In the simplest case
+   * this is the application of one action and one render pass, but optimizations can
+   * change that:
+   *
+   *  - With the `RENDER_ONLY_WHEN_STATE_CHANGES` optimization, there may not be a render pass
+   *    at all, in which case [RenderPassSkipped] is the outcome.
+   *  - With the `CONFLATE_STALE_RENDERINGS` optimization, there could be multiple render passes.
+   *  - If there is at least one render pass, then [RenderPassesComplete] is passed as the outcome,
+   *    which includes the actual [RenderingAndSnapshot] returned from the runtime.
+   *
+   * @param outcome The [RuntimeLoopOutcome] of the tick of the runtime loop.
+   */
+  public fun onRuntimeLoopTick(
+    outcome: RuntimeLoopOutcome
+  ): Unit = Unit
+
+  public sealed interface RuntimeLoopOutcome
+  public object RenderPassSkipped : RuntimeLoopOutcome
+  public class RenderPassesComplete<R>(
+    public val renderingAndSnapshot: RenderingAndSnapshot<R>
+  ) : RuntimeLoopOutcome
+
   /**
    * Information about the session of a workflow in the runtime that a [WorkflowInterceptor] method
    * is intercepting.

workflow-runtime/src/commonMain/kotlin/com/squareup/workflow1/internal/ChainedWorkflowInterceptor.kt

@@ -9,6 +9,7 @@ import com.squareup.workflow1.Workflow
 import com.squareup.workflow1.WorkflowAction
 import com.squareup.workflow1.WorkflowInterceptor
 import com.squareup.workflow1.WorkflowInterceptor.RenderContextInterceptor
+import com.squareup.workflow1.WorkflowInterceptor.RuntimeLoopOutcome
 import com.squareup.workflow1.WorkflowInterceptor.WorkflowSession
 import kotlinx.coroutines.CoroutineScope
 import kotlin.reflect.KType
@@ -123,6 +124,12 @@ internal class ChainedWorkflowInterceptor(
     return chainedProceed(state)
   }
 
+  override fun onRuntimeLoopTick(outcome: RuntimeLoopOutcome) {
+    interceptors.forEach { interceptor ->
+      interceptor.onRuntimeLoopTick(outcome)
+    }
+  }
+
   private fun <P, S, O> RenderContextInterceptor<P, S, O>?.wrap(
     inner: RenderContextInterceptor<P, S, O>?
   ) = when {