effect 4.0.3 → 4.0.4

package/src/workflow/DurableDeferred.ts

@@ -134,6 +134,25 @@ const CurrentAttempt = Context.Reference<number>(
   { defaultValue: () => 1 }
 )
 
+/** Awaits registered under the instance copy of a `recordHeld` body. */
+const awaitOwners = new WeakMap<WorkflowInstance["Service"], Array<string>>()
+
+const registerAwait = (instance: WorkflowInstance["Service"], name: string) => {
+  instance.awaitedDeferreds.set(name, (instance.awaitedDeferreds.get(name) ?? 0) + 1)
+  awaitOwners.get(instance)?.push(name)
+}
+
+const releaseAwaits = (instance: WorkflowInstance["Service"], names: Array<string>) => {
+  for (const name of names) {
+    const count = instance.awaitedDeferreds.get(name)! - 1
+    if (count === 0) {
+      instance.awaitedDeferreds.delete(name)
+    } else {
+      instance.awaitedDeferreds.set(name, count)
+    }
+  }
+}
+
 const await_: <Success extends Schema.Constraint, Error extends Schema.Constraint>(
   self: DurableDeferred<Success, Error>
 ) => Effect.Effect<
@@ -150,7 +169,7 @@ const await_: <Success extends Schema.Constraint, Error extends Schema.Constrain
   const engine = yield* EngineTag
   const instance = yield* InstanceTag
   // Register before the read so any later completion can preempt the run.
-  instance.awaitedDeferreds.add(self.name)
+  registerAwait(instance, self.name)
   const exit = yield* Workflow.wrapActivityResult(
     engine.deferredResult(self),
     Option.isNone
@@ -343,6 +362,10 @@ const recordHeld = Effect.fnUntraced(function*<A, E, R>(
         suspended: false,
         activityState: { count: 0, latch: Latch.makeUnsafe() }
       }
+      // A losing branch parked on a durable wait has already exited when the
+      // race settles, so this body owns the waits registered beneath it.
+      const owned: Array<string> = []
+      awaitOwners.set(local, owned)
       // A parked `effect` interrupts the fiber it runs on. The child fiber
       // keeps that from skipping the suspension handling below.
       const fiber = yield* effect.pipe(
@@ -350,10 +373,25 @@ const recordHeld = Effect.fnUntraced(function*<A, E, R>(
         Effect.onExit((exit) => recordExit(engine, instance, self, exit)),
         Effect.forkChild({ startImmediately: true })
       )
-      const exit = yield* Effect.onInterrupt(Fiber.await(fiber), () => Fiber.interrupt(fiber))
-      return local.suspended && Exit.isFailure(exit) && Cause.hasInterruptsOnly(exit.cause)
-        ? Option.none()
-        : Option.some(exit)
+      return yield* Effect.onInterrupt(Fiber.await(fiber), () => Fiber.interrupt(fiber)).pipe(
+        Effect.map((exit) =>
+          local.suspended && Exit.isFailure(exit) && Cause.hasInterruptsOnly(exit.cause)
+            ? Option.none()
+            : Option.some(exit)
+        ),
+        // The waits are over once the body has a result. Otherwise every branch
+        // parked, or an enclosing race interrupted the body, and the waits move
+        // to the enclosing owner, if any, to be released when that race settles.
+        Effect.onExit((result) =>
+          Effect.sync(() => {
+            if (Exit.isSuccess(result) && Option.isSome(result.value)) {
+              releaseAwaits(instance, owned)
+            } else {
+              awaitOwners.get(instance)?.push(...owned)
+            }
+          })
+        )
+      )
     }),
     // Every branch of `effect` parked: release the hold and let the enclosing
     // activities finish before suspending. External preemption does not wait.

package/src/workflow/WorkflowEngine.ts

@@ -12,6 +12,7 @@
  */
 import * as Cause from "../Cause.ts"
 import * as Context from "../Context.ts"
+import * as Deferred from "../Deferred.ts"
 import * as Effect from "../Effect.ts"
 import * as Exit from "../Exit.ts"
 import * as Fiber from "../Fiber.ts"
@@ -75,6 +76,14 @@ export class WorkflowEngine extends Context.Service<
 
     /**
      * Execute a registered workflow.
+     *
+     * **Details**
+     *
+     * Unless `discard` is set, a caller outside any workflow waits for the
+     * result. While the execution is suspended, the caller retries on
+     * `suspendedRetrySchedule`; engines that observe the final result wake it
+     * sooner. `ClusterWorkflowEngine` does so only for callers on the runner
+     * that owns the execution.
      */
     readonly execute: <
       Name extends string,
@@ -271,8 +280,11 @@ export class WorkflowInstance extends Context.Service<
      */
     cause: Cause.Cause<never> | undefined
 
-    /** Deferred names this run parked on; their completions preempt the run. */
-    readonly awaitedDeferreds: Set<string>
+    /**
+     * Deferred names this run waits on, counted per live wait; their
+     * completions preempt the run.
+     */
+    readonly awaitedDeferreds: Map<string, number>
 
     /** Deferred names this run completed itself; their completions need not wake it. */
     readonly completedDeferreds: Set<string>
@@ -296,7 +308,7 @@ export class WorkflowInstance extends Context.Service<
       interrupted: false,
       abandoned: false,
       cause: undefined,
-      awaitedDeferreds: new Set(),
+      awaitedDeferreds: new Map(),
       completedDeferreds: new Set(),
       activityState: {
         count: 0,
@@ -414,6 +426,22 @@ export interface Encoded {
     workflow: Workflow.Any,
     executionId: string
   ) => Effect.Effect<void>
+
+  /**
+   * Waits until a suspended execution has a result other than `Suspended`.
+   *
+   * **Gotchas**
+   *
+   * External callers race this with their `suspendedRetrySchedule`, so it may
+   * never complete when the engine cannot observe the result. Completing while
+   * the execution is still suspended skips the sleep and spends a step of that
+   * schedule. A hook that keeps completing early makes the caller spin.
+   */
+  readonly awaitComplete?: (
+    workflow: Workflow.Any,
+    executionId: string
+  ) => Effect.Effect<void>
+
   readonly activityExecute: (
     activity: Activity.Any,
     attempt: number
@@ -548,7 +576,10 @@ export const makeUnsafe = (options: Encoded): WorkflowEngine["Service"] =>
             )
           )
         )
-        yield* sleep
+        // Completion wakes the caller early; the schedule is the fallback.
+        yield* options.awaitComplete
+          ? Effect.raceFirst(sleep, options.awaitComplete(self, executionId))
+          : sleep
       }
     }),
     poll: options.poll,
@@ -685,6 +716,8 @@ export const layerMemory: Layer.Layer<WorkflowEngine> = Layer.effect(WorkflowEng
       interrupted: boolean
       resumeRequested: boolean
       fiber: Fiber.Fiber<Workflow.Result<unknown, unknown>> | undefined
+      // Completed once a run succeeds with `Complete`, after which it cannot resume.
+      readonly done: Deferred.Deferred<void>
     }
     const executions = new Map<string, ExecutionState>()
 
@@ -742,6 +775,11 @@ export const layerMemory: Layer.Layer<WorkflowEngine> = Layer.effect(WorkflowEng
           }
           return Effect.forkIn(resume(state.parent), scope)
         }),
+        Effect.onExit((exit) => {
+          return Exit.isSuccess(exit) && exit.value._tag === "Complete"
+            ? Deferred.succeed(state.done, void 0)
+            : Effect.void
+        }),
         Effect.forkIn(entry.scope)
       )
     })
@@ -773,6 +811,7 @@ export const layerMemory: Layer.Layer<WorkflowEngine> = Layer.effect(WorkflowEng
             interrupted: false,
             resumeRequested: false,
             fiber: undefined,
+            done: Deferred.makeUnsafe(),
             parent: options.parent?.executionId
           }
           executions.set(options.executionId, state)
@@ -788,6 +827,11 @@ export const layerMemory: Layer.Layer<WorkflowEngine> = Layer.effect(WorkflowEng
         }
         return (yield* exit) as any
       }),
+      awaitComplete: (_workflow, executionId) =>
+        Effect.suspend(() => {
+          const state = executions.get(executionId)
+          return state ? Deferred.await(state.done) : Effect.never
+        }),
       interrupt: Effect.fnUntraced(function*(_workflow, executionId) {
         const state = executions.get(executionId)
         if (!state) return