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. A fiber is canceled when it observes a cancelation request before it completes. 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 the observation of cancelation until the fiber is unmasked, which is achieved via uncancelable. If a fiber would be 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 will be canceled if it has not already completed.

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

F.uncancelable { poll =>
  // can only be canceled immediately before `fb` is executed, or between combinators in `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 cancelation boundary is a boundary where the cancelation status of a fiber may be checked and hence canceled. Cancelation is advisory. It does not have to be checked at every boundary, so it is possible for a fiber to complete after cancelation has been requested, but before it is observed.

In general they are introduced before each of the combinators from the Cats/Cats Effect hierarchy (map, flatMap, handleErrorWith, attempt, etc). Typeclasses which extend MonadCancel may introduce additional cancelation boundaries with their combinators. Importantly, there will never be a cancelation boundary after a combinator, as this would allow cancelation between the end of a poll and the next action, losing the result of the polled operation.

Outside uncancelable cancelation may be observed at any cancelation boundary:

/* boundary */
fa
  .flatMap(f)
  /* boundary */
  .handleErrorWith(g)
  /* boundary */
  .map(h)

If cancelation of the fiber above is requested then the cancelation status may be checked and the execution terminated before each combinator is executed, or it may not be observed at all before the fiber completes.

Inside uncancelable, the observation of cancelation at boundaries outside of poll is suppressed. This is the definition of masking as above.

/* boundary */
F.uncancelable( poll =>
  fa
    .flatMap(f)
    .poll(/* boundary */g)
    .handleErrorWith(h)
    .map(i)
)

The only points above where cancelation can be observed are:

1. before the uncancelable block
2. the boundary before g is executed inside poll
3. between any combinators that g is composed of.

Since uncancelable regions compose, if uncancelable is called within g, the observation of cancelation will again be suppressed until after that block. Cancelation will not be observed after g completes

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.

Law Violations

Because cancelation may be checked before each combinator, MonadCancel introduces a subtle violation of identity functor law that fa.map(identity) <-> fa. For example, in:

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

cancelation may be observed before the execution of map on the right-hand side, causing the onCancel combinator to never be registered. The monad right identity law, and other similar laws that allow the insertion of a combinator are similarly violated. The justification is that cancelation is a hint rather than a mandate and so enshrining its behaviour in laws will always be awkward.