An effect that requests self-cancelation on the current fiber.

canceled has a return type of F[Unit] instead of F[Nothing] due to execution continuing in a masked region. In the following example, the fiber requests self-cancelation in a masked region, so cancelation is suppressed until the fiber is completely unmasked. fa will run but fb will not. If canceled had a return type of F[Nothing], then it would not be possible to continue execution to fa (there would be no Nothing value to pass to the flatMap).

F.uncancelable { _ =>
  F.canceled *> fa
} *> fb

Introduces a fairness boundary that yields control back to the scheduler of the runtime system. This allows the carrier thread to resume execution of another waiting fiber.

This function is primarily useful when performing long-running computation that is outside of the monadic context. For example:

fa.map(data => expensiveWork(data))

In the above, we're assuming that expensiveWork is a function which is entirely compute-bound but very long-running. A good rule of thumb is to consider a function "expensive" when its runtime is around three or more orders of magnitude higher than the overhead of the map function itself (which runs in around 5 nanoseconds on modern hardware). Thus, any expensiveWork function which requires around 10 microseconds or longer to execute should be considered "long-running".

The danger is that these types of long-running actions outside of the monadic context can result in degraded fairness properties. The solution is to add an explicit cede both before and after the expensive operation:

(fa <* F.cede).map(data => expensiveWork(data)).guarantee(F.cede)

Note that extremely long-running expensiveWork functions can still cause fairness issues, even when used with cede. This problem is somewhat fundamental to the nature of scheduling such computation on carrier threads. Whenever possible, it is best to break apart any such functions into multiple pieces invoked independently (e.g. via chained map calls) whenever the execution time exceeds five or six orders of magnitude beyond the overhead of map itself (around 1 millisecond on most hardware).

Note that cede is merely a hint to the runtime system; implementations have the liberty to interpret this method to their liking as long as it obeys the respective laws. For example, a lawful, but atypical, implementation of this function is F.unit, in which case the fairness boundary is a no-op.

Analogous to productR, but suppresses short-circuiting behavior except for cancelation.

A non-terminating effect that never completes, which causes a fiber to semantically block indefinitely. This is the purely functional, asynchronous equivalent of an infinite while loop in Java, but no native threads are blocked.

A fiber that is suspended in never can be canceled if it is completely unmasked before it suspends:

// ignoring race conditions between `start` and `cancel`
F.never.start.flatMap(_.cancel) <-> F.unit

However, if the fiber is masked, cancellers will be semantically blocked forever:

// ignoring race conditions between `start` and `cancel`
F.uncancelable(_ => F.never).start.flatMap(_.cancel) <-> F.never

Registers a finalizer that is invoked if cancelation is observed during the evaluation of fa. If the evaluation of fa completes without encountering a cancelation, the finalizer is unregistered before proceeding.

Note that if fa is uncancelable (e.g. created via uncancelable) then fin won't be fired.

F.onCancel(F.uncancelable(_ => F.canceled), fin) <-> F.unit

During finalization, all actively registered finalizers are run exactly once. The order by which finalizers are run is dictated by nesting: innermost finalizers are run before outermost finalizers. For example, in the following program, the finalizer f1 is run before the finalizer f2:

F.onCancel(F.onCancel(F.canceled, f1), f2)

If a finalizer throws an error during evaluation, the error is suppressed, and implementations may choose to report it via a side channel. Finalizers are always uncancelable, so cannot otherwise be interrupted.

A low-level primitive for racing the evaluation of two fibers that returns the Outcome of the winner and the Fiber of the loser. The winner of the race is considered to be the first fiber that completes with an outcome.

racePair is a cancelation-unsafe function; it is recommended to use the safer variants.

A low-level primitive for starting the concurrent evaluation of a fiber. Returns a Fiber that can be used to wait for a fiber or cancel it.

start is a cancelation-unsafe function; it is recommended to use the safer variant, background, to spawn fibers.

Masks cancelation on the current fiber. The argument to body of type Poll[F] is a natural transformation F ~> F that enables polling. Polling causes a fiber to unmask within a masked region so that cancelation can be observed again.

In the following example, cancelation can be observed only within fb and nowhere else:

F.uncancelable { poll =>
  fa *> poll(fb) *> fc
}

If a fiber is canceled while it is masked, the cancelation is suppressed for as long as the fiber remains masked. Whenever the fiber is completely unmasked again, the cancelation will be respected.

Masks can also be stacked or nested within each other. If multiple masks are active, all masks must be undone so that cancelation can be observed. In order to completely unmask within a multi-masked region the poll corresponding to each mask must be applied to the effect, outermost-first.

F.uncancelable { p1 =>
  F.uncancelable { p2 =>
    fa *> p2(p1(fb)) *> fc
  }
}

The following operations are no-ops:

1. Polling in the wrong order
2. Subsequent polls when applying the same poll more than once: poll(poll(fa)) is equivalent to poll(fa)
3. Applying a poll bound to one fiber within another fiber

Returns a Resource that manages the concurrent execution of a fiber. The inner effect can be used to wait on the outcome of the child fiber; it is effectively a join.

The child fiber is canceled in two cases: either the resource goes out of scope or the parent fiber is canceled. If the child fiber terminates before one of these cases occurs, then cancelation is a no-op. This avoids fiber leaks because the child fiber is always canceled before the parent fiber drops the reference to it.

// Starts a fiber that continously prints "A".
// After 10 seconds, the resource scope exits so the fiber is canceled.
F.background(F.delay(println("A")).foreverM).use { _ =>
  F.sleep(10.seconds)
}

Races the evaluation of two fibers and returns the result of both.

The following rules describe the semantics of both:

1. If the winner completes with Outcome.Succeeded, the race waits for the loser to complete. 2. If the winner completes with Outcome.Errored, the race raises the error. The loser is canceled. 3. If the winner completes with Outcome.Canceled, the loser and the race are canceled as well. 4. If the loser completes with Outcome.Succeeded, the race returns the successful value of both fibers. 5. If the loser completes with Outcome.Errored, the race returns the error. 6. If the loser completes with Outcome.Canceled, the race is canceled. 7. If the race is canceled before one or both participants complete, then whichever ones are incomplete are canceled. 8. If the race is masked and is canceled because one or both participants canceled, the fiber will block indefinitely.

Races the evaluation of two fibers and returns the Outcome of both. If the race is canceled before one or both participants complete, then then whichever ones are incomplete are canceled.

A pattern for safely interacting with effectful lifecycles.

If acquire completes successfully, use is called. If use succeeds, fails, or is canceled, release is guaranteed to be called exactly once.

acquire is uncancelable. release is uncancelable. use is cancelable by default, but can be masked.

A pattern for safely interacting with effectful lifecycles.

If acquire completes successfully, use is called. If use succeeds, fails, or is canceled, release is guaranteed to be called exactly once.

acquire is uncancelable. release is uncancelable. use is cancelable by default, but can be masked.

A pattern for safely interacting with effectful lifecycles.

If acquire completes successfully, use is called. If use succeeds, fails, or is canceled, release is guaranteed to be called exactly once.

If use succeeds the returned value B is returned. If use returns an exception, the exception is returned.

acquire is uncancelable by default, but can be unmasked. release is uncancelable. use is cancelable by default, but can be masked.

Given an effect which might be uncancelable and a finalizer, produce an effect which can be canceled by running the finalizer. This combinator is useful for handling scenarios in which an effect is inherently uncancelable but may be canceled through setting some external state. A trivial example of this might be the following (assuming an Async instance):

val flag = new AtomicBoolean(false)
val fa = F blocking {
  while (!flag.get()) {
    Thread.sleep(10)
  }
}

F.cancelable(fa, F.delay(flag.set(true)))

Without cancelable, effects constructed by blocking, delay, and similar are inherently uncancelable. Simply adding an onCancel to such effects is insufficient to resolve this, despite the fact that under *some* circumstances (such as the above), it is possible to enrich an otherwise-uncancelable effect with early termination. cancelable addresses this use-case.

Note that there is no free lunch here. If an effect truly cannot be prematurely terminated, cancelable will not allow for cancelation. As an example, if you attempt to cancel uncancelable(_ => never), the cancelation will hang forever (in other words, it will be itself equivalent to never). Applying cancelable will not change this in any way. Thus, attempting to cancel cancelable(uncancelable(_ => never), unit) will also hang forever. As in all cases, cancelation will only return when all finalizers have run and the fiber has fully terminated.

If fa self-cancels and the cancelable itself is uncancelable, the resulting fiber will be equal to never (similar to race). Under normal circumstances, if fa self-cancels, that cancelation will be propagated to the calling context.

Specifies an effect that is always invoked after evaluation of fa completes, regardless of the outcome.

This function can be thought of as a combination of flatTap, onError, and onCancel.

Specifies an effect that is always invoked after evaluation of fa completes, but depends on the outcome.

This function can be thought of as a combination of flatTap, onError, and onCancel.