超时

在编程中，处理可能需要一些时间才能完成的任务是很常见的。通常，我们希望对等待这些任务的时间施加限制。Effect.timeout 函数通过对操作施加时间约束来提供帮助，确保它不会无限期运行。

基本用法

timeout

Effect.timeout 函数使用持续时间参数来为操作建立时间限制。如果操作超过此限制，将触发 TimeoutException，表示发生了超时。

示例（设置超时）

在这里，任务在超时持续时间内完成，因此成功返回结果。

import { Effect } from "effect"

const task = Effect.gen(function* () {
  console.log("Start processing...")
  yield* Effect.sleep("2 seconds") // 模拟处理中的延迟
  console.log("Processing complete.")
  return "Result"
})

// 为任务设置 3 秒超时
const timedEffect = task.pipe(Effect.timeout("3 seconds"))

// 输出将显示任务成功完成
// 因为它在超时持续时间内
Effect.runPromiseExit(timedEffect).then(console.log)
/*
Output:
Start processing...
Processing complete.
{ _id: 'Exit', _tag: 'Success', value: 'Result' }
*/

如果操作超过指定持续时间，将引发 TimeoutException：

import { Effect } from "effect"

const task = Effect.gen(function* () {
  console.log("Start processing...")
  yield* Effect.sleep("2 seconds") // 模拟处理中的延迟
  console.log("Processing complete.")
  return "Result"
})

// 输出将显示 TimeoutException，因为任务花费的时间
// 超过了指定的超时持续时间
const timedEffect = task.pipe(Effect.timeout("1 second"))

Effect.runPromiseExit(timedEffect).then(console.log)
/*
Output:
Start processing...
{
  _id: 'Exit',
  _tag: 'Failure',
  cause: {
    _id: 'Cause',
    _tag: 'Fail',
    failure: { _tag: 'TimeoutException' }
  }
}
*/

timeoutOption

如果您想更优雅地处理超时，请考虑使用 Effect.timeoutOption。此函数将超时视为常规结果，将结果包装在选项中。

示例（将超时作为选项处理）

在此示例中，第一个任务成功完成，而第二个任务超时。超时任务的结果在 Option 类型中表示为 None。

import { Effect } from "effect"

const task = Effect.gen(function* () {
  console.log("Start processing...")
  yield* Effect.sleep("2 seconds") // 模拟处理中的延迟
  console.log("Processing complete.")
  return "Result"
})

const timedOutEffect = Effect.all([
  task.pipe(Effect.timeoutOption("3 seconds")),
  task.pipe(Effect.timeoutOption("1 second"))
])

Effect.runPromise(timedOutEffect).then(console.log)
/*
Output:
Start processing...
Processing complete.
Start processing...
[
  { _id: 'Option', _tag: 'Some', value: 'Result' },
  { _id: 'Option', _tag: 'None' }
]
*/

处理超时

当操作在指定持续时间内未完成时，Effect.timeout 的行为取决于操作是否”不可中断”。

不可中断的 Effect

不可中断的 effect 是指一旦启动，就不能被超时机制直接在执行过程中停止的 effect。这可能是因为 effect 内的操作需要运行到完成，以避免使系统处于不一致状态。

1. 可中断操作：如果操作可以被中断，一旦达到超时阈值，它会立即终止，导致 TimeoutException。

   import { Effect } from "effect"
   
   const task = Effect.gen(function* () {
     console.log("Start processing...")
     yield* Effect.sleep("2 seconds") // 模拟处理中的延迟
     console.log("Processing complete.")
     return "Result"
   })
   
   const timedEffect = task.pipe(Effect.timeout("1 second"))
   
   Effect.runPromiseExit(timedEffect).then(console.log)
   /*
    Output:
    Start processing...
    {
      _id: 'Exit',
      _tag: 'Failure',
      cause: {
        _id: 'Cause',
        _tag: 'Fail',
        failure: { _tag: 'TimeoutException' }
      }
    }
    */

2. 不可中断操作：如果操作是不可中断的，它会继续执行直到完成，然后才评估 TimeoutException。

   import { Effect } from "effect"
   
   const task = Effect.gen(function* () {
     console.log("Start processing...")
     yield* Effect.sleep("2 seconds") // 模拟处理中的延迟
     console.log("Processing complete.")
     return "Result"
   })
   
   const timedEffect = task.pipe(
     Effect.uninterruptible,
     Effect.timeout("1 second")
   )
   
   // 在任务完成后输出 TimeoutException，
   // 因为任务是不可中断的
   Effect.runPromiseExit(timedEffect).then(console.log)
   /*
    Output:
    Start processing...
    Processing complete.
    {
      _id: 'Exit',
      _tag: 'Failure',
      cause: {
        _id: 'Cause',
        _tag: 'Fail',
        failure: { _tag: 'TimeoutException' }
      }
    }
    */

超时时断开连接

Effect.disconnect 函数提供了一种更灵活地处理不可中断 effect 中超时的方法。它允许不可中断的 effect 在后台完成，而主控制流程继续进行，就像发生了超时一样。

区别如下：

不使用 Effect.disconnect：

• 不可中断的 effect 将忽略超时并继续执行直到完成，之后才评估超时错误。
• 这可能导致识别超时条件的延迟，因为系统必须等待 effect 完成。

使用 Effect.disconnect：

• 不可中断的 effect 被允许在后台继续，独立于主控制流程。
• 主控制流程立即识别超时并继续处理超时错误或替代逻辑，而无需等待 effect 完成。
• 当 effect 的操作不需要阻塞程序的继续执行时，此方法特别有用，尽管被标记为不可中断。

示例（运行带超时和后台完成的不可中断任务）

考虑这样一个场景：启动了一个长时间运行的数据处理任务，您希望确保系统保持响应，即使数据处理花费太长时间：

import { Effect } from "effect"

const longRunningTask = Effect.gen(function* () {
  console.log("Start heavy processing...")
  yield* Effect.sleep("5 seconds") // 模拟长时间处理
  console.log("Heavy processing done.")
  return "Data processed"
})

const timedEffect = longRunningTask.pipe(
  Effect.uninterruptible,
  // 如果超时，允许任务在后台完成
  Effect.disconnect,
  Effect.timeout("1 second")
)

Effect.runPromiseExit(timedEffect).then(console.log)
/*
Output:
Start heavy processing...
{
  _id: 'Exit',
  _tag: 'Failure',
  cause: {
    _id: 'Cause',
    _tag: 'Fail',
    failure: { _tag: 'TimeoutException' }
  }
}
Heavy processing done.
*/

在此示例中，系统在一秒后检测到超时，但长时间运行的任务继续在后台完成，而不会阻塞程序的流程。

自定义超时行为

除了基本的 Effect.timeout 函数外，还有一些变体可让您自定义超时发生时的行为。

timeoutFail

Effect.timeoutFail 函数允许您在超时发生时产生特定错误。

示例（自定义超时错误）

import { Effect, Data } from "effect"

const task = Effect.gen(function* () {
  console.log("Start processing...")
  yield* Effect.sleep("2 seconds") // 模拟处理中的延迟
  console.log("Processing complete.")
  return "Result"
})

class MyTimeoutError extends Data.TaggedError("MyTimeoutError")<{}> {}

const program = task.pipe(
  Effect.timeoutFail({
    duration: "1 second",
    onTimeout: () => new MyTimeoutError() // 自定义超时错误
  })
)

Effect.runPromiseExit(program).then(console.log)
/*
Output:
Start processing...
{
  _id: 'Exit',
  _tag: 'Failure',
  cause: {
    _id: 'Cause',
    _tag: 'Fail',
    failure: MyTimeoutError { _tag: 'MyTimeoutError' }
  }
}
*/

timeoutFailCause

Effect.timeoutFailCause 让您定义在超时发生时抛出的特定缺陷。这对于将超时视为代码中的异常情况很有帮助。

示例（超时时的自定义缺陷）

import { Effect, Cause } from "effect"

const task = Effect.gen(function* () {
  console.log("Start processing...")
  yield* Effect.sleep("2 seconds") // 模拟处理中的延迟
  console.log("Processing complete.")
  return "Result"
})

const program = task.pipe(
  Effect.timeoutFailCause({
    duration: "1 second",
    onTimeout: () => Cause.die("Timed out!") // 超时的自定义缺陷
  })
)

Effect.runPromiseExit(program).then(console.log)
/*
Output:
Start processing...
{
  _id: 'Exit',
  _tag: 'Failure',
  cause: { _id: 'Cause', _tag: 'Die', defect: 'Timed out!' }
}
*/

timeoutTo

Effect.timeoutTo 与 Effect.timeout 相比提供了更多灵活性，允许您为成功和超时操作定义不同的结果。当您想要根据操作是否及时完成来自定义结果时，这很有用。

示例（使用 Either 处理成功和超时）

import { Effect, Either } from "effect"

const task = Effect.gen(function* () {
  console.log("Start processing...")
  yield* Effect.sleep("2 seconds") // 模拟处理中的延迟
  console.log("Processing complete.")
  return "Result"
})

const program = task.pipe(
  Effect.timeoutTo({
    duration: "1 second",
    onSuccess: (result): Either.Either<string, string> =>
      Either.right(result),
    onTimeout: (): Either.Either<string, string> =>
      Either.left("Timed out!")
  })
)

Effect.runPromise(program).then(console.log)
/*
Output:
Start processing...
{
  _id: "Either",
  _tag: "Left",
  left: "Timed out!"
}
*/