System.IO.Resource

This module defines an IO monad for linearly working with system resources like files. It provides tools to take resources that are currently unsafely accessible from System.IO and use them in this monad.

Import this module qualified to avoid name clashes.

To use this RIO monad, create some RIO computation, run it to get a System.IO computation.

A simple example

>>> :set -XLinearTypes
>>> :set -XQualifiedDo
>>> :set -XNoImplicitPrelude
>>> import qualified System.IO.Resource as Linear
>>> import qualified Control.Functor.Linear as Control
>>> import qualified Data.Text as Text
>>> import Prelude.Linear
>>> import qualified Prelude
>>> :{
 linearWriteToFile :: IO ()
 linearWriteToFile = Linear.run Prelude.$ Control.do
   handle1 <- Linear.openFile "/home/user/test.txt" Linear.WriteMode
   handle2 <- Linear.hPutStrLn handle1 (Text.pack "hello there")
   () <- Linear.hClose handle2
   Control.return (Ur ())
:}

To enable do notation, QualifiedDo extension is used. But since QualifiedDo only modifies the desugaring of binds, we still need to qualify return.

The Resource I/O Monad

data RIO a

The resource-aware I/O monad. This monad guarantees that acquired resources are always released.

Instances

Functor RIO

Defined in System.IO.Resource

Methods

fmap :: (a %1 -> b) -> RIO a %1 -> RIO b

Applicative RIO

Defined in System.IO.Resource

Methods

pure :: a -> RIO a

(<*>) :: RIO (a %1 -> b) %1 -> RIO a %1 -> RIO b

liftA2 :: (a %1 -> b %1 -> c) -> RIO a %1 -> RIO b %1 -> RIO c

Monad RIO

Defined in System.IO.Resource

Methods

(>>=) :: RIO a %1 -> (a %1 -> RIO b) %1 -> RIO b

(>>) :: RIO () %1 -> RIO a %1 -> RIO a

Applicative RIO

Defined in System.IO.Resource

Methods

pure :: a %1 -> RIO a

(<*>) :: RIO (a %1 -> b) %1 -> RIO a %1 -> RIO b

liftA2 :: (a %1 -> b %1 -> c) %1 -> RIO a %1 -> RIO b %1 -> RIO c

Functor RIO

Defined in System.IO.Resource

Methods

fmap :: (a %1 -> b) %1 -> RIO a %1 -> RIO b

run :: RIO (Ur a) -> IO a

Take a RIO computation with a value a that is not linearly bound and make it a System.IO computation.

Using Resource Handles

data Handle

File I/O

openFile :: FilePath -> IOMode -> RIO Handle

See openFile

data IOMode

See openFile

Constructors

ReadMode

WriteMode

AppendMode

ReadWriteMode

Instances

Enum IOMode

Since: base-4.2.0.0

Defined in GHC.IO.IOMode

Methods

succ :: IOMode -> IOMode

pred :: IOMode -> IOMode

toEnum :: Int -> IOMode

fromEnum :: IOMode -> Int

enumFrom :: IOMode -> [IOMode]

enumFromThen :: IOMode -> IOMode -> [IOMode]

enumFromTo :: IOMode -> IOMode -> [IOMode]

enumFromThenTo :: IOMode -> IOMode -> IOMode -> [IOMode]

Eq IOMode

Since: base-4.2.0.0

Defined in GHC.IO.IOMode

Methods

(==) :: IOMode -> IOMode -> Bool

(/=) :: IOMode -> IOMode -> Bool

Ord IOMode

Since: base-4.2.0.0

Defined in GHC.IO.IOMode

Methods

compare :: IOMode -> IOMode -> Ordering

(<) :: IOMode -> IOMode -> Bool

(<=) :: IOMode -> IOMode -> Bool

(>) :: IOMode -> IOMode -> Bool

(>=) :: IOMode -> IOMode -> Bool

max :: IOMode -> IOMode -> IOMode

min :: IOMode -> IOMode -> IOMode

Read IOMode

Since: base-4.2.0.0

Defined in GHC.IO.IOMode

Methods

readsPrec :: Int -> ReadS IOMode

readList :: ReadS [IOMode]

readPrec :: ReadPrec IOMode

readListPrec :: ReadPrec [IOMode]

Show IOMode

Since: base-4.2.0.0

Defined in GHC.IO.IOMode

Methods

showsPrec :: Int -> IOMode -> ShowS

show :: IOMode -> String

showList :: [IOMode] -> ShowS

Ix IOMode

Since: base-4.2.0.0

Defined in GHC.IO.IOMode

Methods

range :: (IOMode, IOMode) -> [IOMode]

index :: (IOMode, IOMode) -> IOMode -> Int

unsafeIndex :: (IOMode, IOMode) -> IOMode -> Int

inRange :: (IOMode, IOMode) -> IOMode -> Bool

rangeSize :: (IOMode, IOMode) -> Int

unsafeRangeSize :: (IOMode, IOMode) -> Int

Working with Handles

hClose :: Handle %1 -> RIO ()

hIsEOF :: Handle %1 -> RIO (Ur Bool, Handle)

hGetChar :: Handle %1 -> RIO (Ur Char, Handle)

hPutChar :: Handle %1 -> Char -> RIO Handle

hGetLine :: Handle %1 -> RIO (Ur Text, Handle)

hPutStr :: Handle %1 -> Text -> RIO Handle

hPutStrLn :: Handle %1 -> Text -> RIO Handle

Creating new types of resources

data UnsafeResource a

The type of system resources. To create and use resources, you need to use the API since the constructor is not released.

unsafeRelease :: UnsafeResource a %1 -> RIO ()

Given an unsafe resource, release it with the linear IO action provided when the resrouce was acquired.

unsafeAcquire :: IO (Ur a) -> (a -> IO ()) -> RIO (UnsafeResource a)

Given a resource in the System.IO.Linear.IO monad, and given a function to release that resource, provides that resource in the RIO monad. For example, releasing a Handle from System.IO would be done with fromSystemIO hClose. Because this release function is an input, and could be wrong, this function is unsafe.

unsafeFromSystemIOResource :: (a -> IO b) -> UnsafeResource a %1 -> RIO (Ur b, UnsafeResource a)

Given a System.IO computation on an unsafe resource, lift it to RIO computaton on the acquired resource. That is function of type a -> IO b turns into a function of type UnsafeResource a %1-> RIO (Ur b) along with threading the UnsafeResource a.

Note that the result b can be used non-linearly.

unsafeFromSystemIOResource_ :: (a -> IO ()) -> UnsafeResource a %1 -> RIO (UnsafeResource a)