FSharp.Control.TaskSeq 0.2.0

TaskSeq

An implementation of IAsyncEnumerable<'T> as a taskSeq CE for F# with accompanying TaskSeq module.

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, where each page is a MoveNextAsync call on the IAsyncEnumerator<'T> given by a call to GetAsyncEnumerator(). It has been relatively challenging to work properly with this type and dealing with each step being asynchronous, and the enumerator implementing IAsyncDisposable as well, which requires careful handling.

Table of contents

• Implementation progress
  • taskSeq CE
  • TaskSeq module functions
• More information
  • Futher reading IAsyncEnumerable
  • Futher reading on resumable state machines
  • Further reading on computation expressions

Implementation progress

As of 6 November 2022:

taskSeq CE

The resumable state machine backing the taskSeq CE is now finished and restartability (not to be confused with resumability) has been implemented and stabilized. Full support for empty task sequences is done. Focus is now on adding functionality there, like adding more useful overloads for yield and let!. Suggestions are welcome!

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 from AsyncSeq. Each implemented function is documented through XML doc comments to provide the necessary context-sensitive help.

The following is the progress report:

^{¹⁾ <a id="note1"></a>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.}
^{²⁾ <a id="note2"></a>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.}
^{³⁾ <a id="note3"></a>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

Futher 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.

Futher reading on resumable state machines

• A state machine from a monadic perspective in F# can be found here, which works with the pre-F# 6.0 non-resumable internals.
• The original RFC for F# 6.0 on resumable state machines
• The original RFC for introducing task to F# 6.0.
• A pre F# 6.0 TaskBuilder that motivated the task CE later added to F# Core.
• MSDN Documentation on task and async.

Further reading on computation expressions

• Docs on MSDN form a good summary and starting point.
• Arguably the best step-by-step tutorial to using and building computation expressions by Scott Wlaschin.