A typeclass that characterizes monads which support safe cancelation, masking, and finalization. MonadCancel extends the capabilities of cats.MonadError, so an instance of this typeclass must also provide a lawful instance for cats.MonadError.

Fibers

A fiber is a sequence of effects which are bound together by flatMap. The execution of a fiber of an effect F[E, A] terminates with one of three outcomes, which are encoded by the datatype Outcome:

1. Outcome.Succeeded: indicates success with a value of type A
2. Outcome.Errored: indicates failure with a value of type E
3. Outcome.Canceled: indicates abnormal termination

Additionally, a fiber may never produce an outcome, in which case it is said to be non-terminating.

Cancelation

Cancelation refers to the act of requesting that the execution of a fiber be abnormally terminated. MonadCancel exposes a means of self-cancelation, with which a fiber can request that its own execution be terminated. Self-cancelation is achieved via canceled.

Cancelation is vaguely similar to the short-circuiting behavior introduced by cats.MonadError, but there are several key differences:

1. Cancelation is effective; if it is observed it must be respected, and it cannot be reversed. In contrast, handleError exposes the ability to catch and recover from errors, and then proceed with normal execution.
2. Cancelation can be masked via MonadCancel!.uncancelable. Masking is discussed in the next section.
3. GenSpawn introduces external cancelation, another cancelation mechanism by which fibers can be canceled by external parties.

Masking

Masking allows a fiber to suppress cancelation for a period of time, which is achieved via uncancelable. If a fiber is canceled while it is masked, the cancelation is suppressed for as long as the fiber remains masked. Once the fiber reaches a completely unmasked state, it responds to the cancelation.

While a fiber is masked, it may optionally unmask by "polling", rendering itself cancelable again.

F.uncancelable { poll =>
  // can only observe cancelation within `fb`
  fa *> poll(fb) *> fc
}

These semantics allow users to precisely mark what regions of code are cancelable within a larger code block.

Cancelation Boundaries

A boundary corresponds to an iteration of the internal runloop. In general they are introduced by any of the combinators from the cats/cats effect hierarchy (map, flatMap, handleErrorWith, attempt, etc).

A cancelation boundary is a boundary where the cancelation status of a fiber may be checked and hence cancelation observed. Note that in general you cannot guarantee that cancelation will be observed at a given boundary. However, in the absence of masking it will be observed eventually.

With a small number of exceptions covered below, all boundaries are cancelable boundaries ie cancelation may be observed before the invocation of any combinator.

fa
  .flatMap(f)
  .handleErrorWith(g)
  .map(h)

If the fiber above is canceled then the cancelation status may be checked and the execution terminated between any of the combinators.

As noted above, there are some boundaries which are not cancelable boundaries:

1. Any boundary inside uncancelable and not inside poll. This is the definition of masking as above.

F.uncancelable( _ =>
  fa
    .flatMap(f)
    .handleErrorWith(g)
    .map(h)
)

None of the boundaries above are cancelation boundaries as cancelation is masked.

2. The boundary after uncancelable

F.uncancelable(poll => foo(poll)).flatMap(f)

It is guaranteed that we will not observe cancelation after uncancelable and hence flatMap(f) will be invoked. This is necessary for uncancelable to compose. Consider for example Resource#allocated

def allocated[B >: A](implicit F: MonadCancel[F, Throwable]): F[(B, F[Unit])]

which returns a tuple of the resource and a finalizer which needs to be invoked to clean-up once the resource is no longer needed. The implementation of allocated can make sure it is safe by appropriate use of uncancelable. However, if it were possible to observe cancelation on the boundary directly after allocated then we would have a leak as the caller would be unable to ensure that the finalizer is invoked. In other words, the safety of allocated and the safety of f would not guarantee the safety of the composition allocated.flatMap(f).

This does however mean that we violate the functor law that fa.map(identity) <-> fa as

F.uncancelable(_ => fa).onCancel(fin)  <-!-> F.uncancelable(_ => fa).map(identity).onCancel(fin)

as cancelation may be observed before the onCancel on the RHS. The justification is that cancelation is a hint rather than a mandate and so enshrining its behaviour in laws will always be awkward. Given this, it is better to pick a semantic that allows safe composition of regions.

3. The boundary after poll

F.uncancelable(poll => poll(fa).flatMap(f))

If fa completes successfully then cancelation may not be observed after poll but before flatMap. The reasoning is similar to above - if fa has successfully produced a value then the caller should have the opportunity to observe the value and ensure finalizers are in-place, etc.

Finalization

Finalization refers to the act of running finalizers in response to a cancelation. Finalizers are those effects whose evaluation is guaranteed in the event of cancelation. After a fiber has completed finalization, it terminates with an outcome of Canceled.

Finalizers can be registered to a fiber for the duration of some effect via onCancel. If a fiber is canceled while running that effect, the registered finalizer is guaranteed to be run before terminating.

Bracket pattern

The aforementioned concepts work together to unlock a powerful pattern for safely interacting with effectful lifecycles: the bracket pattern. This is analogous to the try-with-resources/finally construct in Java.

A lifecycle refers to a pair of actions, which are called the acquisition action and the release action respectively. The relationship between these two actions is that if the former completes successfully, then the latter is guaranteed to be run eventually, even in the presence of errors and cancelation. While the lifecycle is active, other work can be performed, but this invariant is always respected.

The bracket pattern is an invaluable tool for safely handling resource lifecycles. Imagine an application that opens network connections to a database server to do work. If a task in the application is canceled while it holds an open database connection, the connection would never be released or returned to a pool, causing a resource leak.

To illustrate the compositional nature of MonadCancel and its combinators, the implementation of bracket is shown below:

def bracket[A, B](acquire: F[A])(use: A => F[B])(release: A => F[Unit]): F[B] =
  uncancelable { poll =>
    flatMap(acquire) { a =>
      val finalized = onCancel(poll(use(a)), release(a).uncancelable)
      val handled = onError(finalized) { case e => void(attempt(release(a).uncancelable)) }
      flatMap(handled)(b => as(attempt(release(a).uncancelable), b))
    }
  }

See bracketCase and bracketFull for other variants of the bracket pattern. If more specialized behavior is necessary, it is recommended to use uncancelable and onCancel directly.