|
GHC.IOBase | Portability | non-portable (GHC Extensions) | Stability | internal | Maintainer | cvs-ghc@haskell.org |
|
|
|
|
|
Description |
Definitions for the IO monad and its friends.
|
|
Synopsis |
|
|
|
Documentation |
|
newtype IO a |
A value of type IO a is a computation which, when performed,
does some I/O before returning a value of type a.
There is really only one way to "perform" an I/O action: bind it to
Main.main in your program. When your program is run, the I/O will
be performed. It isn't possible to perform I/O from an arbitrary
function, unless that function is itself in the IO monad and called
at some point, directly or indirectly, from Main.main.
IO is a monad, so IO actions can be combined using either the do-notation
or the >> and >>= operations from the Monad class.
| Constructors | | Instances | |
|
|
unIO :: IO a -> State# RealWorld -> (#State# RealWorld, a#) |
|
failIO :: String -> IO a |
|
liftIO :: IO a -> State# RealWorld -> STret RealWorld a |
|
bindIO :: IO a -> (a -> IO b) -> IO b |
|
thenIO :: IO a -> IO b -> IO b |
|
returnIO :: a -> IO a |
|
stToIO :: ST RealWorld a -> IO a |
A monad transformer embedding strict state transformers in the IO
monad. The RealWorld parameter indicates that the internal state
used by the ST computation is a special one supplied by the IO
monad, and thus distinct from those used by invocations of runST. |
|
ioToST :: IO a -> ST RealWorld a |
|
unsafePerformIO :: IO a -> a |
This is the "back door" into the IO monad, allowing
IO computation to be performed at any time. For
this to be safe, the IO computation should be
free of side effects and independent of its environment.
If the I/O computation wrapped in unsafePerformIO
performs side effects, then the relative order in which those side
effects take place (relative to the main I/O trunk, or other calls to
unsafePerformIO) is indeterminate. You have to be careful when
writing and compiling modules that use unsafePerformIO:
- Use {-# NOINLINE foo #-} as a pragma on any function foo
that calls unsafePerformIO. If the call is inlined,
the I/O may be performed more than once.
- Use the compiler flag -fno-cse to prevent common sub-expression
elimination being performed on the module, which might combine
two side effects that were meant to be separate. A good example
is using multiple global variables (like test in the example below).
- Make sure that the either you switch off let-floating, or that the
call to unsafePerformIO cannot float outside a lambda. For example,
if you say:
f x = unsafePerformIO (newIORef [])
you may get only one reference cell shared between all calls to f.
Better would be
f x = unsafePerformIO (newIORef [x])
because now it can't float outside the lambda.
It is less well known that
unsafePerformIO is not type safe. For example:
test :: IORef [a]
test = unsafePerformIO $ newIORef []
main = do
writeIORef test [42]
bang \<- readIORef test
print (bang :: [Char])
This program will core dump. This problem with polymorphic references
is well known in the ML community, and does not arise with normal
monadic use of references. There is no easy way to make it impossible
once you use unsafePerformIO. Indeed, it is
possible to write coerce :: a -> b with the
help of unsafePerformIO. So be careful!
|
|
unsafeInterleaveIO :: IO a -> IO a |
unsafeInterleaveIO allows IO computation to be deferred lazily.
When passed a value of type IO a, the IO will only be performed
when the value of the a is demanded. This is used to implement lazy
file reading, see hGetContents.
|
|
data MVar a |
An MVar (pronounced "em-var") is a synchronising variable, used
for communication between concurrent threads. It can be thought of
as a a box, which may be empty or full.
| Constructors | | Instances | |
|
|
data Handle |
Haskell defines operations to read and write characters from and to files,
represented by values of type Handle. Each value of this type is a
handle: a record used by the Haskell run-time system to manage I/O
with file system objects. A handle has at least the following properties:
- whether it manages input or output or both;
- whether it is open, closed or semi-closed;
- whether the object is seekable;
- whether buffering is disabled, or enabled on a line or block basis;
- a buffer (whose length may be zero).
Most handles will also have a current I/O position indicating where the next
input or output operation will occur. A handle is readable if it
manages only input or both input and output; likewise, it is writable if
it manages only output or both input and output. A handle is open when
first allocated.
Once it is closed it can no longer be used for either input or output,
though an implementation cannot re-use its storage while references
remain to it. Handles are in the Show and Eq classes. The string
produced by showing a handle is system dependent; it should include
enough information to identify the handle for debugging. A handle is
equal according to == only to itself; no attempt
is made to compare the internal state of different handles for equality. | Constructors | | Instances | |
|
|
type FD = Int |
|
data Handle__ |
|
|
type RawBuffer = MutableByteArray# RealWorld |
|
data Buffer |
|
|
data BufferState |
|
|
data BufferList |
|
|
bufferIsWritable :: Buffer -> Bool |
|
bufferEmpty :: Buffer -> Bool |
|
bufferFull :: Buffer -> Bool |
|
data HandleType |
Constructors | ClosedHandle | | SemiClosedHandle | | ReadHandle | | WriteHandle | | AppendHandle | | ReadWriteHandle | |
| Instances | |
|
|
type FilePath = String |
File and directory names are values of type String, whose precise
meaning is operating system dependent. Files can be opened, yielding a
handle which can then be used to operate on the contents of that file. |
|
data BufferMode |
Three kinds of buffering are supported: line-buffering,
block-buffering or no-buffering. These modes have the following
effects. For output, items are written out, or flushed,
from the internal buffer according to the buffer mode:
- line-buffering: the entire output buffer is flushed
whenever a newline is output, the buffer overflows,
a hFlush is issued, or the handle is closed.
- block-buffering: the entire buffer is written out whenever it
overflows, a hFlush is issued, or the handle is closed.
- no-buffering: output is written immediately, and never stored
in the buffer.
An implementation is free to flush the buffer more frequently,
but not less frequently, than specified above.
The output buffer is emptied as soon as it has been written out.
Similarly, input occurs according to the buffer mode for handle {em hdl}.
- line-buffering: when the buffer for the handle is not empty,
the next item is obtained from the buffer; otherwise, when the
buffer is empty, characters up to and including the next newline
character are read into the buffer. No characters are available
until the newline character is available or the buffer is full.
- block-buffering: when the buffer for the handle becomes empty,
the next block of data is read into the buffer.
- no-buffering: the next input item is read and returned.
The hLookAhead operation implies that even a no-buffered
handle may require a one-character buffer.
The default buffering mode when a handle is opened is
implementation-dependent and may depend on the file system object
which is attached to that handle.
For most implementations, physical files will normally be block-buffered
and terminals will normally be line-buffered. | Constructors | NoBuffering | buffering is disabled if possible. | LineBuffering | line-buffering should be enabled if possible. | BlockBuffering (Maybe Int) | block-buffering should be enabled if possible.
The size of the buffer is n items if the argument
is Just n and is otherwise implementation-dependent. |
| Instances | |
|
|
newtype IORef a |
A mutable variable in the IO monad | Constructors | | Instances | |
|
|
newIORef :: a -> IO (IORef a) |
Build a new IORef |
|
readIORef :: IORef a -> IO a |
Read the value of an IORef |
|
writeIORef :: IORef a -> a -> IO () |
Write a new value into an IORef |
|
newtype IOArray i e |
An IOArray is a mutable, boxed, non-strict array in the IO monad.
The type arguments are as follows:
- i: the index type of the array (should be an instance of Ix)
- e: the element type of the array.
| Constructors | | Instances | |
|
|
newIOArray :: Ix i => (i, i) -> e -> IO (IOArray i e) |
Build a new IOArray |
|
unsafeReadIOArray :: Ix i => IOArray i e -> Int -> IO e |
Read a value from an IOArray |
|
unsafeWriteIOArray :: Ix i => IOArray i e -> Int -> e -> IO () |
Write a new value into an IOArray |
|
readIOArray :: Ix i => IOArray i e -> i -> IO e |
Read a value from an IOArray |
|
writeIOArray :: Ix i => IOArray i e -> i -> e -> IO () |
Write a new value into an IOArray |
|
data Exception |
The type of exceptions. Every kind of system-generated exception
has a constructor in the Exception type, and values of other
types may be injected into Exception by coercing them to
Dynamic (see the section on Dynamic Exceptions:
Control.Exception#DynamicExceptions). | Constructors | ArithException ArithException | Exceptions raised by arithmetic
operations. (NOTE: GHC currently does not throw
ArithExceptions except for DivideByZero). | ArrayException ArrayException | Exceptions raised by array-related
operations. (NOTE: GHC currently does not throw
ArrayExceptions). | AssertionFailed String | This exception is thrown by the
assert operation when the condition
fails. The String argument contains the
location of the assertion in the source program. | AsyncException AsyncException | Asynchronous exceptions (see section on Asynchronous Exceptions: Control.Exception#AsynchronousExceptions). | BlockedOnDeadMVar | The current thread was executing a call to
takeMVar that could never return,
because there are no other references to this MVar. | Deadlock | There are no runnable threads, so the program is
deadlocked. The Deadlock exception is
raised in the main thread only (see also: Control.Concurrent). | DynException Dynamic | Dynamically typed exceptions (see section on Dynamic Exceptions: Control.Exception#DynamicExceptions). | ErrorCall String | The ErrorCall exception is thrown by error. The String
argument of ErrorCall is the string passed to error when it was
called. | ExitException ExitCode | The ExitException exception is thrown by exitWith (and
exitFailure). The ExitCode argument is the value passed
to exitWith. An unhandled ExitException exception in the
main thread will cause the program to be terminated with the given
exit code. | IOException IOException | These are the standard IO exceptions generated by
Haskell's IO operations. See also System.IO.Error. | NoMethodError String | An attempt was made to invoke a class method which has
no definition in this instance, and there was no default
definition given in the class declaration. GHC issues a
warning when you compile an instance which has missing
methods. | NonTermination | The current thread is stuck in an infinite loop. This
exception may or may not be thrown when the program is
non-terminating. | PatternMatchFail String | A pattern matching failure. The String argument should contain a
descriptive message including the function name, source file
and line number. | RecConError String | An attempt was made to evaluate a field of a record
for which no value was given at construction time. The
String argument gives the location of the
record construction in the source program. | RecSelError String | A field selection was attempted on a constructor that
doesn't have the requested field. This can happen with
multi-constructor records when one or more fields are
missing from some of the constructors. The
String argument gives the location of the
record selection in the source program. | RecUpdError String | An attempt was made to update a field in a record,
where the record doesn't have the requested field. This can
only occur with multi-constructor records, when one or more
fields are missing from some of the constructors. The
String argument gives the location of the
record update in the source program. |
| Instances | |
|
|
data ArithException |
The type of arithmetic exceptions | Constructors | Overflow | | Underflow | | LossOfPrecision | | DivideByZero | | Denormal | |
| Instances | |
|
|
data AsyncException |
Asynchronous exceptions | Constructors | StackOverflow | The current thread's stack exceeded its limit.
Since an exception has been raised, the thread's stack
will certainly be below its limit again, but the
programmer should take remedial action
immediately. | HeapOverflow | The program's heap is reaching its limit, and
the program should take action to reduce the amount of
live data it has. Notes:
- It is undefined which thread receives this exception.
- GHC currently does not throw HeapOverflow exceptions.
| ThreadKilled | This exception is raised by another thread
calling killThread, or by the system
if it needs to terminate the thread for some
reason. |
| Instances | |
|
|
data ArrayException |
Exceptions generated by array operations | Constructors | IndexOutOfBounds String | An attempt was made to index an array outside
its declared bounds. | UndefinedElement String | An attempt was made to evaluate an element of an
array that had not been initialized. |
| Instances | |
|
|
stackOverflow :: Exception |
|
heapOverflow :: Exception |
|
data ExitCode |
Constructors | ExitSuccess | indicates successful termination; | ExitFailure Int | indicates program failure with an exit code.
The exact interpretation of the code is
operating-system dependent. In particular, some values
may be prohibited (e.g. 0 on a POSIX-compliant system). |
| Instances | |
|
|
throw :: Exception -> a |
Throw an exception. Exceptions may be thrown from purely
functional code, but may only be caught within the IO monad. |
|
throwIO :: Exception -> IO a |
A variant of throw that can be used within the IO monad.
Although throwIO has a type that is an instance of the type of throw, the
two functions are subtly different:
throw e `seq` return () ===> throw e
throwIO e `seq` return () ===> return ()
The first example will cause the exception e to be raised,
whereas the second one won't. In fact, throwIO will only cause
an exception to be raised when it is used within the IO monad.
The throwIO variant should be used in preference to throw to
raise an exception within the IO monad because it guarantees
ordering with respect to other IO operations, whereas throw
does not. |
|
ioException :: IOException -> IO a |
|
ioError :: IOError -> IO a |
Raise an IOError in the IO monad. |
|
type IOError = IOException |
The Haskell 98 type for exceptions in the IO monad.
Any I/O operation may raise an IOError instead of returning a result.
For a more general type of exception, including also those that arise
in pure code, see Exception.
In Haskell 98, this is an opaque type. |
|
data IOException |
Exceptions that occur in the IO monad.
An IOException records a more specific error type, a descriptive
string and maybe the handle that was used when the error was
flagged. | Constructors | | Instances | |
|
|
data IOErrorType |
An abstract type that contains a value for each variant of IOError. | Constructors | AlreadyExists | | NoSuchThing | | ResourceBusy | | ResourceExhausted | | EOF | | IllegalOperation | | PermissionDenied | | UserError | | UnsatisfiedConstraints | | SystemError | | ProtocolError | | OtherError | | InvalidArgument | | InappropriateType | | HardwareFault | | UnsupportedOperation | | TimeExpired | | ResourceVanished | | Interrupted | | DynIOError Dynamic | |
| Instances | |
|
|
userError :: String -> IOError |
Construct an IOError value with a string describing the error.
The fail method of the IO instance of the Monad class raises a
userError, thus:
instance Monad IO where
...
fail s = ioError (userError s)
|
|
data IOMode |
Constructors | ReadMode | | WriteMode | | AppendMode | | ReadWriteMode | |
| Instances | |
|
|
Produced by Haddock version 0.6 |