Given a Resource, possibly built by composing multiple Resources monadically, returns the acquired resource, as well as an action that runs all the finalizers for releasing it.

If the outer F fails or is interrupted, allocated guarantees that the finalizers will be called. However, if the outer F succeeds, it's up to the user to ensure the returned F[Unit] is called once A needs to be released. If the returned F[Unit] is not called, the finalizers will not be run.

For this reason, this is an advanced and potentially unsafe api which can cause a resource leak if not used correctly, please prefer use as the standard way of running a Resource program.

Use cases include interacting with side-effectful apis that expect separate acquire and release actions (like the before and after methods of many test frameworks), or complex library code that needs to modify or move the finalizer for an existing resource.

Given a Resource, possibly built by composing multiple Resources monadically, returns the acquired resource, as well as a cleanup function that takes an exit case and runs all the finalizers for releasing it.

If the outer F fails or is interrupted, allocated guarantees that the finalizers will be called. However, if the outer F succeeds, it's up to the user to ensure the returned ExitCode => F[Unit] is called once A needs to be released. If the returned ExitCode => F[Unit] is not called, the finalizers will not be run.

For this reason, this is an advanced and potentially unsafe api which can cause a resource leak if not used correctly, please prefer use as the standard way of running a Resource program.

Use cases include interacting with side-effectful apis that expect separate acquire and release actions (like the before and after methods of many test frameworks), or complex library code that needs to modify or move the finalizer for an existing resource.

Allocates two resources concurrently, and combines their results in a tuple.

The finalizers for the two resources are also run concurrently with each other, but within _each_ of the two resources, nested finalizers are run in the usual reverse order of acquisition.

The same Resource.ExitCase is propagated to every finalizer. If both resources acquired successfully, the Resource.ExitCase is determined by the outcome of use. Otherwise, it is determined by which resource failed or canceled first during acquisition.

Note that Resource also comes with a cats.Parallel instance that offers more convenient access to the same functionality as both, for example via parMapN:

import scala.concurrent.duration._
import cats.effect.{IO, Resource}
import cats.effect.std.Random
import cats.syntax.all._

def mkResource(name: String) = {
  val acquire = for {
    n <- Random.scalaUtilRandom[IO].flatMap(_.nextIntBounded(1000))
    _ <- IO.sleep(n.millis)
    _ <- IO.println(s"Acquiring $$name")
  } yield name

  def release(name: String) =
    IO.println(s"Releasing $$name")

  Resource.make(acquire)(release)
}

val r = (mkResource("one"), mkResource("two"))
  .parMapN((s1, s2) => s"I have $s1 and $s2")
  .use(IO.println(_))

Applies an effectful transformation to the allocated resource. Like a flatMap on F[A] while maintaining the resource context

Applies an effectful transformation to the allocated resource. Like a flatTap on F[A] while maintaining the resource context

Given a mapping function, transforms the resource provided by this Resource.

This is the standard Functor.map.

Given a natural transformation from F to G, transforms this Resource from effect F to effect G. The F and G constraint can also be satisfied by requiring a MonadCancelThrow[F] and MonadCancelThrow[G].

A Resource where the acquire step is done lazily and memoized. This means that acquire happens only if and when the F[A] value is executed, instead of happening immediately upon use(). If the F[A] value is executed multiple times, acquire happens once only and the acquired resource is shared to all callers. The resource is released as normal at the end of use (whether normal termination, error, or cancelled), if it was acquired.

Runs finalizer when this resource is closed. Unlike the release action passed to Resource.make, this will run even if resource acquisition fails or is canceled.

Allocates a resource and supplies it to the given function. The resource is released as soon as the resulting F[B] is completed, whether normally or as a raised error.

Allocates a resource with a non-terminating use action. Useful to run programs that are expressed entirely in Resource.

The finalisers run when the resulting program fails or gets interrupted.