Resource
is a data structure which encodes the idea of executing an action which has an
associated finalizer that needs to be run when the action completes.
Examples include scarce resources like files, which need to be closed after use, or concurrent abstractions like locks, which need to be released after having been acquired.
There are several constructors to allocate a resource, the most common is make:
def open(file: File): Resource[IO, BufferedReader] = {
val openFile = IO(new BufferedReader(new FileReader(file)))
Resource.make(acquire = openFile)(release = f => IO(f.close))
}
and several methods to consume a resource, the most common is use:
def readFile(file: BufferedReader): IO[Content]
open(file1).use(readFile)
Finalisation (in this case file closure) happens when the action passed to use
terminates.
Therefore, the code above is not equivalent to:
open(file1).use(IO.pure).flatMap(readFile)
which will instead result in an error, since the file gets closed after pure
, meaning that
.readFile
will then fail.
Also note that a new resource is allocated every time use
is called, so the following
code opens and closes the resource twice:
val file: Resource[IO, File]
file.use(read) >> file.use(read)
If you want sharing, pass the result of allocating the resource around, and call use
once.
file.use { file => read(file) >> read(file) }
The acquire and release actions passed to make
are not interruptible, and release will run
when the action passed to use
succeeds, fails, or is interrupted. You can use
makeCase to specify a different release logic depending on each of the
three outcomes above.
It is also possible to specify an interruptible acquire though makeFull but be warned that this is an advanced concurrency operation, which requires some care.
Resource usage nests:
open(file1).use { in1 =>
open(file2).use { in2 =>
readFiles(in1, in2)
}
}
However, it is more idiomatic to compose multiple resources together before use
, exploiting
the fact that Resource
forms a Monad
, and therefore that resources can be nested through
flatMap
. 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
can also lift arbitrary actions that don't require finalisation through
eval. Actions passed to eval
preserve their interruptibility.
Finally, Resource
partakes in other abstractions such as MonadError
, Parallel
, and
Monoid
, so make sure to explore those instances as well as the other methods not covered
here.
Resource
is encoded as a data structure, an ADT, described by the following node types:
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),
in which case they can be interpreted through pattern matching.
- Type parameters:
- A
the type of resource
- F
the effect type in which the resource is allocated and released
- Companion:
- object
- Source:
- Resource.scala
Value members
Concrete methods
Given a Resource
, possibly built by composing multiple Resource
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 multiple Resource
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 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.
- Source:
- Resource.scala
Given a Resource
, possibly built by composing multiple Resource
s monadically, returns
the acquired resource, as well as a cleanup function that takes an
exit case and runs all the finalizers for releasing it.
Given a Resource
, possibly built by composing multiple Resource
s 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.
- Source:
- Resource.scala
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 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(_))
- Source:
- Resource.scala
- Source:
- Resource.scala
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 flatMap
on F[A]
while maintaining the resource context
- Source:
- Resource.scala
Applies an effectful transformation to the allocated resource. Like a flatTap
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
- Source:
- Resource.scala
Implementation for the flatMap
operation, as described via the cats.Monad
type class.
Implementation for the flatMap
operation, as described via the cats.Monad
type class.
- Source:
- Resource.scala
Flattens the outer Resource scope with the inner, mirroring the semantics of Resource.flatMap.
Flattens the outer Resource scope with the inner, mirroring the semantics of Resource.flatMap.
This function is useful in cases where some generic combinator (such as GenSpawn.background) explicitly returns a value within a Resource effect, and that generic combinator is itself used within an outer Resource. In this case, it is often desirable to flatten the inner and outer Resource together. flattenK implements this flattening operation with the same semantics as Resource.flatMap.
- Source:
- Resource.scala
- Source:
- Resource.scala
- Source:
- Resource.scala
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
.
- Source:
- Resource.scala
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].
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].
- Source:
- Resource.scala
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.
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.
- Source:
- Resource.scala
Like onFinalize
, but the action performed depends on the exit case.
Like onFinalize
, but the action performed depends on the exit case.
- Source:
- Resource.scala
Runs precede
before this resource is allocated.
Runs precede
before this resource is allocated.
- Source:
- Resource.scala
Races the evaluation of two resource allocations and returns the result of the winner, except in the case of cancelation.
Races the evaluation of two resource allocations and returns the result of the winner, except in the case of cancelation.
- Source:
- Resource.scala
Acquires the resource, runs gb
and closes the resource once gb
terminates, fails or
gets interrupted
Acquires the resource, runs gb
and closes the resource once gb
terminates, fails or
gets interrupted
- Source:
- Resource.scala
Creates a FunctionK that can run gb
within a resource, which is then closed once gb
terminates, fails or gets interrupted
Creates a FunctionK that can run gb
within a resource, which is then closed once gb
terminates, fails or gets interrupted
- Source:
- Resource.scala
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 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 parameters:
- f
the function to apply to the allocated resource
- Returns:
the result of applying [F] to
- Source:
- Resource.scala
For a resource that allocates an action (type F[B]
), allocate that action, run it and
release it.
For a resource that allocates an action (type F[B]
), allocate that action, run it and
release it.
- Source:
- Resource.scala
Allocates a resource with a non-terminating use action. Useful to run programs that are
expressed entirely in Resource
.
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.
- Source:
- Resource.scala
Allocates the resource and uses it to run the given Kleisli.
Allocates the resource and uses it to run the given Kleisli.
- Source:
- Resource.scala
Creates a FunctionK that, when applied, will allocate the resource and use it to run the given Kleisli.
Creates a FunctionK that, when applied, will allocate the resource and use it to run the given Kleisli.
- Source:
- Resource.scala
Allocates a resource and closes it immediately.
Allocates a resource and closes it immediately.
- Source:
- Resource.scala