Skip to content

nuget-package-readme.md

Latest commit

 

History

History
311 lines (264 loc) · 27.8 KB

nuget-package-readme.md

File metadata and controls

311 lines (264 loc) · 27.8 KB

TaskSeq

An implementation of IAsyncEnumerable<'T> as a computation expression: taskSeq { ... } with an accompanying TaskSeq module, that allows seamless use of asynchronous sequences similar to F#'s native seq and task CE's.

This readme covers the highlights and a summary of implemented functions. A more extensive overview can be found in the repository's readme.

Table of contents

Overview

The IAsyncEnumerable interface was added to .NET in .NET Core 3.0 and is part of .NET Standard 2.1. The main use-case was for iterative asynchronous enumeration over some resource. For instance, an event stream or a REST API interface with pagination, asynchronous reading over a list of files and accumulating the results, where each action can be modeled as a MoveNextAsync call on the IAsyncEnumerator<'T> given by a call to GetAsyncEnumerator().

Since the introduction of task in F# the call for a native implementation of task sequences has grown, in particular because proper iterating over an IAsyncEnumerable has proven challenging, especially if one wants to avoid mutable variables. This library is an answer to that call and implements the same resumable state machine approach with taskSeq.

Module functions

As with seq and Seq, this library comes with a bunch of well-known collection functions, like TaskSeq.empty, isEmpty or TaskSeq.map, iter, collect, fold and TaskSeq.find, pick, choose, filter. Where applicable, these come with async variants, like TaskSeq.mapAsync iterAsync, collectAsync, foldAsync and TaskSeq.findAsync, pickAsync, chooseAsync, filterAsync, which allows the applied function to be asynchronous.

See below for a full list of currently implemented functions and their variants.

taskSeq computation expressions

The taskSeq computation expression can be used just like using seq. On top of that, it adds support for working with tasks through let! and looping over a normal or asynchronous sequence (one that implements IAsyncEnumerable<'T>'). You can use yield! and yield and there's support for use and use!, try-with and try-finally and while loops within the task sequence expression.

Examples

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 module functions

We are working hard on getting a full set of module functions on TaskSeq that can be used with IAsyncEnumerable sequences. Our guide is the set of F# Seq functions in F# Core and, where applicable, the functions provided by AsyncSeq. Each implemented function is documented through XML doc comments to provide the necessary context-sensitive help.

This is what has been implemented so far, is planned or skipped:

Done Seq TaskSeq Variants Remarks
❓ allPairs allPairs note #1
✅ #81 append append
✅ #81 appendSeq
✅ #81 prependSeq
average average
averageBy averageBy averageByAsync
❓ cache cache note #1
✅ #67 cast cast
✅ #67 box
✅ #67 unbox
✅ #23 choose choose chooseAsync
chunkBySize chunkBySize
✅ #11 collect collect collectAsync
✅ #11 collectSeq collectSeqAsync
compareWith compareWith compareWithAsync
✅ #69 concat concat
✅ #70 contains contains
✅ #82 delay delay
distinct distinct
distinctBy dictinctBy distinctByAsync
✅ #2 empty empty
✅ #23 exactlyOne exactlyOne
✅ #83 except except
✅ #83 exceptOfSeq
✅ #70 exists exists existsAsync
exists2 exists2
✅ #23 filter filter filterAsync
✅ #23 find find findAsync
🚫 findBack note #2
✅ #68 findIndex findIndex findIndexAsync
🚫 findIndexBack n/a n/a note #2
✅ #2 fold fold foldAsync
fold2 fold2 fold2Async
🚫 foldBack note #2
🚫 foldBack2 note #2
forall forall forallAsync
forall2 forall2 forall2Async
❓ groupBy groupBy groupByAsync note #1
✅ #23 head head
✅ #68 indexed indexed
✅ #69 init init initAsync
✅ #69 initInfinite initInfinite initInfiniteAsync
insertAt insertAt
insertManyAt insertManyAt
✅ #23 isEmpty isEmpty
✅ #23 item item
✅ #2 iter iter iterAsync
iter2 iter2 iter2Async
✅ #2 iteri iteri iteriAsync
iteri2 iteri2 iteri2Async
✅ #23 last last
✅ #53 length length
✅ #53 lengthBy lengthByAsync
✅ #2 map map mapAsync
map2 map2 map2Async
map3 map3 map3Async
mapFold mapFold mapFoldAsync
🚫 mapFoldBack note #2
✅ #2 mapi mapi mapiAsync
mapi2 mapi2 mapi2Async
max max
maxBy maxBy maxByAsync
min min
minBy minBy minByAsync
✅ #2 ofArray ofArray
✅ #2 ofAsyncArray
✅ #2 ofAsyncList
✅ #2 ofAsyncSeq
✅ #2 ofList ofList
✅ #2 ofTaskList
✅ #2 ofResizeArray
✅ #2 ofSeq
✅ #2 ofTaskArray
✅ #2 ofTaskList
✅ #2 ofTaskSeq
pairwise pairwise
permute permute permuteAsync
✅ #23 pick pick pickAsync
🚫 readOnly note #3
reduce reduce reduceAsync
🚫 reduceBack note #2
removeAt removeAt
removeManyAt removeManyAt
replicate replicate
❓ rev note #1
scan scan scanAsync
🚫 scanBack note #2
✅ #90 singleton singleton
✅ #209 skip skip
✅ #209 drop
✅ #219 skipWhile skipWhile skipWhileAsync
✅ #219 skipWhileInclusive skipWhileInclusiveAsync
❓ sort note #1
❓ sortBy note #1
❓ sortByAscending note #1
❓ sortByDescending note #1
❓ sortWith note #1
splitInto splitInto
sum sum
sumBy sumBy sumByAsync
✅ #76 tail tail
✅ #209 take take
✅ #126 takeWhile takeWhile takeWhileAsync
✅ #126 takeWhileInclusive takeWhileInclusiveAsync
✅ #2 toArray toArray toArrayAsync
✅ #2 toIList toIListAsync
✅ #2 toList toList toListAsync
✅ #2 toResizeArray toResizeArrayAsync
✅ #2 toSeq toSeqAsync
[…]
❓ transpose note #1
✅ #209 truncate truncate
✅ #23 tryExactlyOne tryExactlyOne tryExactlyOneAsync
✅ #23 tryFind tryFind tryFindAsync
🚫 tryFindBack note #2
✅ #68 tryFindIndex tryFindIndex tryFindIndexAsync
🚫 tryFindIndexBack note #2
✅ #23 tryHead tryHead
✅ #23 tryItem tryItem
✅ #23 tryLast tryLast
✅ #23 tryPick tryPick tryPickAsync
✅ #76 tryTail
unfold unfold unfoldAsync
updateAt updateAt
✅ #217 where where whereAsync
windowed windowed
✅ #2 zip zip
zip3 zip3
zip4

Note 1

These functions require a form of pre-materializing through TaskSeq.cache, similar to the approach taken in the corresponding Seq functions. It doesn't make much sense to have a cached async sequence. However, AsyncSeq does implement these, so we'll probably do so eventually as well.

Note 2

Because of the async nature of TaskSeq sequences, iterating from the back would be bad practice. Instead, materialize the sequence to a list or array and then apply the xxxBack iterators.

Note 3

The motivation for readOnly in Seq is that a cast from a mutable array or list to a seq<_> is valid and can be cast back, leading to a mutable sequence. Since TaskSeq doesn't implement IEnumerable<_>, such casts are not possible.

More information

Further reading IAsyncEnumerable

  • A good C#-based introduction can be found in this blog.
  • An MSDN article written shortly after it was introduced.
  • Converting a seq to an IAsyncEnumerable demo gist as an example, though TaskSeq contains many more utility functions and uses a slightly different approach.
  • If you're looking for using IAsyncEnumerable with async and not task, the excellent AsyncSeq library should be used. While TaskSeq is intended to consume async just like task does, it won't create an AsyncSeq type (at least not yet). If you want classic Async and parallelism, you should get this library instead.

Further reading on resumable state machines

Further reading on computation expressions