FSharp.Control.TaskSeq 0.4.0

TaskSeq

IAsyncEnumerable 的实现，作为计算表达式：带有关联的 TaskSeq 模块和函数的 taskSeq { ... }，允许无缝使用与 F# 原生 seq 和 task CE 类似的异步序列。

此README介绍了一些重点和已实现函数的摘要。更详细的内容可以在存储库的README中找到。

目录

• 概述
  • 模块函数
  • taskSeq 计算表达式
  • 示例
  • TaskSeq 模块函数
• 更多信息
  • 进一步阅读 IAsyncEnumerable
  • 关于可恢复状态机的进一步阅读
  • 关于计算表达式的进一步阅读

概述

.NET 在 .NET Core 3.0 中添加了 IAsyncEnumerable 接口，它是 .NET Standard 2.1 的一部分。主要用例是针对某些资源的迭代异步、顺序枚举。例如，一个事件流或分页的 REST API 接口，或异步读取文件列表并累积结果，其中的每个动作可以建模为对由 MoveNextAsync 调用返回的 IAsyncEnumerator<'T> 的调用，而该调用是通过 GetAsyncEnumerator() 调用获得的。

自 F# 中引入 task 以来，对原生 任务序列 实现的需求不断增长，特别是在需要对 IAsyncEnumerable 进行正确迭代的情况下，尤其是当想要避免使用可变变量时。这个库是对这一需求的回应，并使用 taskSeq 实现了相同的 可恢复状态机 方法。

模块函数

与 seq 和 Seq 一样，这个库提供了一堆熟悉收集函数，如 TaskSeq.empty、isEmpty 或 TaskSeq.map、iter、collect、fold 和 TaskSeq.find、pick、choose、filter。在这些函数适用的情况下，它们还包括异步版本，如 TaskSeq.mapAsync、iterAsync、collectAsync、foldAsync 和 TaskSeq.findAsync、pickAsync、chooseAsync、filterAsync，这使得应用的功能可以是异步的。

有关当前实现的函数及其变体的完整列表，请参阅下文。

taskSeq 计算表达式

可以使用 taskSeq 计算表达式就像使用 seq 一样。除此之外，它还添加了对通过 let! 和循环遍历正常或异步序列（实现 IAsyncEnumerable<'T> 的序列）进行处理的支持。您可以使用 yield! 和 yield，并且对任务序列表达式内的 use 和 use!、try-with 和 try-finally 以及 while 循环提供了支持。

示例

open System.IO
open FSharp.Control

// singleton is fine
let helloTs = taskSeq { yield "Hello, World!" }

// cold-started, that is, delay-executed
let f() = task {
    // using toList forces execution of whole sequence
    let! hello = TaskSeq.toList helloTs  // toList returns a Task<'T list>
    return List.head hello
}

// can be mixed with normal sequences
let oneToTen = taskSeq { yield! [1..10] }

// can be used with F#'s task and async in a for-loop
let f() = task { for x in oneToTen do printfn "Number %i" x }
let g() = async { for x in oneToTen do printfn "Number %i" x }

// returns a delayed sequence of IAsyncEnumerable<string>
let allFilesAsLines() = taskSeq {
    let files = Directory.EnumerateFiles(@"c:\temp")
    for file in files do
        // await
        let! contents = File.ReadAllLinesAsync file
        // return all lines
        yield! contents
}

let write file =
    allFilesAsLines()

    // synchronous map function on asynchronous task sequence
    |> TaskSeq.map (fun x -> x.Replace("a", "b"))

    // asynchronous map
    |> TaskSeq.mapAsync (fun x -> task { return "hello: " + x })

    // asynchronous iter
    |> TaskSeq.iterAsync (fun data -> File.WriteAllTextAsync(fileName, data))


// infinite sequence
let feedFromTwitter user pwd = taskSeq {
    do! loginToTwitterAsync(user, pwd)
    while true do
       let! message = getNextNextTwitterMessageAsync()
       yield message
}

TaskSeq 模块函数

我们正在努力在 TaskSeq 上得到一组完整的模块函数，以便与 IAsyncEnumerable 序列一起使用。我们的指导是 F# 核心中 Seq 函数的集合，以及适用时 AsyncSeq 提供的函数。每个实现的函数都通过 XML 文档注释进行了文档化，以提供必要的上下文相关的帮助。

以下是至今为止已实现、计划实现或跳过的内容。

Note 1

这些函数要求通过 TaskSeq.cache 进行某种形式的预先验证，类似于在相应的 Seq 函数中采用的方法。拥有一个缓存的后台异步序列没有太多意义。但是，AsyncSeq 仍然实现了这些功能，所以我们可能会最终这样做。

备注2

由于 TaskSeq 序列的异步本质，从后往前迭代是不好的做法。相反，应将序列材料化为列表或数组，然后应用 xxxBack 迭代器。

备注3

在 Seq 中引入 readOnly 的动机是，从可变的数组或列表到 seq<_> 的转换是有效的，并且可以转换回，从而导致可变序列。由于 TaskSeq 不实现 IEnumerable<_>，因此这些转换是不可能的。

更多信息

进一步阅读 IAsyncEnumerable

• 有关如何使用 C# 的良好介绍，请参阅此博客 https://stu.dev/iasyncenumerable-introduction/。
• 在此之后不久，《MSDN 文章》介绍了异步可枚举。
• 以下是一个示例，说明如何将 seq 转换为 IAsyncEnumerable https://gist.github.com/akhansari/d88812b742aa6be1c35b4f46bd9f8532，尽管 TaskSeq 包含许多更多实用功能，且采用的方法略有不同。
• 如果您想使用 IAsyncEnumerable 并使用 async 而不是 task，则应使用出色的 AsyncSeq 库。虽然 TaskSeq 的目的是像 task 一样消费 async，但它不会创建一个 AsyncSeq 类型（至少目前还没有）。如果您想使用经典异步和并行处理，则应使用此库。

关于可恢复状态机的进一步阅读

• F# 单子视角下的状态机 https://blumu.github.io/ResumableMonad/TheResumableMonad.html，它与 F# 6.0 之前的不可恢复内部结构一起使用。
• F# 6.0 上可恢复状态机的原始 RFC https://github.com/fsharp/fslang-design/blob/main/FSharp-6.0/FS-1087-resumable-code.md。
• 引入 F# 6.0 中 task 的原始 RFC https://github.com/fsharp/fslang-design/blob/main/FSharp-6.0/FS-1097-task-builder.md。
• 在 F# Core 中后来添加的 task CE 动机的前 F# 6.0 TaskBuilder https://github.com/rspeele/TaskBuilder.fs/。
• 有关 task https://learn.microsoft.com/en-us/dotnet/fsharp/language-reference/task-expressions 和 async https://learn.microsoft.com/en-us/dotnet/fsharp/language-reference/async-expressions 的 MSDN 文档。

关于计算表达式的进一步阅读

• MSDN 上的 https://learn.microsoft.com/en-us/dotnet/fsharp/language-reference/computation-expressions 文档构成了一个好的总结和起点。
• Scott Wlaschin 的逐步教程是目前有争议的最好的 使用和构建计算表达式的教程。