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.
Attributes
- A
the type of resource
- F
the effect type in which the resource is allocated and released
- Companion:
- object
- Source:
- Resource.scala
- Graph
- Supertypes
- trait Serializableclass Objecttrait Matchableclass Any
- Known subtypes