linear-base-0.4.0: Standard library for linear types.
Safe HaskellSafe-Inferred
LanguageHaskell2010

System.IO.Resource.Linear

Description

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.Linear 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 $ 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.

Synopsis

The Resource I/O Monad

data RIO a Source #

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

Instances

Instances details
Applicative RIO Source # 
Instance details

Defined in System.IO.Resource.Linear.Internal

Methods

pure :: a %1 -> RIO a Source #

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

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

Functor RIO Source # 
Instance details

Defined in System.IO.Resource.Linear.Internal

Methods

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

Monad RIO Source # 
Instance details

Defined in System.IO.Resource.Linear.Internal

Methods

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

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

Applicative RIO Source # 
Instance details

Defined in System.IO.Resource.Linear.Internal

Methods

pure :: a -> RIO a Source #

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

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

Functor RIO Source # 
Instance details

Defined in System.IO.Resource.Linear.Internal

Methods

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

Monoid a => Monoid (RIO a) Source # 
Instance details

Defined in System.IO.Resource.Linear.Internal

Methods

mempty :: RIO a Source #

Semigroup a => Semigroup (RIO a) Source # 
Instance details

Defined in System.IO.Resource.Linear.Internal

Methods

(<>) :: RIO a %1 -> RIO a %1 -> RIO a Source #

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

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

Using Resource Handles

File I/O

openBinaryFile :: FilePath -> IOMode -> RIO Handle Source #

See System.IO.openBinaryFile

Since: 0.3.0

data IOMode #

Instances

Instances details
Enum IOMode

Since: base-4.2.0.0

Instance details

Defined in GHC.IO.IOMode

Ix IOMode

Since: base-4.2.0.0

Instance details

Defined in GHC.IO.IOMode

Read IOMode

Since: base-4.2.0.0

Instance details

Defined in GHC.IO.IOMode

Show IOMode

Since: base-4.2.0.0

Instance details

Defined in GHC.IO.IOMode

Eq IOMode

Since: base-4.2.0.0

Instance details

Defined in GHC.IO.IOMode

Methods

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

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

Ord IOMode

Since: base-4.2.0.0

Instance details

Defined in GHC.IO.IOMode

Working with Handles

hClose :: Handle %1 -> RIO () Source #

Specialised alias for release

hSeek :: Handle %1 -> SeekMode -> Integer -> RIO Handle Source #

See System.IO.hSeek.

Since: 0.3.0

data SeekMode #

A mode that determines the effect of hSeek hdl mode i.

Constructors

AbsoluteSeek

the position of hdl is set to i.

RelativeSeek

the position of hdl is set to offset i from the current position.

SeekFromEnd

the position of hdl is set to offset i from the end of the file.

Instances

Instances details
Enum SeekMode

Since: base-4.2.0.0

Instance details

Defined in GHC.IO.Device

Ix SeekMode

Since: base-4.2.0.0

Instance details

Defined in GHC.IO.Device

Read SeekMode

Since: base-4.2.0.0

Instance details

Defined in GHC.IO.Device

Show SeekMode

Since: base-4.2.0.0

Instance details

Defined in GHC.IO.Device

Eq SeekMode

Since: base-4.2.0.0

Instance details

Defined in GHC.IO.Device

Ord SeekMode

Since: base-4.2.0.0

Instance details

Defined in GHC.IO.Device

hTell :: Handle %1 -> RIO (Ur Integer, Handle) Source #

See System.IO.hTell.

Since: 0.3.0

Creating new types of resources

data Resource a Source #

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

release :: Resource a %1 -> RIO () Source #

release r calls the release function provided when r was acquired.

unsafeAcquire :: IO (Ur a) -> (a -> IO ()) -> RIO (Resource a) Source #

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) -> Resource a %1 -> RIO (Ur b, Resource a) Source #

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 Resource a %1-> RIO (Ur b) along with threading the Resource a.

unsafeFromSystemIOResource is only safe to use on actions which do not release the resource.

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

unsafeFromSystemIOResource_ :: (a -> IO ()) -> Resource a %1 -> RIO (Resource a) Source #

Specialised variant of unsafeFromSystemIOResource for actions that don't return a value.

Deprecated symbols

type UnsafeResource = Resource Source #

Deprecated: UnsafeResource has been renamed to Resource

Deprecated alias for Resource

unsafeRelease :: Resource a %1 -> RIO () Source #

Deprecated: unsafeRelease has been renamed to release

Deprecated alias of the release function