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).
- F
the effect type in which the resource is allocated and released
- A
the type of resource
- Source
- Resource.scala
- Alphabetic
- By Inheritance
- Resource
- ResourceLike
- AnyRef
- Any
- Hide All
- Show All
- Public
- All
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[G[x] >: F[x], B >: A](implicit F: BracketThrow[[α$7$]G[α$7$]]): G[(B, G[Unit])]
Given a
Resource
, possibly built by composing multipleResource
s 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 multipleResource
s 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 outerF
succeeds, it's up to the user to ensure the returnedF[Unit]
is called onceA
needs to be released. If the returnedF[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
andafter
methods of many test frameworks), or complex library code that needs to modify or move the finalizer for an existing resource.- Definition Classes
- ResourceLike
-
def
allocated_[G[x] >: F[x], B >: A](implicit F: BracketThrow[G]): G[(B, G[Unit])]
Implementation of
allocated
, which is declared inResourceLike
Implementation of
allocated
, which is declared inResourceLike
- Attributes
- protected
-
final
def
asInstanceOf[T0]: T0
- Definition Classes
- Any
-
def
clone(): AnyRef
- Attributes
- protected[lang]
- Definition Classes
- AnyRef
- Annotations
- @throws( ... ) @native()
-
def
combineK[G[x] >: F[x], B >: A](that: Resource[G, B])(implicit F: Sync[G], K: SemigroupK[G]): Resource[G, B]
Combines two
Resource
instances by lifting the behaviour of aSemigroupK
instance into the resource context -
final
def
eq(arg0: AnyRef): Boolean
- Definition Classes
- AnyRef
-
def
equals(arg0: Any): Boolean
- Definition Classes
- AnyRef → Any
-
def
evalMap[G[x] >: F[x], B](f: (A) ⇒ G[B])(implicit F: Applicative[[α$8$]G[α$8$]]): Resource[[α$9$]G[α$9$], B]
Applies an effectful transformation to the allocated resource.
Applies an effectful transformation to the allocated resource. Like a
flatMap
onF[A]
while maintaining the resource context- Definition Classes
- ResourceLike
-
def
evalMap_[G[x] >: F[x], B](f: (A) ⇒ G[B])(implicit F: Applicative[G]): Resource[G, B]
Implementation of
evalMap
, which is declared inResourceLike
Implementation of
evalMap
, which is declared inResourceLike
- Attributes
- protected
-
def
evalTap[G[x] >: F[x], B](f: (A) ⇒ G[B])(implicit F: Applicative[[α$10$]G[α$10$]]): Resource[[α$11$]G[α$11$], A]
Applies an effectful transformation to the allocated resource.
Applies an effectful transformation to the allocated resource. Like a
flatTap
onF[A]
while maintaining the resource context- Definition Classes
- ResourceLike
-
def
evalTap_[G[x] >: F[x], B](f: (A) ⇒ G[B])(implicit F: Applicative[G]): Resource[G, A]
Implementation of
evalTap
, which is declared inResourceLike
Implementation of
evalTap
, which is declared inResourceLike
- Attributes
- protected
-
def
finalize(): Unit
- Attributes
- protected[lang]
- Definition Classes
- AnyRef
- Annotations
- @throws( classOf[java.lang.Throwable] )
-
def
flatMap[G[x] >: F[x], B](f: (A) ⇒ Resource[[α$3$]G[α$3$], B]): Resource[[α$4$]G[α$4$], B]
Implementation for the
flatMap
operation, as described via thecats.Monad
type class.Implementation for the
flatMap
operation, as described via thecats.Monad
type class.- Definition Classes
- ResourceLike
-
def
flatMap_[G[x] >: F[x], B](f: (A) ⇒ Resource[G, B]): Resource[G, B]
Implementation of
flatMap
, which is declared inResourceLike
Implementation of
flatMap
, which is declared inResourceLike
- Attributes
- protected
-
final
def
getClass(): Class[_]
- Definition Classes
- AnyRef → Any
- Annotations
- @native()
-
def
hashCode(): Int
- Definition Classes
- AnyRef → Any
- Annotations
- @native()
-
final
def
isInstanceOf[T0]: Boolean
- Definition Classes
- Any
-
def
map[G[x] >: F[x], B](f: (A) ⇒ B)(implicit F: Applicative[[α$5$]G[α$5$]]): Resource[[α$6$]G[α$6$], B]
Given a mapping function, transforms the resource provided by this Resource.
Given a mapping function, transforms the resource provided by this Resource.
This is the standard
Functor.map
.- Definition Classes
- ResourceLike
-
def
mapK[G[x] >: F[x], H[_]](f: ~>[G, H])(implicit D: Defer[H], G: Applicative[H]): Resource[H, A]
Given a natural transformation from
F
toG
, transforms this Resource from effectF
to effectG
. -
def
map_[G[x] >: F[x], B](f: (A) ⇒ B)(implicit F: Applicative[G]): Resource[G, B]
Implementation of
map
, which is declared inResourceLike
Implementation of
map
, which is declared inResourceLike
- Attributes
- protected
-
final
def
ne(arg0: AnyRef): Boolean
- Definition Classes
- AnyRef
-
final
def
notify(): Unit
- Definition Classes
- AnyRef
- Annotations
- @native()
-
final
def
notifyAll(): Unit
- Definition Classes
- AnyRef
- Annotations
- @native()
-
def
onFinalize[G[x] >: F[x]](finalizer: G[Unit])(implicit F: Applicative[G]): Resource[G, A]
Runs
finalizer
when this resource is closed.Runs
finalizer
when this resource is closed. Unlike the release action passed toResource.make
, this will run even if resource acquisition fails or is canceled. -
def
onFinalizeCase[G[x] >: F[x]](f: (ExitCase[Throwable]) ⇒ G[Unit])(implicit F: Applicative[G]): Resource[G, A]
Like
onFinalize
, but the action performed depends on the exit case. -
def
parZip[G[x] >: F[x], B](that: Resource[[α$1$]G[α$1$], B])(implicit arg0: Sync[G], arg1: Parallel[G]): Resource[[α$2$]G[α$2$], (A, B)]
Allocates two resources concurrently, and combines their results in a tuple.
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 acats.Parallel
instance that offers more convenient access to the same functionality asparZip
, for example viaparMapN
: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)))
- Definition Classes
- ResourceLike
-
def
parZip_[G[x] >: F[x], B](that: Resource[G, B])(implicit arg0: Sync[G], arg1: Parallel[G]): Resource[G, (A, B)]
Implementation of
parZip
, which is declared inResourceLike
Implementation of
parZip
, which is declared inResourceLike
- Attributes
- protected
-
final
def
synchronized[T0](arg0: ⇒ T0): T0
- Definition Classes
- AnyRef
-
def
toString(): String
- Definition Classes
- AnyRef → Any
-
def
use[G[x] >: F[x], B](f: (A) ⇒ G[B])(implicit F: BracketThrow[[α$0$]G[α$0$]]): G[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
- Definition Classes
- ResourceLike
-
def
use_[G[x] >: F[x], B](f: (A) ⇒ G[B])(implicit F: BracketThrow[G]): G[B]
Implementation of
use
, which is declared inResourceLike
Implementation of
use
, which is declared inResourceLike
- Attributes
- protected
-
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( ... ) @native()
This is the API documentation for the cats-effect library.
See the cats.effect package for a quick overview.
Links
Canonical documentation links:
Related Cats links (the core):