Resource

sealed abstract class Resource[+F[_], +A] extends ResourceLike[F, A]

The Resource is a data structure that captures the effectful allocation of a resource, along with its finalizer.

This can be used to wrap expensive resources. Example:

 def open(file: File): Resource[IO, BufferedReader] =
   Resource(IO {
     val in = new BufferedReader(new FileReader(file))
     (in, IO(in.close()))
   })

Usage is done via use and note that resource usage nests, because its implementation is specified in terms of Bracket:

 open(file1).use { in1 =>
   open(file2).use { in2 =>
     readFiles(in1, in2)
   }
 }

Resource forms a MonadError on the resource type when the effect type has a cats.MonadError instance. Nested resources are released in reverse order of acquisition. Outer resources are released even if an inner use or release fails.

 def mkResource(s: String) = {
   val acquire = IO(println(s"Acquiring $$s")) *> IO.pure(s)
   def release(s: String) = IO(println(s"Releasing $$s"))
   Resource.make(acquire)(release)
 }

 val r = for {
   outer <- mkResource("outer")
   inner <- mkResource("inner")
 } yield (outer, inner)

 r.use { case (a, b) =>
   IO(println(s"Using $$a and $$b"))
 }

On evaluation the above prints:

 Acquiring outer
 Acquiring inner
 Using outer and inner
 Releasing inner
 Releasing outer

A Resource is nothing more than a data structure, an ADT, described by the following node types and that can be interpreted if needed:

Normally users don't need to care about these node types, unless conversions from Resource into something else is needed (e.g. conversion from Resource into a streaming data type).

Type Params

A: the type of resource
F: the effect type in which the resource is allocated and released

Companion

object

class ResourceLike[F, A]

class Object

trait Matchable

class Any

Value members

Concrete methods

Combines two Resource instances by lifting the behaviour of a SemigroupK instance into the resource context

Given a natural transformation from F to G, transforms this Resource from effect F to effect G.

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.

Like onFinalize, but the action performed depends on the exit case.

Inherited methods

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.

Inherited from: ResourceLike

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

Inherited from: ResourceLike

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

Inherited from: ResourceLike

Implementation for the flatMap operation, as described via the cats.Monad type class.

Inherited from: ResourceLike

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

This is the standard Functor.map.

Inherited from: ResourceLike

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.

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

 def mkResource(name: String) = {
   val acquire =
     IO(scala.util.Random.nextInt(1000).millis).flatMap(IO.sleep) *>
     IO(println(s"Acquiring $$name")).as(name)

   val release = 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(msg => IO(println(msg)))

Inherited from: ResourceLike

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.

Value Params

f: the function to apply to the allocated resource

Returns

the result of applying [F] to

Inherited from

ResourceLike