Add let! and do! support for F# async / Async<'T>

[abelbraaksma]

Fixes: #79

This introduces async support similar to how task supports async through let-bang and do-bang.

---

Original PR contained the following, which has been moved to #132 and #133.

I'm not certain whether or not to allow this (creative?) approach of setting a CancellationToken.

Basically, if we'd merge this, setting a CancellationToken can be done as follows:

let f() =
    let tokenSource = CancellationTokenSource(500)
    taskSeq {
        do! tokenSource.Token // this sets the token for this taskSeq
        do! Task.Delay 300
        do! Task.Delay 300
        do! Task.Delay 300
    }

@dsyme, what do you think? In a way I think it is smoother than adding overloads to all the TaskSeq.XXX functions to take a cancellation token. Alternatively, of course, I could just have a TaskSeq.setCancellationToken method. However, the above way is very flexible.

The relatively simple way this is done is as follows:

member inline _.Bind(myToken: CancellationToken, continuation: (unit -> TaskSeqCode<'T>)) : TaskSeqCode<'T> =
    TaskSeqCode<'T>(fun sm ->
        sm.Data.cancellationToken <- myToken
        (continuation ()).Invoke(&sm))

Which may also be a way to allow cancellation tokens to be passed through in tasks (but, it adds overhead).

[abelbraaksma]

/cc @dsyme what do you think?

[abelbraaksma]

@bartelink would you have an informed opinion on this method of setting the cancellation token?

[bartelink]

I'm at the lower end of the 'informed' spectrum on this, but won't let that stop me opining...

People could cope with this, and it's obviously terse. It's also arguably a dual to the do! fun ct -> ... construct in IcedTasks.

But, to my eyes, it's not terribly searchable or scannable in the same way that e.g. Async.CancellationToken clearly is; it took me a few takes to grok it on first glance when I first saw it. Hence I'd personally go for a TaskSeq.setCancellationToken API over supporting this.

---

However, this also begs questions like - would you ever want to setCT more than once? I can't think of any case where I'd only become aware of/generate the CT other than immediately when starting a Task?

Is there any way the CT can become an argument to the builder? e.g. if the code could become taskSeqCt tokenSource.Token {, that would convey the intent (it's at its heart a cancellableTask) more clearly, and generally align with the convention of supplying a ct argument whenever a Task is being kicked off. While that name/letter sequence is probably a tough sell, it is searchable and easy to scan.

Even if there was still a get out of jail card in the form of a TaskSeq.setCancellationToken API, one could validate correct flowing of CTs in a given codebase by looking for either taskSeqCt, or taskSeq + TaskSeq.setCancellationToken pairs.

---

for posterity, answers & follow up discussion: see #133.

[abelbraaksma]

Hence I'd personally go for a TaskSeq.setCancellationToken API over supporting this.

that’d most certainly be added as well. All CE methods are also supported in point free style.

[gusty]

Why not using a CE Custom Operator for that ?

[abelbraaksma]

Why not using a CE Custom Operator for that ?

EDIT: continued in PR #132.

@gusty That would be my preference. Less magic, more explicitness. But last time I tried to mix "default" (yield!/let! etc) styles with ones that have custom operators, it all fell apart (but, to be fair, that was trying to add let!/do! behavior into something that only had custom operations, i.e. the other way around and I probably just screwed something up).

I didn't try it this time around, I'll give it a go.

EDIT: tried it, failed it. I probably do something wrong here. Since there's zero docs on custom operations (apart from a few lines of explanatory text) I always have to figure it out by just trying.

It compiles fine, but when I use cancellationToken it says that cancellationToken is not defined:

        [<CustomOperation("cancellationToken")>]
        member inline _.SetCancellationToken(myToken: CancellationToken, continuation: (unit -> ResumableTSC<'T>)) : ResumableTSC<'T> =
            ResumableTSC<'T>(fun sm ->
                sm.Data.cancellationToken <- myToken
                (continuation ()).Invoke(&sm))

This does not compile:

taskSeq {
    cancellationToken (CancellationToken())
    yield! [ 1..10 ]
 }

It's also unfortunate that you need the extra parentheses...

@gusty do you know if this can be fixed or is this a limitation of the language? Or perhaps a limitation of trying custom operations with resumable code?

EDIT: see #132.

[abelbraaksma]

I shouldn't have conflated adding these two features in one PR. So I'm gonna split this up:

• Issue for discussing cancellations: Add better support for cancellation tokens passing #133.
• PR to experiment on implementations (and showing my current problem with @gusty's suggestion): Add cancellation support (experimental!) #132.

I've addressed the relevant questions there.

Will continue this one with just the simple task of adding async support.

[abelbraaksma]

This will be published as part of 0.4.0.