One final note: the
@aaaa@ @bbbb@ example may not
work too well on GHC (see Scheduling, above), due
- to the locking on a 'Handle'. Only one thread
- may hold the lock on a 'Handle' at any one
+ to the locking on a 'System.IO.Handle'. Only one thread
+ may hold the lock on a 'System.IO.Handle' at any one
time, so if a reschedule happens while a thread is holding the
lock, the other thread won't be able to run. The upshot is that
the switch from @aaaa@ to
touchForeignPtr :: ForeignPtr a -> IO ()
-- ^This function ensures that the foreign object in
-- question is alive at the given place in the sequence of IO
--- actions. In particular 'withForeignPtr'
+-- actions. In particular 'Foreign.ForeignPtr.withForeignPtr'
-- does a 'touchForeignPtr' after it
-- executes the user action.
--
-- has another usage occurrence.
--
-- To avoid subtle coding errors, hand written marshalling code
--- should preferably use 'withForeignPtr' rather
+-- should preferably use 'Foreign.ForeignPtr.withForeignPtr' rather
-- than combinations of 'unsafeForeignPtrToPtr' and
-- 'touchForeignPtr'. However, the later routines
-- are occasionally preferred in tool generated marshalling code.
-- Some operating systems delete empty files, so there is no guarantee
-- that the file will exist following an 'openFile' with @mode@
-- 'WriteMode' unless it is subsequently written to successfully.
--- The handle is positioned at the end of the file if `mode' is
--- `AppendMode', and otherwise at the beginning (in which case its
+-- The handle is positioned at the end of the file if @mode@ is
+-- 'AppendMode', and otherwise at the beginning (in which case its
-- internal position is 0).
-- The initial buffer mode is implementation-dependent.
--
-- ---------------------------------------------------------------------------
-- Looking ahead
--- | Computation 'hLookahead' returns the next character from the handle
+-- | Computation 'hLookAhead' returns the next character from the handle
-- without removing it from the input buffer, blocking until a character
-- is available.
--
-- further explanation of what the type represent.
-- | Computation 'hSetBuffering' @hdl mode@ sets the mode of buffering for
--- handle hdl on subsequent reads and writes.
+-- handle @hdl@ on subsequent reads and writes.
--
-- If the buffer mode is changed from 'BlockBuffering' or
-- 'LineBuffering' to 'NoBuffering', then
-- hFlush
-- | The action 'hFlush' @hdl@ causes any items buffered for output
--- in handle `hdl' to be sent immediately to the operating system.
+-- in handle @hdl@ to be sent immediately to the operating system.
--
-- This operation may fail with:
--
-- 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 'System.IO.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
-- |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").
+-- 'Data.Dynamic.Dynamic' (see the section on Dynamic Exceptions:
+-- "Control.Exception\#DynamicExceptions").
data Exception
= ArithException ArithException
-- ^Exceptions raised by arithmetic
-- ^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'.
+ -- 'Control.Concurrent.MVar.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
-- of type @a@.
--
-- The type @a@ will normally be an instance of class
--- 'Storable' which provides the marshalling operations.
+-- 'Foreign.Storable.Storable' which provides the marshalling operations.
-- |The constant 'nullPtr' contains a distinguished value of 'Ptr'