Resource

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.