延迟值

一个 Deferred<Success, Error> 是 Effect 的专门子类型，它像一个具有一些独特特征的一次性变量。它只能完成一次，使其成为管理异步操作和程序不同部分之间同步的有用工具。

延迟值本质上是一个同步原语，表示一个可能不会立即可用的值。当您创建延迟值时，它开始是空的。稍后，它可以用成功值 Success 或错误值 Error 完成：

           ┌─── Represents the success type
           │        ┌─── Represents the error type
           │        │
           ▼        ▼
Deferred<Success, Error>

一旦完成，就不能再次更改。

当纤程调用 Deferred.await 时，它将暂停直到延迟值完成。当纤程等待时，它不会阻塞线程，只是在语义上阻塞。这意味着其他纤程仍然可以运行，确保高效的并发。

延迟值在概念上类似于 JavaScript 的 Promise。 关键区别在于它支持成功和错误类型，提供更多的类型安全性。

创建延迟值

可以使用 Deferred.make 构造函数创建延迟值。这返回一个表示延迟值创建的 effect。由于延迟值的创建涉及内存分配，必须在 effect 内完成以确保资源的安全管理。

示例（创建延迟值）

import { Deferred } from "effect"

//      ┌─── Effect<Deferred<string, Error>>
//      ▼
const deferred = Deferred.make<string, Error>()

等待

要从延迟值中检索值，您可以使用 Deferred.await。此操作会暂停调用纤程，直到延迟值完成并返回值或错误。

import { Effect, Deferred } from "effect"

//      ┌─── Effect<Deferred<string, Error>, never, never>
//      ▼
const deferred = Deferred.make<string, Error>()

//      ┌─── Effect<string, Error, never>
//      ▼
const value = deferred.pipe(Effect.andThen(Deferred.await))

完成

您可以通过多种方式完成延迟值，具体取决于您是否要成功、失败或中断等待的纤程：

API	描述
Deferred.succeed	使用值成功完成延迟值。
Deferred.done	使用 Exit 值完成延迟值。
Deferred.complete	使用 effect 的结果完成延迟值。
Deferred.completeWith	使用 effect 完成延迟值。此 effect 将由每个等待的纤程执行，因此请谨慎使用。
Deferred.fail	使用错误使延迟值失败。
Deferred.die	使用用户定义的错误使延迟值缺陷。
Deferred.failCause	使用 Cause 使延迟值失败或缺陷。
Deferred.interrupt	中断延迟值，强制停止或中断等待的纤程。

示例（成功完成延迟值）

import { Effect, Deferred } from "effect"

const program = Effect.gen(function* () {
  const deferred = yield* Deferred.make<number, string>()

  // 成功完成延迟值
  yield* Deferred.succeed(deferred, 1)

  // 等待延迟值以获取其值
  const value = yield* Deferred.await(deferred)

  console.log(value)
})

Effect.runFork(program)
// 输出: 1

完成延迟值会产生一个 Effect<boolean>。如果延迟值成功完成，此 effect 返回 true，如果之前已经完成，则返回 false。这对于跟踪延迟值的状态很有用。

示例（检查完成状态）

import { Effect, Deferred } from "effect"

const program = Effect.gen(function* () {
  const deferred = yield* Deferred.make<number, string>()

  // 尝试使延迟值失败
  const firstAttempt = yield* Deferred.fail(deferred, "oh no!")

  // 在已经完成后尝试成功
  const secondAttempt = yield* Deferred.succeed(deferred, 1)

  console.log([firstAttempt, secondAttempt])
})

Effect.runFork(program)
// 输出: [ true, false ]

检查完成状态

有时，您可能需要检查延迟值是否已完成而不暂停纤程。这可以使用 Deferred.poll 方法来完成。它的工作原理如下：

• Deferred.poll 返回一个 Option<Effect<A, E>>：
  • 如果 Deferred 未完成，它返回 None。
  • 如果 Deferred 已完成，它返回 Some，其中包含结果或错误。

此外，您可以使用 Deferred.isDone 函数来检查延迟值是否已完成。此方法返回一个 Effect<boolean>，如果 Deferred 已完成，则计算为 true，允许您快速检查其状态。

示例（轮询和检查完成状态）

import { Effect, Deferred } from "effect"

const program = Effect.gen(function* () {
  const deferred = yield* Deferred.make<number, string>()

  // 轮询延迟值以检查是否已完成
  const done1 = yield* Deferred.poll(deferred)

  // 检查延迟值是否已完成
  const done2 = yield* Deferred.isDone(deferred)

  console.log([done1, done2])
})

Effect.runFork(program)
/*
输出:
[ { _id: 'Option', _tag: 'None' }, false ]
*/

常见用例

当您需要等待程序中发生特定事情时，Deferred 变得很有用。 它非常适合您希望代码的一部分在准备就绪时向另一部分发出信号的场景。

以下是一些常见用例：

用例	描述
协调纤程	当您有多个并发任务并需要协调它们的操作时，Deferred 可以帮助一个纤程在完成任务时向另一个纤程发出信号。
同步	任何时候您想确保一段代码在另一段代码完成工作之前不会继续执行，Deferred 可以提供您需要的同步。
工作交接	您可以使用 Deferred 将工作从一个纤程交给另一个纤程。例如，一个纤程可以准备一些数据，然后第二个纤程可以继续处理它。
暂停执行	当您希望纤程暂停执行直到满足某些条件时，可以使用 Deferred 阻塞它直到条件满足。

示例（使用延迟值协调两个纤程）

在此示例中，延迟值用于在两个纤程之间传递值。

通过并发运行两个纤程并使用延迟值作为同步点，我们可以确保 fiberB 仅在 fiberA 完成其任务后才继续。

import { Effect, Deferred, Fiber } from "effect"

const program = Effect.gen(function* () {
  const deferred = yield* Deferred.make<string, string>()

  // 延迟后使用值完成延迟值
  const taskA = Effect.gen(function* () {
    console.log("开始完成延迟值的任务")
    yield* Effect.sleep("1 second")
    console.log("完成延迟值")
    return yield* Deferred.succeed(deferred, "hello world")
  })

  // 等待延迟值并打印值
  const taskB = Effect.gen(function* () {
    console.log("开始从延迟值获取值的任务")
    const value = yield* Deferred.await(deferred)
    console.log("从延迟值获取了值")
    return value
  })

  // 并发运行两个纤程
  const fiberA = yield* Effect.fork(taskA)
  const fiberB = yield* Effect.fork(taskB)

  // 等待两个纤程完成
  const both = yield* Fiber.join(Fiber.zip(fiberA, fiberB))

  console.log(both)
})

Effect.runFork(program)
/*
开始完成延迟值的任务
开始从延迟值获取值的任务
完成延迟值
从延迟值获取了值
[ true, 'hello world' ]
*/