search

TheAngryByrd / IcedTasks

F# Cold Tasks and Cancellable Tasks
https://www.jimmybyrd.me/IcedTasks/
MIT License
120 stars 5 forks source link
async-await dotnet dotnet-core fsharp

readme

IcedTasks

What is IcedTasks?

This library contains additional computation expressions for the task CE utilizing the Resumable Code introduced in F# 6.0.

Differences at a glance

Computation Expression1 Library2 TFM3 Hot/Cold4 Multiple Awaits 5 Multi-start6 Tailcalls7 CancellationToken propagation8 Cancellation checks9 Parallel when using and!10 use IAsyncDisposable 11
F# Async FSharp.Core netstandard2.0 Cold Multiple multiple tailcalls implicit implicit No No
F# AsyncEx IcedTasks netstandard2.0 Cold Multiple multiple tailcalls implicit implicit No Yes
F# ParallelAsync IcedTasks netstandard2.0 Cold Multiple multiple tailcalls implicit implicit Yes No
F# Task/C# Task FSharp.Core netstandard2.0 Hot Multiple once-start no tailcalls explicit explicit No Yes
F# ValueTask IcedTasks netstandard2.0 Hot Once once-start no tailcalls explicit explicit Yes Yes
F# ColdTask IcedTasks netstandard2.0 Cold Multiple multiple no tailcalls explicit explicit Yes Yes
F# CancellableTask IcedTasks netstandard2.0 Cold Multiple multiple no tailcalls implicit implicit Yes Yes
F# CancellableValueTask IcedTasks netstandard2.0 Cold Once multiple no tailcalls implicit implicit Yes Yes

Why should I use this?

AsyncEx

AsyncEx is similar to Async except in the following ways:

  1. Allows use for IAsyncDisposable

    open IcedTasks
let fakeDisposable () = { new IAsyncDisposable with member __.DisposeAsync() = ValueTask.CompletedTask }

let myAsyncEx = asyncEx {
    use _ = fakeDisposable ()
    return 42
}

  2. Allows let!/do! against Tasks/ValueTasks/any Awaitable

    open IcedTasks
let myAsyncEx = asyncEx {
    let! _ = task { return 42 } // Task<T>
    let! _ = valueTask { return 42 } // ValueTask<T>
    let! _ = Task.Yield() // YieldAwaitable
    return 42
}

  3. When Tasks throw exceptions they will use the behavior described in Async.Await overload (esp. AwaitTask without throwing AggregateException

    let data = "lol"

let inner = asyncEx {
    do!
        task {
            do! Task.Yield()
            raise (ArgumentException "foo")
            return data
        }
        :> Task
}

let outer = asyncEx {
    try
        do! inner
        return ()
    with
    | :? ArgumentException ->
        // Should be this exception and not AggregationException
        return ()
    | ex ->
        return raise (Exception("Should not throw this type of exception", ex))
}

  4. Use IAsyncEnumerable with for keyword. This example uses TaskSeq but you can use any IAsyncEnumerable<T>.

    open IcedTasks
open FSharp.Control
let myAsyncEx = asyncEx {
    let items = taskSeq {  // IAsyncEnumerable<T>
        yield 42
        do! Task.Delay(100)
        yield 1701
    }
    let mutable sum = 0
    for i in items do
        sum <- sum + i
    return sum
}

For ValueTasks

open IcedTasks

let myValueTask = task {
    let! theAnswer = valueTask { return 42 }
    return theAnswer
}

For Cold & CancellableTasks

ColdTask

Short example:

open IcedTasks

let coldTask_dont_start_immediately = task {
    let mutable someValue = null
    let fooColdTask = coldTask { someValue <- 42 }
    do! Async.Sleep(100)
    // ColdTasks will not execute until they are called, similar to how Async works
    Expect.equal someValue null ""
    // Calling fooColdTask will start to execute it
    do! fooColdTask ()
    Expect.equal someValue 42 ""
}

CancellableTask & CancellableValueTask

The examples show cancellableTask but cancellableValueTask can be swapped in.

Accessing the context's CancellationToken:

  1. Binding against CancellationToken -> Task<_>

    let writeJunkToFile = 
    let path = Path.GetTempFileName()

    cancellableTask {
        let junk = Array.zeroCreate bufferSize
        use file = File.Create(path)

        for i = 1 to manyIterations do
            // You can do! directly against a function with the signature of `CancellationToken -> Task<_>` to access the context's `CancellationToken`. This is slightly more performant.
            do! fun ct -> file.WriteAsync(junk, 0, junk.Length, ct)
    }

  2. Binding against CancellableTask.getCancellationToken

    let writeJunkToFile = 
    let path = Path.GetTempFileName()

    cancellableTask {
        let junk = Array.zeroCreate bufferSize
        use file = File.Create(path)
        // You can bind against `CancellableTask.getCancellationToken` to get the current context's `CancellationToken`.
        let! ct = CancellableTask.getCancellationToken ()
        for i = 1 to manyIterations do
            do! file.WriteAsync(junk, 0, junk.Length, ct)
    }

Short example:

let executeWriting = task {
    // CancellableTask is an alias for `CancellationToken -> Task<_>` so we'll need to pass in a `CancellationToken`.
    // For this example we'll use a `CancellationTokenSource` but if you were using something like ASP.NET, passing in `httpContext.RequestAborted` would be appropriate.
    use cts = new CancellationTokenSource()
    // call writeJunkToFile from our previous example
    do! writeJunkToFile cts.Token
}

ParallelAsync

Short example:

open IcedTasks

let exampleHttpCall url = async {
    // Pretend we're executing an HttpClient call
    return 42
}

let getDataFromAFewSites = parallelAsync {
    let! result1 = exampleHttpCall "howManyPlantsDoIOwn"
    and! result2 = exampleHttpCall "whatsTheTemperature"
    and! result3 = exampleHttpCall "whereIsMyPhone"

    // Do something meaningful with results
    return ()
}

Builds

GitHub Actions
GitHub Actions
Build History

NuGet

Package Stable Prerelease
IcedTasks NuGet Badge NuGet Badge

Developing

Make sure the following requirements are installed on your system:

or

Environment Variables

Building

> build.cmd <optional buildtarget> // on windows
$ ./build.sh  <optional buildtarget>// on unix

The bin of your library should look similar to:

$ tree src/MyCoolNewLib/bin/
src/MyCoolNewLib/bin/
└── Debug
    └── net50
        ├── MyCoolNewLib.deps.json
        ├── MyCoolNewLib.dll
        ├── MyCoolNewLib.pdb
        └── MyCoolNewLib.xml

Build Targets

Releasing

git add .
git commit -m "Scaffold"
git remote add origin https://github.com/user/MyCoolNewLib.git
git push -u origin master

NOTE: Its highly recommend to add a link to the Pull Request next to the release note that it affects. The reason for this is when the RELEASE target is run, it will add these new notes into the body of git commit. GitHub will notice the links and will update the Pull Request with what commit referenced it saying "added a commit that referenced this pull request". Since the build script automates the commit message, it will say "Bump Version to x.y.z". The benefit of this is when users goto a Pull Request, it will be clear when and which version those code changes released. Also when reading the CHANGELOG, if someone is curious about how or why those changes were made, they can easily discover the work and discussions.

Here's an example of adding an "Unreleased" section to a CHANGELOG.md with a 0.1.0 section already released.

## [Unreleased]

### Added
- Does cool stuff!

### Fixed
- Fixes that silly oversight

## [0.1.0] - 2017-03-17
First release

### Added
- This release already has lots of features

[Unreleased]: https://github.com/user/MyCoolNewLib.git/compare/v0.1.0...HEAD
[0.1.0]: https://github.com/user/MyCoolNewLib.git/releases/tag/v0.1.0

macOS/Linux Parameter:

./build.sh Release 0.2.0

macOS/Linux Environment Variable:

RELEASE_VERSION=0.2.0 ./build.sh Release