effect 4.0.3 → 4.0.5

package/src/testing/TestClock.ts

@@ -13,14 +13,14 @@
  */
 import * as Arr from "../Array.ts"
 import * as Clock from "../Clock.ts"
+import * as Context from "../Context.ts"
 import * as Data from "../Data.ts"
 import * as Duration from "../Duration.ts"
 import * as Effect from "../Effect.ts"
 import * as Fiber from "../Fiber.ts"
-import { flow } from "../Function.ts"
 import * as Latch from "../Latch.ts"
 import * as Layer from "../Layer.ts"
-import * as Order from "../Order.ts"
+import * as Scheduler from "../Scheduler.ts"
 import * as Semaphore from "../Semaphore.ts"
 
 /**
@@ -40,6 +40,9 @@ import * as Semaphore from "../Semaphore.ts"
  * the time is set to on or after the time they are scheduled to run. Fork the
  * effect being tested, then adjust the clock time, and finally verify that the
  * expected effects have been performed.
+ * The ordered execution of sleeps registered after multiple scheduler hops
+ * requires fibers running under {@link layer}; providing a clock from
+ * {@link make} by hand does not install the tracking scheduler.
  *
  * **Example** (Testing timeouts deterministically)
  *
@@ -142,7 +145,8 @@ export declare namespace TestClock {
   /**
    * Options used when constructing a `TestClock`. `warningDelay` controls how
    * long the live clock waits before logging a warning when a test uses time
-   * without advancing the test clock.
+   * without advancing the test clock, or when a fiber woken by the test clock
+   * keeps running without suspending.
    *
    * **Example** (Configuring the warning delay)
    *
@@ -170,7 +174,8 @@ export declare namespace TestClock {
   export interface Options {
     /**
      * The amount of time to wait before displaying a warning message when a
-     * test is using time but is not advancing the `TestClock`.
+     * test is using time but is not advancing the `TestClock`, or when a fiber
+     * woken by `adjust` or `setTime` keeps running without suspending.
      */
     readonly warningDelay?: Duration.Input
   }
@@ -197,15 +202,30 @@ const warningMessage = "A test is using time, but is not advancing the test " +
   "clock, which may result in the test hanging. Use TestClock.adjust to " +
   "manually advance the time."
 
+/**
+ * The warning message that will be displayed if a fiber woken by the
+ * `TestClock` does not suspend within the warning delay.
+ */
+const busyWarningMessage = "A fiber woken by the test clock is still running " +
+  "without suspending, so the test clock stopped waiting for it. Sleeps it " +
+  "starts later may be scheduled relative to a later time."
+
+/**
+ * The live clock of each `TestClock`, so a `TestClock` constructed while
+ * another one is the current clock uses the outer clock's live clock instead
+ * of the outer `TestClock`, which only advances when adjusted.
+ */
+const liveClocks = new WeakMap<Clock.Clock, Clock.Clock>()
+
+interface WakeTracker {
+  pending: number
+  onIdle: (() => void) | undefined
+}
+
 const defaultOptions: Required<TestClock.Options> = {
   warningDelay: "1 second"
 }
 
-const SleepOrder = Order.flip(Order.Struct({
-  timestamp: Order.Number,
-  sequence: Order.Number
-}))
-
 const nanosPerMilli = BigInt(1_000_000)
 
 const millisToNanos = (millis: number): bigint => {
@@ -217,6 +237,14 @@ const millisToNanos = (millis: number): bigint => {
 /**
  * Creates a `TestClock` with optional configuration.
  *
+ * **Gotchas**
+ *
+ * The guarantee that sleeps registered after multiple scheduler hops run in
+ * order applies only to fibers running under {@link layer}, which
+ * `@effect/vitest`'s `it.effect` uses. Providing a clock from `make` by hand
+ * waits only one scheduler turn after each woken sleep. Prefer `layer` when
+ * forked fibers sleep.
+ *
  * **Example** (Creating a test clock)
  *
  * ```ts import.meta.vitest
@@ -245,18 +273,21 @@ const millisToNanos = (millis: number): bigint => {
  * @category constructors
  * @since 4.0.0
  */
-export const make = Effect.fnUntraced(function*(
+export const make = (options?: TestClock.Options) => Effect.map(makeWithScheduler(options), ([testClock]) => testClock)
+
+const makeWithScheduler = Effect.fnUntraced(function*(
   options?: TestClock.Options
 ) {
   const config = { ...defaultOptions, ...options }
-  let sequence = 0
+  // Sorted by descending timestamp, so `pop` wakes the earliest sleep first
   const sleeps: Array<{
-    readonly sequence: number
     readonly timestamp: number
     readonly latch: Latch.Latch
   }> = []
-  const liveClock = yield* Clock.clockWith(Effect.succeed)
+  const currentClock = yield* Clock.clockWith(Effect.succeed)
+  const liveClock = liveClocks.get(currentClock) ?? currentClock
   const warningSemaphore = yield* Semaphore.make(1)
+  const parentScheduler = yield* Scheduler.Scheduler
 
   let currentTimestamp: number = new Date(0).getTime()
   let currentWallNanos = BigInt(0)
@@ -332,17 +363,97 @@ export const make = Effect.fnUntraced(function*(
     const millis = Duration.toMillis(duration)
     const end = currentTimestamp + millis
     if (end <= currentTimestamp) return
-    const latch = Latch.makeUnsafe()
-    sleeps.push({
-      sequence: sequence++,
-      timestamp: end,
-      latch
-    })
-    sleeps.sort(SleepOrder)
-    yield* warningStart
-    yield* latch.await
+    yield* Effect.acquireUseRelease(
+      Effect.sync(() => {
+        const entry = { timestamp: end, latch: Latch.makeUnsafe() }
+        // Insert before entries with an equal timestamp, so they wake in
+        // registration order
+        let low = 0
+        let high = sleeps.length
+        while (low < high) {
+          const mid = (low + high) >>> 1
+          if (sleeps[mid].timestamp > end) low = mid + 1
+          else high = mid
+        }
+        sleeps.splice(low, 0, entry)
+        return entry
+      }),
+      (entry) => Effect.andThen(warningStart, entry.latch.await),
+      (entry) =>
+        Effect.sync(() => {
+          // The entry is already gone if `run` popped it
+          const index = sleeps.indexOf(entry)
+          if (index !== -1) sleeps.splice(index, 1)
+        })
+    )
   })
 
+  /**
+   * Tasks scheduled while waking a sleeper, and tasks scheduled by those tasks,
+   * are counted by that wake's tracker so `run` can wait for the woken fiber,
+   * and any fibers it resumes or forks, to suspend before checking the next
+   * sleep.
+   */
+  let currentTracker: WakeTracker | undefined = undefined
+
+  function runTracked(tracker: WakeTracker, f: () => void): void {
+    const previous = currentTracker
+    currentTracker = tracker
+    try {
+      f()
+    } finally {
+      currentTracker = previous
+    }
+  }
+
+  const scheduler: Scheduler.Scheduler = {
+    executionMode: parentScheduler.executionMode,
+    shouldYield: (fiber) => parentScheduler.shouldYield(fiber),
+    makeDispatcher() {
+      const dispatcher = parentScheduler.makeDispatcher()
+      return {
+        scheduleTask(task, priority) {
+          const tracker = currentTracker
+          if (tracker === undefined) {
+            return dispatcher.scheduleTask(task, priority)
+          }
+          tracker.pending++
+          dispatcher.scheduleTask(() => {
+            try {
+              runTracked(tracker, task)
+            } finally {
+              if (--tracker.pending === 0) tracker.onIdle?.()
+            }
+          }, priority)
+        },
+        flush() {
+          dispatcher.flush()
+        }
+      }
+    }
+  }
+
+  const wake = (latch: Latch.Latch) =>
+    Effect.suspend(() => {
+      const tracker: WakeTracker = { pending: 0, onIdle: undefined }
+      runTracked(tracker, () => latch.openUnsafe())
+      if (tracker.pending === 0) return Effect.yieldNow
+      return Effect.callback<void>((resume) => {
+        if (tracker.pending === 0) return resume(Effect.void)
+        tracker.onIdle = () => resume(Effect.void)
+        return Effect.sync(() => {
+          tracker.onIdle = undefined
+        })
+      }).pipe(
+        Effect.timeoutOrElse({
+          duration: config.warningDelay,
+          orElse: () => Effect.logWarning(busyWarningMessage)
+        }),
+        withLive,
+        Effect.andThen(Effect.yieldNow)
+      )
+    })
+
   const runSemaphore = yield* Semaphore.make(1)
   const run = Effect.fnUntraced(function*(
     step: (currentTimestamp: number) => number,
@@ -366,8 +477,7 @@ export const make = Effect.fnUntraced(function*(
       if (Arr.lastNonEmpty(sleeps).timestamp > endTimestamp) break
       const entry = sleeps.pop()!
       advanceTo(entry.timestamp)
-      entry.latch.openUnsafe()
-      yield* Effect.yieldNow
+      yield* wake(entry.latch)
     }
     advanceTo(endTimestamp)
     if (adjustmentNanos !== undefined && Number.isFinite(endTimestamp)) {
@@ -391,7 +501,7 @@ export const make = Effect.fnUntraced(function*(
 
   yield* Effect.addFinalizer(() => warningDone)
 
-  return {
+  const testClock = {
     currentTimeMillisUnsafe,
     currentTimeNanosUnsafe,
     monotonicTimeNanosUnsafe,
@@ -403,6 +513,8 @@ export const make = Effect.fnUntraced(function*(
     sleep,
     withLive
   }
+  liveClocks.set(testClock, liveClock)
+  return [testClock, scheduler] as const
 })
 
 /**
@@ -438,10 +550,13 @@ export const make = Effect.fnUntraced(function*(
  * @category layers
  * @since 4.0.0
  */
-export const layer: (options?: TestClock.Options) => Layer.Layer<TestClock> = flow(
-  make,
-  Layer.effect(Clock.Clock)
-) as any
+export const layer = (options?: TestClock.Options): Layer.Layer<TestClock> =>
+  Layer.effectContext(
+    Effect.map(makeWithScheduler(options), ([testClock, scheduler]) =>
+      Context.make(Clock.Clock, testClock).pipe(
+        Context.add(Scheduler.Scheduler, scheduler)
+      ))
+  ) as any
 
 /**
  * Retrieves the `TestClock` service for this test and uses it to run the

package/src/workflow/Activity.ts

@@ -347,6 +347,7 @@ const makeExecute = Effect.fnUntraced(function*<
     (_) => _._tag === "Suspended"
   )
   if (result._tag === "Suspended") {
+    if (result.failed) instance.failed = true
     return yield* Workflow.suspend(instance)
   }
   return yield* result.exit

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/Workflow.ts

@@ -78,11 +78,26 @@ export interface Workflow<
 
   /**
    * Execute the workflow with the given payload.
+   *
+   * **Details**
+   *
+   * `discard: true` returns the execution ID without waiting for the result.
+   * The child remains linked to its parent for completion wakes and interruption.
+   *
+   * With `discard: true, detached: true`, the child neither wakes its parent
+   * nor gets interrupted with it. The cluster engine retains the parent for
+   * observability.
+   *
+   * **Gotchas**
+   *
+   * Do not await a detached execution later. Executing the same payload joins
+   * it, but its completion will not wake the awaiting workflow.
    */
   readonly execute: <const Discard extends boolean = false>(
     payload: Payload["~type.make.in"],
     options?: {
       readonly discard?: Discard
+      readonly detached?: [Discard] extends [true] ? boolean | undefined : undefined
     }
   ) => Effect.Effect<
     Discard extends true ? string : Success["Type"],
@@ -248,7 +263,7 @@ export interface AnyWithProps extends Any {
   readonly errorSchema: Schema.Top
   readonly execute: (
     payload: any,
-    options?: { readonly discard?: boolean }
+    options?: { readonly discard?: boolean; readonly detached?: boolean | undefined }
   ) => Effect.Effect<any, any, any>
   readonly resume: (
     executionId: string
@@ -352,7 +367,7 @@ const Proto = {
   execute<const Discard extends boolean = false>(
     this: AnyWithProps,
     fields: any,
-    opts?: { readonly discard?: Discard } | undefined
+    opts?: { readonly discard?: Discard; readonly detached?: boolean | undefined } | undefined
   ) {
     return Effect.suspend(() => {
       const payload = this.payloadSchema.make(fields)
@@ -366,6 +381,7 @@ const Proto = {
                 executionId,
                 payload,
                 discard: opts?.discard,
+                detached: opts?.detached,
                 suspendedRetrySchedule: this.suspendedRetrySchedule
               })
             ))
@@ -617,6 +633,11 @@ export class Complete<A, E> extends Data.TaggedClass("Complete")<{
  * Represents a suspended workflow execution, optionally carrying the cause that
  * triggered suspension.
  *
+ * **Details**
+ *
+ * `failed` marks this execution's own `SuspendOnFailure` and requires explicit
+ * `resume` or `interrupt`. Inherited child failures do not set it.
+ *
  * @stability unstable
  * @category schemas
  * @since 4.0.0
@@ -625,7 +646,8 @@ export class Suspended extends Schema.Class<Suspended>(
   "effect/workflow/Workflow/Suspended"
 )({
   _tag: Schema.tag("Suspended"),
-  cause: Schema.optional(Schema.Cause(Schema.Never, Schema.Defect()))
+  cause: Schema.optional(Schema.Cause(Schema.Never, Schema.Defect())),
+  failed: Schema.optional(Schema.Boolean)
 }) {
   /**
    * Marks this value as a workflow result for runtime guards.
@@ -697,11 +719,13 @@ export const intoResult = <A, E, R>(
       Effect.interruptible,
       suspendOnFailure
         ? Effect.catchCause((cause) => {
-          if (instance.abandoned) {
+          if (instance.abandoned || instance.interrupted) {
             return Effect.failCause(cause)
           }
           instance.suspended = true
+          // Ordinary suspension is a self-interrupt and also reaches here.
           if (!Cause.hasInterruptsOnly(cause)) {
+            instance.failed = true
             instance.cause = Cause.die(Cause.squash(cause))
           }
           return Effect.interrupt
@@ -720,7 +744,9 @@ export const intoResult = <A, E, R>(
           const abandoned = instance.abandoned && !instance.interrupted && hasInterruptsOnly
           instance.abandoned = abandoned
           if (instance.suspended && hasInterruptsOnly && !abandoned) {
-            return Effect.succeed(new Suspended({ cause: instance.cause }))
+            return Effect.succeed(
+              new Suspended(instance.failed ? { cause: instance.cause, failed: true } : { cause: instance.cause })
+            )
           }
           if (!instance.interrupted && hasInterruptsOnly) {
             // External interrupts exit without a result. When the cluster has