blob: 4eabe0c9bfd07a6d83eee267f3db695e7b53b064 [file]
/-
Copyright (c) 2025 Lean FRO, LLC. All rights reserved.
Released under Apache 2.0 license as described in the file LICENSE.
Authors: Sofia Rodrigues
-/
module
prelude
public import Std.Internal.UV
public import Std.Internal.Async.Timer
public import Std.Sync.CancellationContext
public section
/-!
This module contains the implementation of `ContextAsync`, a monad for asynchronous computations with
cooperative cancellation support that must be explicitly checked for and cancelled explicitly.
-/
namespace Std
namespace Internal
namespace IO
namespace Async
/--
An asynchronous computation with cooperative cancellation support via a `CancellationContext`. `ContextAsync α`
is equivalent to `ReaderT CancellationContext Async α`, providing a `CancellationContext` value to async
computations.
-/
abbrev ContextAsync (α : Type) := ReaderT CancellationContext Async α
namespace ContextAsync
/--
Runs a `ContextAsync` computation with a given context. See also `ContextAsync.run` for running with a new
context that automatically cancels after execution.
-/
@[inline]
protected def runIn (ctx : CancellationContext) (x : ContextAsync α) : Async α :=
x ctx
/--
Runs a `ContextAsync` computation with a new context that cancels after the execution of the computation.
See also `ContextAsync.runIn` for running with an existing context.
-/
@[inline]
protected def run (x : ContextAsync α) : Async α := do
let ctx ← CancellationContext.new
x ctx <* ctx.cancel .cancel
/--
Returns the current context for inspection or to pass to other functions.
-/
@[inline]
def getContext : ContextAsync CancellationContext :=
fun ctx => pure ctx
/--
Checks if the current context is cancelled. Returns `true` if the context (or any ancestor) has been cancelled.
Long-running operations should periodically check this and exit gracefully when cancelled.
-/
@[inline]
def isCancelled : ContextAsync Bool := do
let ctx ← getContext
ctx.isCancelled
/--
Gets the cancellation reason if the context is cancelled. Returns `some reason` if cancelled, `none` otherwise,
allowing you to distinguish between different cancellation types.
-/
@[inline]
def getCancellationReason : ContextAsync (Option CancellationReason) := do
let ctx ← getContext
ctx.getCancellationReason
/--
Cancels the current context with the given reason, cascading to all child contexts.
Cancellation is cooperative, operations must explicitly check `isCancelled` or use `awaitCancellation` to respond.
-/
@[inline]
def cancel (reason : CancellationReason) : ContextAsync Unit := do
let ctx ← getContext
ctx.cancel reason
/--
Returns a selector that completes when the current context is cancelled.
-/
@[inline]
def doneSelector : ContextAsync (Selector Unit) := do
let ctx ← getContext
return ctx.doneSelector
/--
Waits for the current context to be cancelled.
-/
@[inline]
def awaitCancellation : ContextAsync Unit := do
let ctx ← getContext
let task ← ctx.done
await task
/--
Runs two computations concurrently and returns both results. Each computation runs in its own child context;
if either fails or is cancelled, both are cancelled immediately and the exception is propagated.
-/
@[inline, specialize]
def concurrently (x : ContextAsync α) (y : ContextAsync β)
(prio := Task.Priority.default) : ContextAsync (α × β) := do
let ctx ← getContext
let concurrentCtx ← ctx.fork
let childCtx1 ← concurrentCtx.fork
let childCtx2 ← concurrentCtx.fork
let result ← Async.concurrently
(try x childCtx1 catch err => do concurrentCtx.cancel .cancel; throw err finally childCtx1.cancel .cancel)
(try y childCtx2 catch err => do concurrentCtx.cancel .cancel; throw err finally childCtx2.cancel .cancel)
prio
concurrentCtx.cancel .cancel
return result
/--
Runs two computations concurrently and returns the result of the first to complete. Each computation runs
in its own child context; when either completes, the other is cancelled immediately.
-/
@[inline, specialize]
def race [Inhabited α] (x : ContextAsync α) (y : ContextAsync α)
(prio := Task.Priority.default) : ContextAsync α := do
let parent ← getContext
let ctx1 ← CancellationContext.fork parent
let ctx2 ← CancellationContext.fork parent
let task1 ← async (x ctx1) prio
let task2 ← async (y ctx2) prio
let result ← Async.race
(await task1 <* ctx2.cancel .cancel)
(await task2 <* ctx1.cancel .cancel)
prio
pure result
/--
Runs all computations concurrently and collects results in the same order. Each runs in its own child context;
if any computation fails, all others are cancelled and the exception is propagated.
-/
@[inline, specialize]
def concurrentlyAll (xs : Array (ContextAsync α))
(prio := Task.Priority.default) : ContextAsync (Array α) := do
let ctx ← getContext
let concurrentCtx ← ctx.fork
let tasks : Array (AsyncTask α) ← xs.mapM fun ctxAsync => do
let childCtx ← concurrentCtx.fork
async (prio := prio)
(try
ctxAsync childCtx
catch err => do
concurrentCtx.cancel .cancel
throw err
finally
childCtx.cancel .cancel)
let result ← tasks.mapM await
return result
/--
Launches a `ContextAsync` computation in the background, discarding its result.
The computation runs independently in the background in its own child context. The parent computation does not wait
for background tasks to complete. This means that if the parent finishes its execution it will cause
the cancellation of the background functions. See also `disown` for launching tasks that continue independently
even after parent cancellation.
-/
@[inline, specialize]
def background (action : ContextAsync α) (prio := Task.Priority.default) : ContextAsync Unit := do
let ctx ← getContext
let childCtx ← ctx.fork
Async.background (action childCtx *> childCtx.cancel .cancel) prio
/--
Launches a `ContextAsync` computation in the background, discarding its result. It's similar to `background`,
but the child context is not automatically cancelled when the action completes. This allows the disowned
computation to continue running independently, even if the parent context is cancelled. The child context
will remain alive as long as the computation needs it. See also `background` for launching tasks that are
cancelled when the parent finishes.
-/
@[inline, specialize]
def disown (action : ContextAsync α) (prio := Task.Priority.default) : ContextAsync Unit := do
let childCtx ← CancellationContext.new
Async.background (action childCtx) prio
/--
Runs all computations concurrently and returns the first result. Each computation runs in its own child context;
when the first completes successfully, all others are cancelled immediately.
-/
def raceAll [ForM ContextAsync c (ContextAsync α)] (xs : c)
(prio := Task.Priority.default) : ContextAsync α := do
let parent ← getContext
let promise ← IO.Promise.new
ForM.forM xs fun x => do
let ctx ← CancellationContext.fork parent
let task ← async (x ctx) prio
background do
try
let result ← await task
promise.resolve (.ok result)
catch e =>
discard $ promise.resolve (.error e)
let result ← await promise
parent.cancel .cancel
Async.ofExcept result
/--
Launches a `ContextAsync` computation as an asynchronous task with a forked child context.
The child context is automatically cancelled when the task completes or fails.
-/
@[inline, specialize]
def async (x : ContextAsync α) (prio := Task.Priority.default) : ContextAsync (AsyncTask α) :=
fun ctx => do
let childCtx ← ctx.fork
Async.async (try x childCtx finally childCtx.cancel .cancel) prio
instance : MonadAsync AsyncTask ContextAsync where
async x prio := ContextAsync.async x prio
instance : Functor ContextAsync where
map f x := fun ctx => f <$> x ctx
instance : Monad ContextAsync where
pure a := fun _ => pure a
bind x f := fun ctx => x ctx >>= fun a => f a ctx
instance : MonadLift IO ContextAsync where
monadLift x := fun _ => Async.ofIOTask (Task.pure <$> x)
instance : MonadLift BaseIO ContextAsync where
monadLift x := fun _ => liftM (m := Async) x
instance : MonadExcept IO.Error ContextAsync where
throw e := fun _ => throw e
tryCatch x h := fun ctx => tryCatch (x ctx) (fun e => h e ctx)
instance : MonadFinally ContextAsync where
tryFinally' x f := fun ctx =>
tryFinally' (x ctx) (fun opt => f opt ctx)
instance [Inhabited α] : Inhabited (ContextAsync α) where
default := fun _ => default
instance : MonadAwait AsyncTask ContextAsync where
await t := fun _ => await t
end ContextAsync
/--
Returns a selector that completes when the current context is cancelled.
This is useful for selecting on cancellation alongside other asynchronous operations.
-/
def Selector.cancelled : ContextAsync (Selector Unit) := do
ContextAsync.doneSelector
end Async
end IO
end Internal
end Std