Resource

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 interpretted 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).

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

Source: Resource.scala

Linear Supertypes

AnyRef, Any

Known Subclasses

Allocate, Bind, Suspend

Value Members

final def !=(arg0: Any): Boolean

Definition Classes
AnyRef → Any
final def ##(): Int

Definition Classes
AnyRef → Any
final def ==(arg0: Any): Boolean

Definition Classes
AnyRef → Any
def allocated(implicit F: Bracket[F, Throwable]): F[(A, F[Unit])]

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.
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.
final def asInstanceOf[T0]: T0

Definition Classes
Any
def clone(): AnyRef

Attributes
protected[java.lang]
Definition Classes
AnyRef
Annotations
@throws( ... )
final def eq(arg0: AnyRef): Boolean

Definition Classes
AnyRef
def equals(arg0: Any): Boolean

Definition Classes
AnyRef → Any
def finalize(): Unit

Attributes
protected[java.lang]
Definition Classes
AnyRef
Annotations
@throws( classOf[java.lang.Throwable] )
def flatMap[B](f: (A) ⇒ Resource[F, B]): Resource[F, B]

Implementation for the flatMap operation, as described via the cats.Monad type class.
final def getClass(): Class[_]

Definition Classes
AnyRef → Any
def hashCode(): Int

Definition Classes
AnyRef → Any
final def isInstanceOf[T0]: Boolean

Definition Classes
Any
final def ne(arg0: AnyRef): Boolean

Definition Classes
AnyRef
final def notify(): Unit

Definition Classes
AnyRef
final def notifyAll(): Unit

Definition Classes
AnyRef
final def synchronized[T0](arg0: ⇒ T0): T0

Definition Classes
AnyRef
def toString(): String

Definition Classes
AnyRef → Any
def use[B](f: (A) ⇒ F[B])(implicit F: Bracket[F, Throwable]): F[B]

Allocates a resource and supplies it to the given function.
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.
f
the function to apply to the allocated resource
returns
the result of applying [F] to
final def wait(): Unit

Definition Classes
AnyRef
Annotations
@throws( ... )
final def wait(arg0: Long, arg1: Int): Unit

Definition Classes
AnyRef
Annotations
@throws( ... )
final def wait(arg0: Long): Unit

Definition Classes
AnyRef
Annotations
@throws( ... )

Related Docs: object Resource | package effect

sealed abstract class Resource[F[_], A] extends AnyRef

Value Members

final def !=(arg0: Any): Boolean

final def ##(): Int

final def ==(arg0: Any): Boolean

def allocated(implicit F: Bracket[F, Throwable]): F[(A, F[Unit])]

final def asInstanceOf[T0]: T0

def clone(): AnyRef

final def eq(arg0: AnyRef): Boolean

def equals(arg0: Any): Boolean

def finalize(): Unit

def flatMap[B](f: (A) ⇒ Resource[F, B]): Resource[F, B]

final def getClass(): Class[_]

def hashCode(): Int

final def isInstanceOf[T0]: Boolean

final def ne(arg0: AnyRef): Boolean

final def notify(): Unit

final def notifyAll(): Unit

final def synchronized[T0](arg0: ⇒ T0): T0

def toString(): String

def use[B](f: (A) ⇒ F[B])(implicit F: Bracket[F, Throwable]): F[B]

final def wait(): Unit

final def wait(arg0: Long, arg1: Int): Unit

final def wait(arg0: Long): Unit

Inherited from AnyRef

Inherited from Any

Ungrouped