From 8759db3e70f41a06afafaddbe3e04405ef92b540 Mon Sep 17 00:00:00 2001
From: simonmar <unknown>
Date: Tue, 18 Jan 2000 15:07:24 +0000
Subject: [PATCH] [project @ 2000-01-18 15:07:23 by simonmar] Remove old
libraries documentation.
---
ghc/docs/libraries/Addr.sgml | 68 -----
ghc/docs/libraries/Bits.sgml | 59 ----
ghc/docs/libraries/Concurrent.sgml | 415 -----------------------------
ghc/docs/libraries/Dynamic.sgml | 162 -----------
ghc/docs/libraries/Exception.sgml | 206 --------------
ghc/docs/libraries/Foreign.sgml | 73 -----
ghc/docs/libraries/GetOpt.sgml | 96 -------
ghc/docs/libraries/GlaExts.sgml | 31 ---
ghc/docs/libraries/IOExts.sgml | 119 ---------
ghc/docs/libraries/Int.sgml | 112 --------
ghc/docs/libraries/Makefile | 9 -
ghc/docs/libraries/NumExts.sgml | 72 -----
ghc/docs/libraries/Pretty.sgml | 59 ----
ghc/docs/libraries/ST.sgml | 82 ------
ghc/docs/libraries/Stable.sgml | 126 ---------
ghc/docs/libraries/Weak.sgml | 278 -------------------
ghc/docs/libraries/Word.sgml | 119 ---------
ghc/docs/libraries/libs.sgml | 126 ---------
ghc/docs/libraries/refs.bib | 113 --------
19 files changed, 2325 deletions(-)
delete mode 100644 ghc/docs/libraries/Addr.sgml
delete mode 100644 ghc/docs/libraries/Bits.sgml
delete mode 100644 ghc/docs/libraries/Concurrent.sgml
delete mode 100644 ghc/docs/libraries/Dynamic.sgml
delete mode 100644 ghc/docs/libraries/Exception.sgml
delete mode 100644 ghc/docs/libraries/Foreign.sgml
delete mode 100644 ghc/docs/libraries/GetOpt.sgml
delete mode 100644 ghc/docs/libraries/GlaExts.sgml
delete mode 100644 ghc/docs/libraries/IOExts.sgml
delete mode 100644 ghc/docs/libraries/Int.sgml
delete mode 100644 ghc/docs/libraries/Makefile
delete mode 100644 ghc/docs/libraries/NumExts.sgml
delete mode 100644 ghc/docs/libraries/Pretty.sgml
delete mode 100644 ghc/docs/libraries/ST.sgml
delete mode 100644 ghc/docs/libraries/Stable.sgml
delete mode 100644 ghc/docs/libraries/Weak.sgml
delete mode 100644 ghc/docs/libraries/Word.sgml
delete mode 100644 ghc/docs/libraries/libs.sgml
delete mode 100644 ghc/docs/libraries/refs.bib
diff --git a/ghc/docs/libraries/Addr.sgml b/ghc/docs/libraries/Addr.sgml
deleted file mode 100644
index 39c62da81f8f..000000000000
--- a/ghc/docs/libraries/Addr.sgml
+++ /dev/null
@@ -1,68 +0,0 @@
-<sect> <idx/Addr/
-<label id="sec:Addr">
-<p>
-
-This library provides machine addresses and is primarily intended for
-use in creating foreign function interfaces using GreenCard.
-
-<tscreen><verb>
-module Addr where
-data Addr -- Address type
-instance Eq Addr
-instance Ord Addr
-
-nullAddr :: Addr
-plusAddr :: Addr -> Int -> Addr
-
--- read value out of _immutable_ memory
-indexCharOffAddr :: Addr -> Int -> Char
-indexIntOffAddr :: Addr -> Int -> Int
-indexAddrOffAddr :: Addr -> Int -> Addr
-indexFloatOffAddr :: Addr -> Int -> Float
-indexDoubleOffAddr :: Addr -> Int -> Double
-indexWord8OffAddr :: Addr -> Int -> Word8
-indexWord16OffAddr :: Addr -> Int -> Word16
-indexWord32OffAddr :: Addr -> Int -> Word32
-indexWord64OffAddr :: Addr -> Int -> Word64
-indexInt8OffAddr :: Addr -> Int -> Int8
-indexInt16OffAddr :: Addr -> Int -> Int16
-indexInt32OffAddr :: Addr -> Int -> Int32
-indexInt64OffAddr :: Addr -> Int -> Int64
-
--- read value out of mutable memory
-readCharOffAddr :: Addr -> Int -> IO Char
-readIntOffAddr :: Addr -> Int -> IO Int
-readAddrOffAddr :: Addr -> Int -> IO Addr
-readFloatOffAddr :: Addr -> Int -> IO Float
-readDoubleOffAddr :: Addr -> Int -> IO Double
-readWord8OffAddr :: Addr -> Int -> IO Word8
-readWord16OffAddr :: Addr -> Int -> IO Word16
-readWord32OffAddr :: Addr -> Int -> IO Word32
-readWord64OffAddr :: Addr -> Int -> IO Word64
-readInt8OffAddr :: Addr -> Int -> IO Int8
-readInt16OffAddr :: Addr -> Int -> IO Int16
-readInt32OffAddr :: Addr -> Int -> IO Int32
-readInt64OffAddr :: Addr -> Int -> IO Int64
-
--- write value into mutable memory
-writeCharOffAddr :: Addr -> Int -> Char -> IO ()
-writeIntOffAddr :: Addr -> Int -> Int -> IO ()
-writeAddrOffAddr :: Addr -> Int -> Addr -> IO ()
-writeForeignObjOffAddr :: Addr -> Int -> ForeignObj -> IO ()
-writeFloatOffAddr :: Addr -> Int -> Float -> IO ()
-writeDoubleOffAddr :: Addr -> Int -> Double -> IO ()
-writeWord8OffAddr :: Addr -> Int -> Word8 -> IO ()
-writeWord16OffAddr :: Addr -> Int -> Word16 -> IO ()
-writeWord32OffAddr :: Addr -> Int -> Word32 -> IO ()
-writeWord64OffAddr :: Addr -> Int -> Word64 -> IO ()
-writeInt8OffAddr :: Addr -> Int -> Int8 -> IO ()
-writeInt16OffAddr :: Addr -> Int -> Int16 -> IO ()
-writeInt32OffAddr :: Addr -> Int -> Int32 -> IO ()
-writeInt64OffAddr :: Addr -> Int -> Int64 -> IO ()
-</verb></tscreen>
-
-Hugs provides <tt/Addr/ and <tt/nullAddr/ but does not provide any of
-the index, read or write functions. They can be implemented using
-GreenCard if required.
-
-
diff --git a/ghc/docs/libraries/Bits.sgml b/ghc/docs/libraries/Bits.sgml
deleted file mode 100644
index 37779c25009a..000000000000
--- a/ghc/docs/libraries/Bits.sgml
+++ /dev/null
@@ -1,59 +0,0 @@
-<sect> <idx/Bits/
-<label id="sec:Bits">
-<p>
-
-This library defines bitwise operations for signed and unsigned ints.
-
-<tscreen><verb>
-module Bits where
-infixl 8 `shift`, `rotate`
-infixl 7 .&.
-infixl 6 `xor`
-infixl 5 .|.
-
-class Bits a where
- (.&.), (.|.), xor :: a -> a -> a
- complement :: a -> a
- shift :: a -> Int -> a
- rotate :: a -> Int -> a
- bit :: Int -> a
- setBit :: a -> Int -> a
- clearBit :: a -> Int -> a
- complementBit :: a -> Int -> a
- testBit :: a -> Int -> Bool
- bitSize :: a -> Int
- isSigned :: a -> Bool
-
-shiftL, shiftR :: Bits a => a -> Int -> a
-rotateL, rotateR :: Bits a => a -> Int -> a
-shiftL a i = shift a i
-shiftR a i = shift a (-i)
-rotateL a i = rotate a i
-rotateR a i = rotate a (-i)
-</verb></tscreen>
-
-Notes:
-<itemize>
-<item>
- <tt/bitSize/ and <tt/isSigned/ are like <tt/floatRadix/ and
- <tt/floatDigits/ -- they return parameters of the <em/type/ of their
- argument rather than of the particular argument they are applied to.
- <tt/bitSize/ returns the number of bits in the type; and
- <tt/isSigned/ returns whether the type is signed or not.
-<item>
- <tt/shift/ performs sign extension on signed number types.
- That is, right shifts fill the top bits with 1 if the number is negative
- and with 0 otherwise.
-<item>
- Bits are numbered from 0 with bit 0 being the least significant bit.
-<item>
- <tt/shift x i/ and <tt/rotate x i/ shift to the left if <tt/i/ is
- positive and to the right otherwise.
-<!--
- <item>
- <tt/rotate/ is well defined only if bitSize returns a number.
- (Maybe we should impose a Bounded constraint on it?)
- -->
-<item>
- <tt/bit i/ is the value with the i'th bit set.
-</itemize>
diff --git a/ghc/docs/libraries/Concurrent.sgml b/ghc/docs/libraries/Concurrent.sgml
deleted file mode 100644
index e02a5153b755..000000000000
--- a/ghc/docs/libraries/Concurrent.sgml
+++ /dev/null
@@ -1,415 +0,0 @@
-<sect> <idx/Concurrent/
-<label id="sec:Concurrent">
-<p>
-
-<sect1> <idx/Concurrent Haskell/
-<label id="sec:Concurrent Haskell">
-<p>
-
-GHC and Hugs both provide concurrency extensions, as described in
-<url name="Concurrent Haskell"
-url="http://research.microsoft.com/Users/simonpj/Papers/concurrent-haskell.ps.gz">.
-
-Concurrency in GHC and Hugs is "lightweight", which means that both
-thread creation and context switching overheads are extremely low.
-Scheduling of Haskell threads is done internally in the Haskell
-runtime system, and doesn't make use of any operating system-supplied
-thread packages.
-
-Haskell threads can communicate via <tt/MVar/s, a kind of synchronised
-mutable variable. Several common concurrency abstractions can be
-built from <tt/MVar/s, and these are provided by the <tt/Concurrent/
-library, which is described in the later sections. Threads may also
-communicate via exceptions.
-
-<sect1> <idx/Concurrency Basics/
-<label id="sec:Concurrency Basics">
-<p>
-
-To gain access to the concurrency primitives, just <tt/import Concurrent/
-in your Haskell module. In GHC, you also need to add the <tt/-syslib
-concurrent/ option to the command line.
-
-To create a new thread, use <tt/forkIO/:
-
-<tscreen><verb>
-forkIO :: IO () -> IO ThreadId
-</verb></tscreen>
-
-This sparks off a new thread to run the <tt/IO/ computation passed as the
-first argument.
-
-The returned <tt/ThreadId/ is an abstract type representing a handle
-to the newly created thread. The <tt/ThreadId/ type is an instance of
-both <tt/Eq/ and <tt/Ord/, where the <tt/Ord/ instance implements an
-arbitrary total ordering over <tt/ThreadId/s.
-
-Threads may also be killed via the <tt/ThreadId/:
-
-<tscreen><verb>
-killThread :: ThreadId -> IO ()
-</verb></tscreen>
-
-this terminates the given thread (Note: <tt/killThread/ is not
-implemented in Hugs yet). Any work already done by the thread isn't
-lost: the computation is suspended until required by another thread.
-The memory used by the thread will be garbage collected if it isn't
-referenced from anywhere else.
-
-More generally, an arbitrary exception (see Section <ref
-id="sec:Exception" name="Exceptions">) may be raised in any thread for
-which we have a <tt/ThreadId/, with <tt/raiseInThread/:
-
-<tscreen><verb>
-raiseInThread :: ThreadId -> Exception -> IO ()
-</verb></tscreen>
-
-Actually <tt/killThread/ just raises the <tt/ThreadKilled/ exception
-in the target thread, the normal action of which is to just terminate
-the thread. The target thread will stop whatever it was doing (even
-if it was blocked on an <tt/MVar/ or other computation) and handle the
-exception.
-
-One important property of <tt/raiseInThread/ (and therefore
-<tt/killThread/) is that they are <em/synchronous/. This means that
-after performing a <tt/raiseInThread/ operation, the calling thread
-can be certain that the target thread has received the exception. In
-other words, the target thread cannot perform any more processing
-unless it handles the exception that has just been raised in it. This
-is a useful property to know when dealing with race conditions: eg. if
-there are two threads that can kill each other, it is guaranteed that
-only one of the threads will get to kill the other.
-
-The <tt/ThreadId/ for the current thread can be obtained with
-<tt/myThreadId/:
-
-<tscreen><verb>
-myThreadId :: IO ThreadId
-</verb></tscreen>
-
-NOTE: if you have a <tt/ThreadId/, you essentially have a pointer to the
-thread itself. This means the thread itself can't be garbage
-collected until you drop the <tt/ThreadId/. This misfeature will
-hopefully be corrected at a later date.
-
-<sect1> Scheduling
-<p>
-
-GHC uses <em>preemptive multitasking</em>: context switches can occur
-at any time. At present, Hugs uses <em>cooperative multitasking</em>:
-context switches only occur when you use one of the primitives defined
-in this module. This means that programs such as:
-
-<tscreen><verb>
-main = forkIO (write 'a') >> write 'b'
- where write c = putChar c >> write c
-</verb></tscreen>
-
-will print either <tt/aaaaaaaaaaaaaa.../ or <tt/bbbbbbbbbbbb.../,
-instead of some random interleaving of <tt/a/s and <tt/b/s.
-In practice, cooperative multitasking is sufficient for writing simple
-graphical user interfaces.
-
-The <tt>yield</tt> action forces a context-switch to any other
-currently runnable threads (if any), and is occasionally useful when
-implementing concurrency abstractions:
-
-<tscreen><verb>
-yield :: IO ()
-</verb></tscreen>
-
-<sect2> <idx/Thread Waiting/
-<p>
-
-Finally, there are operations to delay a concurrent thread, and to
-make one wait:<nidx>delay a concurrent thread</nidx>
-<nidx>wait for a file descriptor</nidx>
-
-<tscreen><verb>
-threadDelay :: Int -> IO () -- delay rescheduling for N microseconds
-threadWaitRead :: Int -> IO () -- wait for input on specified file descriptor
-threadWaitWrite :: Int -> IO () -- (read and write, respectively).
-</verb></tscreen>
-
-The <tt/threadDelay/ operation will cause the current thread to
-suspend for a given number of microseconds. Note that the resolution
-used by the Haskell runtime system's internal timer together with the
-fact that the thread may take some time to be rescheduled after the
-time has expired, means that the accuracy is more like 1/50 second.
-
-<tt/threadWaitRead/ and <tt/threadWaitWrite/ can be used to block a
-thread until I/O is available on a given file descriptor. These
-primitives are used by the I/O subsystem to ensure that a thread
-waiting on I/O doesn't hang the entire system.
-
-<sect2> <idx/Blocking/
-<p>
-Calling a foreign C procedure (such as <tt/getchar/) that blocks
-waiting for input will block <em>all</em> threads, in both
-GHC and Hugs. The GHC I/O system uses non-blocking I/O internally to implement
-thread-friendly I/O, so calling standard Haskell I/O functions blocks
-only the thead making the call.
-
-
-<sect1> <idx/Concurrency abstractions/
-<label id="sec:Concurrency-abstractions">
-<p>
-
-<sect2> <idx/MVars/
-<label id="sec:MVars">
-<p>
-
-The <tt/Concurrent/ interface provides access to ``M-Vars'', which are
-<em>synchronising variables</em>.
-
-<nidx>synchronising variables (Glasgow extension)</nidx>
-<nidx>concurrency -- synchronising variables</nidx>
-
-<tt/MVars/<nidx>MVars (Glasgow extension)</nidx> are rendezvous points,
-mostly for concurrent threads. They begin either empty or full, and
-any attempt to read an empty <tt/MVar/ blocks. When an <tt/MVar/ is
-written, a single blocked thread may be freed. Reading an <tt/MVar/
-toggles its state from full back to empty. Therefore, any value
-written to an <tt/MVar/ may only be read once. Multiple reads and writes
-are allowed, but there must be at least one read between any two
-writes. Interface:
-
-<tscreen><verb>
-data MVar a -- abstract
-instance Eq (MVar a)
-
-newEmptyMVar :: IO (MVar a)
-newMVar :: a -> IO (MVar a)
-takeMVar :: MVar a -> IO a
-putMVar :: MVar a -> a -> IO ()
-readMVar :: MVar a -> IO a
-swapMVar :: MVar a -> a -> IO a
-isEmptyMVar :: MVar a -> IO Bool
-</verb></tscreen>
-
-The operation <tt/isEmptyMVar/ returns a flag indicating
-whether the <tt/MVar/ is currently empty or filled in, i.e.,
-will a thread block when performing a <tt/takeMVar/ on that
-<tt/MVar/ or not?
-
-Please notice that the Boolean value returned from <tt/isEmptyMVar/
-represent just a snapshot of the state of the <tt/MVar/. By the
-time a thread gets to inspect the result and act upon it, other
-threads may have accessed the <tt/MVar/ and changed the 'filled-in'
-status of the variable.
-
-The same proviso applies to <tt/isEmptyChan/ (next sub-section).
-
-These two predicates are currently only supported by GHC.
-
-<sect2> <idx/Channel Variables/
-<label id="sec:CVars">
-<p>
-
-A <em>channel variable</em> (<tt/CVar/) is a one-element channel, as
-described in the paper:
-
-<tscreen><verb>
-data CVar a
-newCVar :: IO (CVar a)
-putCVar :: CVar a -> a -> IO ()
-getCVar :: CVar a -> IO a
-</verb></tscreen>
-
-<sect2> <idx/Channels/
-<label id="sec:Channels">
-<p>
-
-A <tt/Channel/ is an unbounded channel:
-
-<tscreen><verb>
-data Chan a
-newChan :: IO (Chan a)
-putChan :: Chan a -> a -> IO ()
-getChan :: Chan a -> IO a
-dupChan :: Chan a -> IO (Chan a)
-unGetChan :: Chan a -> a -> IO ()
-getChanContents :: Chan a -> IO [a]
-</verb></tscreen>
-
-<sect2> <idx/Semaphores/
-<label id="sec:Semaphores">
-<p>
-
-General and quantity semaphores:
-
-<tscreen><verb>
-data QSem
-newQSem :: Int -> IO QSem
-waitQSem :: QSem -> IO ()
-signalQSem :: QSem -> IO ()
-
-data QSemN
-newQSemN :: Int -> IO QSemN
-signalQSemN :: QSemN -> Int -> IO ()
-waitQSemN :: QSemN -> Int -> IO ()
-</verb></tscreen>
-
-<sect2> <idx/Merging Streams/
-<label id="sec:Merging Streams">
-<p>
-
-Merging streams---binary and n-ary:
-
-<tscreen><verb>
-mergeIO :: [a] -> [a] -> IO [a]
-nmergeIO :: [[a]] -> IO [a]
-</verb></tscreen>
-
-These actions fork one thread for each input list that concurrently
-evaluates that list; the results are merged into a single output list.
-
-Note: Hugs does not provide the functions <tt/mergeIO/ or
-<tt/nmergeIO/ since these require preemptive multitasking.
-
-<sect2> <idx/Sample Variables/
-<label id="sec:Sample-Variables">
-<p>
-
-A <em>Sample variable</em> (<tt/SampleVar/) is slightly different from a
-normal <tt/MVar/:
-
-<itemize>
-<item> Reading an empty <tt/SampleVar/ causes the reader to block
- (same as <tt/takeMVar/ on empty <tt/MVar/).
-<item> Reading a filled <tt/SampleVar/ empties it and returns value.
- (same as <tt/takeMVar/)
-<item> Writing to an empty <tt/SampleVar/ fills it with a value, and
-potentially, wakes up a blocked reader (same as for <tt/putMVar/ on empty <tt/MVar/).
-<item> Writing to a filled <tt/SampleVar/ overwrites the current value.
- (different from <tt/putMVar/ on full <tt/MVar/.)
-</itemize>
-
-<tscreen><verb>
-type SampleVar a = MVar (Int, MVar a)
-
-emptySampleVar :: SampleVar a -> IO ()
-newSampleVar :: IO (SampleVar a)
-readSample :: SampleVar a -> IO a
-writeSample :: SampleVar a -> a -> IO ()
-</verb></tscreen>
-
-<sect1> The <tt/Concurrent/ library interface
-<p>
-
-The full interface for the <tt/Concurrent/ library is given below for
-reference:
-
-<tscreen><verb>
-module Concurrent where
-
-data ThreadId -- thread identifiers
-instance Eq ThreadId
-instance Ord ThreadId
-
-forkIO :: IO () -> IO ThreadId
-myThreadId :: IO ThreadId
-killThread :: ThreadId -> IO ()
-yield :: IO ()
-
-data MVar a -- Synchronisation variables
-instance Eq (MVar a)
-newEmptyMVar :: IO (MVar a)
-newMVar :: a -> IO (MVar a)
-takeMVar :: MVar a -> IO a
-putMVar :: MVar a -> a -> IO ()
-swapMVar :: MVar a -> a -> IO a
-readMVar :: MVar a -> IO a
-isEmptyMVar :: MVar a -> IO Bool
-
-
-data Chan a -- channels
-newChan :: IO (Chan a)
-writeChan :: Chan a -> a -> IO ()
-readChan :: Chan a -> IO a
-dupChan :: Chan a -> IO (Chan a)
-unReadChan :: Chan a -> a -> IO ()
-isEmptyChan :: Chan a -> IO Bool
-getChanContents :: Chan a -> IO [a]
-writeList2Chan :: Chan a -> [a] -> IO ()
-
-data CVar a -- one element channels
-newCVar :: IO (CVar a)
-putCVar :: CVar a -> a -> IO ()
-getCVar :: CVar a -> IO a
-
-data QSem -- General/quantity semaphores
-newQSem :: Int -> IO QSem
-waitQSem :: QSem -> IO ()
-signalQSem :: QSem -> IO ()
-
-data QSemN -- General/quantity semaphores
-newQSemN :: Int -> IO QSemN
-waitQSemN :: QSemN -> Int -> IO ()
-signalQSemN :: QSemN -> Int -> IO ()
-
-type SampleVar a -- Sample variables
-newEmptySampleVar:: IO (SampleVar a)
-newSampleVar :: a -> IO (SampleVar a)
-emptySampleVar :: SampleVar a -> IO ()
-readSampleVar :: SampleVar a -> IO a
-writeSampleVar :: SampleVar a -> a -> IO ()
-
-threadDelay :: Int -> IO ()
-threadWaitRead :: Int -> IO ()
-threadWaitWrite :: Int -> IO ()
-</verb></tscreen>
-
-<sect1> GHC-specific concurrency issues
-<p>
-
-In a standalone GHC program, only the main thread is required to
-terminate in order for the process to terminate. Thus all other
-forked threads will simply terminate at the same time as the main
-thread (the terminology for this kind of behaviour is ``daemonic
-threads'').
-
-If you want the program to wait for child threads to finish before
-exiting, you need to program this yourself. A simple mechanism is to
-have each child thread write to an <tt/MVar/ when it completes, and
-have the main thread wait on all the <tt/MVar/s before exiting:
-
-<tscreen><verb>
-myForkIO :: IO () -> IO (MVar ())
-myForkIO io = do
- mvar <- newEmptyMVar
- forkIO (io `finally` putMVar mvar ())
- return mvar
-</verb></tscreen>
-
-Note that we use <tt/finally/ from the <tt/Exception/ module to make
-sure that the <tt/MVar/ is written to even if the thread dies or is
-killed for some reason.
-
-A better method is to keep a global list of all child threads which we
-should wait for at the end of the program:
-
-<tscreen><verb>
-children :: MVar [MVar ()]
-children = unsafePerformIO (newMVar [])
-
-waitForChildren :: IO ()
-waitForChildren = do
- (mvar:mvars) <- takeMVar children
- putMVar children mvars
- takeMVar mvar
- waitForChildren
-
-forkChild :: IO () -> IO ()
-forkChild io = do
- mvar <- newEmptyMVar
- forkIO (p `finally` putMVar mvar ())
- childs <- takeMVar children
- putMVar children (mvar:childs)
-
-later = flip finally
-
-main =
- later waitForChildren $
- ...
-</verb></tscreen>
diff --git a/ghc/docs/libraries/Dynamic.sgml b/ghc/docs/libraries/Dynamic.sgml
deleted file mode 100644
index eccaddb285de..000000000000
--- a/ghc/docs/libraries/Dynamic.sgml
+++ /dev/null
@@ -1,162 +0,0 @@
-<sect> <idx/Dynamic/
-<label id="sec:Dynamic">
-<p>
-
-The <tt/Dynamic/ library provides cheap-and-cheerful dynamic types for
-Haskell. A dynamically typed value is one which carries type
-information with it at run-time, and is represented here by the
-abstract type <tt/Dynamic/. Values can be converted into <tt/Dynamic/
-ones, which can then be combined and manipulated by the program using
-the operations provided over the abstract, dynamic type. One of
-these operations allows you to (try to) convert a dynamically-typed
-value back into a value with the same (monomorphic) type it had before
-converting it into a dynamically-typed value. If the dynamically-typed
-value isn't of the desired type, the coercion will fail.
-
-The <tt/Dynamic/ library is capable of dealing with monomorphic types
-only; no support for polymorphic dynamic values, but hopefully that
-will be added at a later stage.
-
-Examples where this library may come in handy (dynamic types, really -
-hopefully the library provided here will suffice) are: persistent
-programming, interpreters, distributed programming etc.
-
-The following operations are provided over the <tt/Dynamic/ type:
-
-<tscreen> <verb>
-data Dynamic -- abstract, instance of: Show --
-
-toDyn :: Typeable a => a -> Dynamic
-fromDyn :: Typeable a => Dynamic -> a -> a
-fromDynamic :: Typeable a => Dynamic -> Maybe a
-</verb></tscreen>
-
-<itemize>
-<item> <tt/toDyn/ converts a value into a dynamic one, provided
-<tt/toDyn/ knows the (concrete) type representation of the value.
-The <tt/Typeable/ type class is used to encode this, overloading a
-function that returns the type representation of a value. More on this
-below.
-<item> There's two ways of going from a dynamic value to one with
-a concrete type: <tt/fromDyn/, tries to convert the dynamic value into
-a value with the same type as its second argument. If this fails, the
-default second argument is just returned. <tt/fromDynamic/ returns a
-<tt/Maybe/ type instead, <tt/Nothing/ coming back if the conversion
-was not possible.
-<item>
-The <tt/Dynamic/ type has got a <tt/Show/ instance which returns
-a pretty printed string of the type of the dynamic value. (Useful when
-debugging).
-</itemize>
-
-<sect1> <idx/Representing types/
-<label id="sec:Dynamic:TypeRep">
-<p>
-
-Haskell types are represented as terms using the <tt/TypeRep/
-abstract type:
-
-<tscreen> <verb>
-data TypeRep -- abstract, instance of: Eq, Show
-data TyCon -- abstract, instance of: Eq, Show
-
-mkTyCon :: String -> TyCon
-mkAppTy :: TyCon -> [TypeRep] -> TypeRep
-mkFunTy :: TypeRep -> TypeRep -> TypeRep
-applyTy :: TypeRep -> TypeRep -> Maybe TypeRep
-</verb></tscreen>
-
-<itemize>
-<item> <tt/mkAppTy/ applies a type constructor to a sequence of types,
-returning a type.
-<item> <tt/mkFunTy/ is a special case of <tt/mkAppTy/, applying
-the function type constructor to a pair of types.
-<item> <tt/applyTy/ applies a type to a function type. If possible,
-the result type is returned.
-<item> Type constructors are represented by the abstract type,
-<tt/TyCon/.
-<item>
-Most importantly, <tt/TypeRep/s can be compared for equality.
-Type equality is used when converting a <tt/Dynamic/ value into a
-value of some specific type, comparing the type representation that
-the <tt/Dynamic/ value embeds with equality of the type representation
-of the type we're trying to convert the dynamically-typed value into.
-<item>
-To allow comparisons between <tt/TypeRep/s to be implemented
-efficiently, the <em/abstract/ <tt/TyCon/ type is used, with
-the constructor function <tt/mkTyCon/ provided:
-
-<tscreen> <verb>
-mkTyCon :: String -> TyCon
-</verb></tscreen>
-
-An implementation of the <tt/Dynamic/ interface guarantees the
-following,
-
-<tscreen> <verb>
- mkTyCon "a" == mkTyCon "a"
-</verb></tscreen>
-
-A really efficient implementation is possible if we guarantee/demand
-that the strings are unique, and for a particular type constructor,
-the application <tt/mkTyCon/ to the string that represents the type
-constructor is never duplicated. <bf/Q:/ <em>Would this constraint be
-unworkable in practice?</em>
-<item>
-Both <tt/TyCon/ and <tt/TypeRep/ are instances of the <tt/Show/ type
-classes. To have tuple types be shown in infix form, the <tt/Show/
-instance guarantees that type constructors consisting of <tt/n/-commas,
-i.e., (<tt/mkTyCon ",,,,"/), is shown as an <tt/(n+1)/ tuple in infix
-form.
-</itemize>
-
-<sect1><idx>The Typeable class</idx>
-<nidx>Typeable class</nidx>
-<label id="sec:Dynamic:Typeable">
-<p>
-
-To ease the construction of <tt/Dynamic/ values, we
-introduce the following type class to help working with <tt/TypeRep/s:
-
-<tscreen><verb>
-class Typeable a where
- typeOf :: a -> TypeRep
-</verb></tscreen>
-
-<itemize>
-<item> The <tt/typeOf/ function is overloaded to return the type
-representation associated with a type.
-<item> <bf/Important:/ The argument to <tt/typeOf/ is only used to
-carry type information around so that overloading can be resolved.
-<tt/Typeable/ instances should never, ever look at this argument.
-<item> The <tt/Dynamic/ library provide <tt/Typeable/ instances
-for all Prelude and Hugs/GHC extension library types. They are:
-
-<tscreen><verb>
-Prelude types:
- Int, Char, Bool, Float, Double, Integer, (IO a),
- [a], (Either a b), (Maybe a), (a->b),
- (), (,), (,,), (,,,), (,,,,),
- Ordering, Complex, Array, Handle
-Hugs/GHC types:
- Addr, Word8, Word16, Word32, Word64,
- Int8,Int16,Int32,Int64,
- ForeignObj, MVar, (ST s a), (StablePtr a)
-GHC types:
- Word, ByteArray, MutableByteArray
-</verb></tscreen>
-
-</itemize>
-
-<sect1> <idx/Utility functions/
-<label id="sec:Dynamic:util">
-<p>
-
-Operations for applying a dynamic function type to a
-dynamically typed argument are commonly useful, and
-also provided:
-
-<tscreen> <verb>
-dynApply :: Dynamic -> Dynamic -> Dynamic -- unsafe.
-dynApplyMb :: Dynamic -> Dynamic -> Maybe Dynamic
-</verb></tscreen>
diff --git a/ghc/docs/libraries/Exception.sgml b/ghc/docs/libraries/Exception.sgml
deleted file mode 100644
index 55de61d400bb..000000000000
--- a/ghc/docs/libraries/Exception.sgml
+++ /dev/null
@@ -1,206 +0,0 @@
-<sect> <idx/Exception/
-<label id="sec:Exception">
-<p>
-
-The Exception library provides an interface for raising and catching
-both built-in and user defined exceptions.
-
-Exceptions are defined by the following (non-abstract) datatype:
-
-<tscreen><verb>
-data Exception
- = IOException IOError -- IO exceptions (from 'fail')
- | ArithException ArithException -- Arithmetic exceptions
- | ErrorCall String -- Calls to 'error'
- | NoMethodError String -- A non-existent method was invoked
- | PatternMatchFail String -- A pattern match failed
- | NonExhaustiveGuards String -- A guard match failed
- | RecSelError String -- Selecting a non-existent field
- | RecConError String -- Field missing in record construction
- | RecUpdError String -- Record doesn't contain updated field
- | AssertionFailed String -- Assertions
- | DynException Dynamic -- Dynamic exceptions
- | AsyncException AsyncException -- Externally generated errors
-
-instance Eq Exception
-instance Ord Exception
-instance Show Exception
-
-data ArithException
- = Overflow
- | Underflow
- | LossOfPrecision
- | DivideByZero
- | Denormal
-
-instance Eq ArithError
-instance Ord ArithError
-instance Show ArithError
-
-data AsyncException
- = StackOverflow
- | HeapOverflow
- | ThreadKilled
- deriving (Eq, Ord)
-
-instance Eq AsyncException
-instance Ord AsyncException
-instance Show AsyncException
-</verb></tscreen>
-
-An implementation should raise the appropriate exception when one of
-the above conditions arises. <em>Note: GHC currently doesn't generate
-the arithmetic or the async exceptions.</em>
-
-Exceptions may be thrown explicitly from anywhere:
-
-<tscreen><verb>
-throw :: Exception -> a
-</verb></tscreen>
-
-<sect1> The <tt/try/ functions
-<p>
-
-There are several functions for catching and examining exceptions; all
-of them may only be used from within the <tt/IO/ monad. Firstly the
-<tt/try/ family of functions:
-
-<tscreen><verb>
-tryAll :: a -> IO (Either Exception a)
-tryAllIO :: IO a -> IO (Either Exception a)
-try :: (Exception -> Maybe b) -> a -> IO (Either b a)
-tryIO :: (Exception -> Maybe b) -> IO a -> IO (Either b a)
-</verb></tscreen>
-
-The simplest version is <tt/tryAll/. It takes a single argument,
-evaluates it (as if you'd applied <tt/seq/ to it), and returns either
-<tt/Right a/ if the evaluation succeeded with result <tt/a/, or
-<tt/Left e/ if an exception was raised, where <tt/e/ is the exception.
-Note that due to Haskell's unspecified evaluation order, an expression
-may return one of several possible exceptions: consider the expression
-<tt/error "urk" + 1 `div` 0/. Does <tt/tryAll/ return <tt/Just
-(ErrorCall "urk")/ or <tt/Just (ArithError DivideByZero)/? The answer
-is "either": <tt/tryAll/ makes a non-deterministic choice about which
-exception to return. If you call it again, you might get a different
-exception back. This is ok, because <tt/tryAll/ is an IO
-computation.
-
-<tt/tryAllIO/ is the same as <tt/tryAll/ except that the argument to
-evaluate is an <tt/IO/ computation. Don't try to use <tt/tryAll/ to
-catch exceptions in <tt/IO/ computations: in GHC an expression of type
-<tt/IO a/ is in fact a function, so evaluating it does nothing at all
-(and therefore raises no exceptions). Hence the need for
-<tt/tryAllIO/, which runs <tt/IO/ computations properly.
-
-The functions <tt/try/ and <tt/tryIO/ take an extra argument which is
-an <em/exception predicate/, a function which selects which type of
-exceptions we're interested in. The full set of exception predicates
-is given below:
-
-<tscreen><verb>
-justIoErrors :: Exception -> Maybe IOError
-justArithExceptions :: Exception -> Maybe ArithException
-justErrors :: Exception -> Maybe String
-justDynExceptions :: Exception -> Maybe Dynamic
-justAssertions :: Exception -> Maybe String
-justAsyncExceptions :: Exception -> Maybe AsyncException
-</verb></tscreen>
-
-For example, to catch just calls to 'error' we could use something
-like
-
-<tscreen><verb>
- result <- try justErrors thing_to_try
-</verb></tscreen>
-
-Any other exceptions which aren't matched by the predicate are
-re-raised, and may be caught by an enclosing <tt/try/ or <tt/catch/.
-
-<sect1> The <tt/catch/ functions
-<p>
-
-The <tt/catch/ family is similar to the <tt/try/ family:
-
-<tscreen><verb>
-catchAll :: a -> (Exception -> IO a) -> IO a
-catchAllIO :: IO a -> (Exception -> IO a) -> IO a
-catch :: (Exception -> Maybe b) -> a -> (b -> IO a) -> IO a
-catchIO :: (Exception -> Maybe b) -> IO a -> (b -> IO a) -> IO a
-</verb></tscreen>
-
-The difference is that instead of returning an <tt/Either/ type as the
-result, the <tt/catch/ functions take a <em/handler/ argument which is
-invoked in the case that an exception was raised while evaluating the
-first argument.
-
-<tt/catch/ and <tt/catchIO/ take exception predicate arguments in the
-same way as <tt/try/ and <tt/tryIO/.
-
-Note that <tt/catchIO justIoErrors/ is identical to <tt/IO.catch/. In
-fact, the implementation of <tt/IO/ errors in GHC uses exceptions
-"under the hood".
-
-Also, don't forget to <tt/import Prelude hidiing (catch)/ when using
-this library, to avoid the name clash between <tt/Exception.catch/ and
-<tt/IO.catch/.
-
-<sect1> <idx/Dynamic Exceptions/
-<label id="sec:Dynamic-Exceptions">
-<p>
-
-Because the <tt/Exception/ datatype isn't extendible, we added an
-interface for throwing and catching exceptions of type <tt/Dynamic/
-(see Section <ref name="Dynamic" id="sec:Dynamic">), which allows
-exception values of any type in the <tt/Typeable/ class to be thrown
-and caught.
-
-<tscreen><verb>
-throwDyn :: Typeable exception => exception -> b
-catchDyn :: Typeable exception => IO a -> (exception -> IO a) -> IO a
-</verb></tscreen>
-
-The <tt/catchDyn/ function only catches exceptions of the required
-type; all other exceptions are re-thrown as with <tt/catchIO/ and
-friends above.
-
-<sect1> Other Utilities
-<p>
-
-The <tt/bracket/ functions are useful for making sure that resources are
-released properly by code that may raise exceptions:
-
-<tscreen><verb>
- bracket :: IO a -> (a -> IO b) -> (a -> IO c) -> IO c
- bracket_ :: IO a -> IO b -> IO c -> IO c
- finally :: IO a -> IO b -> IO b
-</verb></tscreen>
-
-For example, to open a file, do some work on it and then close it
-again, we might use something like:
-
-<tscreen><verb>
-process_file = bracket (openFile "filename") closeFile
- (do
- ...
- )
-</verb></tscreen>
-
-<tt/bracket/ works as follows: it executes its first argument
-("open"), then its third argument, followed finally by its second
-argument ("close"). If the third argument happened to raise an
-exception, then the close operation will still be performed, and the
-exception will be re-raised.
-
-This means that in the example above the file will always be closed,
-even if an error occurs during processing.
-
-The arguments to <tt/bracket/ are in this order so that we can
-partially apply it, like:
-
-<tscreen><verb>
-withFile name = bracket (openFile name) closeFile
-</verb></tscreen>
-
-The <tt/bracket_/ function is a variant of <tt/bracket/ that throws
-away the result of the open, and <tt/finally/ is an even simpler
-version where we just want some closing code.
diff --git a/ghc/docs/libraries/Foreign.sgml b/ghc/docs/libraries/Foreign.sgml
deleted file mode 100644
index 05e56b3419b3..000000000000
--- a/ghc/docs/libraries/Foreign.sgml
+++ /dev/null
@@ -1,73 +0,0 @@
-<sect> <idx/Foreign/
-<label id="sec:Foreign">
-<p>
-
-This module provides the <tt/ForeignObj/ type, which is a Haskell
-reference to an object in the outside world. Foreign objects are
-boxed versions of <tt/Addr#/, the only reason for their existence is
-so that they can be used with finalisers (see Section <ref
-id="foreign-finalisers" name="Finalisation for foreign objects">).
-
-<tscreen><verb>
-module Foreign where
-data ForeignObj -- abstract, instance of: Eq
-
-makeForeignObj :: Addr{-object-} -> Addr{-finaliser-} -> IO ForeignObj
-writeForeignObj :: ForeignObj -> Addr{-new value-} -> IO ()
-mkForeignObj :: Addr -> IO ForeignObj
-addForeignFinalizer :: ForeignObj -> IO () -> IO ()
-</verb> </tscreen>
-
-In addition to the above, the following operations for indexing via
-a <tt/ForeignObj/ are also, mirrored on the same operations provided
-over <tt/Addr/s:
-
-<tscreen><verb>
-indexCharOffForeignObj :: ForeignObj -> Int -> Char
-indexIntOffForeignObj :: ForeignObj -> Int -> Int
-indexWordOffForeignObj :: ForeignObj -> Int -> Word
-indexAddrOffForeignObj :: ForeignObj -> Int -> Addr
-indexFloatOffForeignObj :: ForeignObj -> Int -> Float
-indexDoubleOffForeignObj :: ForeignObj -> Int -> Double
-indexWord8OffForeignObj :: ForeignObj -> Int -> Word8
-indexWord16OffForeignObj :: ForeignObj -> Int -> Word16
-indexWord32OffForeignObj :: ForeignObj -> Int -> Word32
-indexWord64OffForeignObj :: ForeignObj -> Int -> Word64
-
-indexInt8OffForeignObj :: ForeignObj -> Int -> Int8
-indexInt16OffForeignObj :: ForeignObj -> Int -> Int16
-indexInt32OffForeignObj :: ForeignObj -> Int -> Int32
-indexInt64OffForeignObj :: ForeignObj -> Int -> Int64
-
--- read value out of mutable memory
-readCharOffForeignObj :: ForeignObj -> Int -> IO Char
-readIntOffForeignObj :: ForeignObj -> Int -> IO Int
-readWordOffForeignObj :: ForeignObj -> Int -> IO Word
-readAddrOffForeignObj :: ForeignObj -> Int -> IO Addr
-readFloatOffForeignObj :: ForeignObj -> Int -> IO Float
-readDoubleOffForeignObj :: ForeignObj -> Int -> IO Double
-readWord8OffForeignObj :: ForeignObj -> Int -> IO Word8
-readWord16OffForeignObj :: ForeignObj -> Int -> IO Word16
-readWord32OffForeignObj :: ForeignObj -> Int -> IO Word32
-readWord64OffForeignObj :: ForeignObj -> Int -> IO Word64
-readInt8OffForeignObj :: ForeignObj -> Int -> IO Int8
-readInt16OffForeignObj :: ForeignObj -> Int -> IO Int16
-readInt32OffForeignObj :: ForeignObj -> Int -> IO Int32
-readInt64OffForeignObj :: ForeignObj -> Int -> IO Int64
-
-writeCharOffForeignObj :: ForeignObj -> Int -> Char -> IO ()
-writeIntOffForeignObj :: ForeignObj -> Int -> Int -> IO ()
-writeWordOffForeignObj :: ForeignObj -> Int -> Word -> IO ()
-writeAddrOffForeignObj :: ForeignObj -> Int -> Addr -> IO ()
-writeFloatOffForeignObj :: ForeignObj -> Int -> Float -> IO ()
-writeDoubleOffForeignObj :: ForeignObj -> Int -> Double -> IO ()
-writeWord8OffForeignObj :: ForeignObj -> Int -> Word8 -> IO ()
-writeWord16OffForeignObj :: ForeignObj -> Int -> Word16 -> IO ()
-writeWord32OffForeignObj :: ForeignObj -> Int -> Word32 -> IO ()
-writeWord64OffForeignObj :: ForeignObj -> Int -> Word64 -> IO ()
-writeInt8OffForeignObj :: ForeignObj -> Int -> Int8 -> IO ()
-writeInt16OffForeignObj :: ForeignObj -> Int -> Int16 -> IO ()
-writeInt32OffForeignObj :: ForeignObj -> Int -> Int32 -> IO ()
-writeInt64OffForeignObj :: ForeignObj -> Int -> Int64 -> IO ()
-</verb></tscreen>
-
diff --git a/ghc/docs/libraries/GetOpt.sgml b/ghc/docs/libraries/GetOpt.sgml
deleted file mode 100644
index 2aed0d895789..000000000000
--- a/ghc/docs/libraries/GetOpt.sgml
+++ /dev/null
@@ -1,96 +0,0 @@
-<sect> <idx/GetOpt/
-<label id="sec:GetOpt">
-<p>
-
-The <tt/GetOpt/ library contains Sven Panne's Haskell implementation
-of <tt/getopt/, providing features nigh-on identical to GNU <tt/getopt/:
-
-<tscreen><verb>
-module GetOpt where
-
--- representing a single option:
-data OptDescr a
- = Option [Char] -- list of short option characters
- [String] -- list of long option strings (without "--")
- (ArgDescr a) -- argument descriptor
- String -- explanation of option for user
-
--- argument option:
-data ArgDescr a
- = NoArg a -- no argument expected
- | ReqArg (String -> a) String -- option requires argument
- | OptArg (Maybe String -> a) String -- optional argument
-
-usageInfo :: String -- header
- -> [OptDescr a] -- options recognised
- -> String -- nicely formatted decription of options
-
-getOpt :: ArgOrder a -- non-option handling
- -> [OptDescr a] -- options recognised
- -> [String] -- the command-line
- -> ( [a] -- options
- , [String] -- non-options
- ,[String] -- error messages
- )
-
-data ArgOrder a
- = RequireOrder
- | Permute
- | ReturnInOrder (String -> a)
-
-</verb></tscreen>
-
-<itemize>
-<item> The command-line options recognised is described by a list of
-<tt/OptDescr/ values. The <tt/OptDescr/ describes the long and short
-strings that recognise the option, together with a help string and
-info on whether the option takes extra arguments, if any.
-<item>
-From a list of option values, <tt/usageInfo/ returns a nicely
-formatted string that enumerates the different options supported
-together with a short message about what
-<item>
-To decode a command-line with respect to a list of options,
-<tt/getOpt/ is used. It processes the command-line, and returns
-the list of values that matched (and those that didn't). The first
-argument to <tt/getOpt/ controls whether the user is to give the
-options in any old order or not.
-</itemize>
-
-To hopefully illuminate the role of the different <tt/GetOpt/ data
-structures, here's the command-line options for a (very simple)
-compiler:
-
-<tscreen><verb>
-module Opts where
-
-import GetOpt
-import Maybe ( fromMaybe )
-
-data Flag
- = Verbose | Version
- | Input String | Output String | LibDir String
- deriving Show
-
-options :: [OptDescr Flag]
-options =
- [ Option ['v'] ["verbose"] (NoArg Verbose) "chatty output on stderr"
- , Option ['V','?'] ["version"] (NoArg Version) "show version number"
- , Option ['o'] ["output"] (OptArg outp "FILE") "output FILE"
- , Option ['c'] [] (OptArg inp "FILE") "input FILE"
- , Option ['L'] ["libdir"] (ReqArg LibDir "DIR") "library directory"
- ]
-
-inp,outp :: Maybe String -> Flag
-outp = Output . fromMaybe "stdout"
-inp = Input . fromMaybe "stdout"
-
-compilerOpts :: [String] -> IO ([Flag], [String])
-compilerOpts argv =
- case (getOpt Permute options argv) of
- (o,n,[] ) -> return (o,n)
- (_,_,errs) -> fail (userError (concat errs ++ usageInfo header options))
- where header = "Usage: ic [OPTION...] files..."
-</verb></tscreen>
-
-
diff --git a/ghc/docs/libraries/GlaExts.sgml b/ghc/docs/libraries/GlaExts.sgml
deleted file mode 100644
index cdd2b7c9eaaa..000000000000
--- a/ghc/docs/libraries/GlaExts.sgml
+++ /dev/null
@@ -1,31 +0,0 @@
-<!--
- <sect> <idx/GlaExts/ <p>
-
- This library provides a convenient bundle of most of the extensions
- available in GHC and Hugs. This module is generally more stable than
- the other modules of non-standard extensions so you might choose to
- import them from here rather than going straight to the horses mouth.
-
- <tscreen><verb>
- module GlaExts( module GlaExts, module IOExts, module ST, module Addr ) where
- import IOExts
- import ST
- import Addr
- trace :: String -> a -> a
- performGC :: IO ()
- </verb></tscreen>
-
- The GHC version also provides the types <tt/RealWorld/,
- <tt/ByteArray/, <tt/Lift/ and operations on these types. It also
- provides the unboxed views of the types
- <tt/Int/,
- <tt/Addr/,
- <tt/Word/,
- <tt/Float/,
- <tt/Double/,
- <tt/Integer/ and
- <tt/Char/
- and a number of ``primitive operations'' (<tt/+&num/,
- <tt/plusFloat&num/, etc.).
-
- -->
diff --git a/ghc/docs/libraries/IOExts.sgml b/ghc/docs/libraries/IOExts.sgml
deleted file mode 100644
index 60387068943e..000000000000
--- a/ghc/docs/libraries/IOExts.sgml
+++ /dev/null
@@ -1,119 +0,0 @@
-<sect> <idx/IOExts/
-<label id="sec:IOExts">
-<p>
-
-(Documetation for this library is sadly inadequate.)
-
-This library provides the following extensions to the IO monad:
-<itemize>
-<item>
-The operations <tt/fixIO/, <tt/unsafePerformIO/ and <tt/unsafeInterleaveIO/
-described in <cite id="ImperativeFP">.
-<p>
-Everyone knows that if the I/O computation wrapped in <tt/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 <tt/unsafePerformIO/)
-is indeterminate. It is less well known that <tt/unsafePerformIO/ is not type safe.
-For example:
-<tscreen><verb>
- test :: IORef [a]
- test = unsafePerformIO $ newIORef []
-
- main = do
- writeIORef test [42]
- bang <- readIORef test
- print (bang :: [Char])
-</verb></tscreen>
-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
-<tt/unsafePerformIO/. Indeed, it is possible to write
-<tt>coerce :: a -> b</tt> with the help of <tt/unsafePerformIO/.
-So be careful!
-
-<item>
-References (aka mutable variables) and mutable arrays (but no form of
-mutable byte arrays)
-
-<item>
-<tt/openFileEx/ extends the standard <tt/openFile/ action with support
-for opening binary files.
-
-<item>
-<tt/performGC/ triggers an immediate garbage collection
-
-<item>
-When called, <tt/trace/ prints the string in its first argument to
-standard error, before returning the second argument as its result.
-The <tt/trace/ function is not referentially transparent, and should
-only be used for debugging, or for monitoring execution. Some
-implementations of <tt/trace/ may decorate the string that's output
-to indicate that you're tracing.
-
-<!--
- You should also be warned that, unless you understand some of the
- details about the way that Haskell programs are executed, results
- obtained using <tt/trace/ can be rather confusing. For example, the
- messages may not appear in the order that you expect. Even ignoring the
- output that they produce, adding calls to <tt/trace/ can change the
- semantics of your program. Consider this a warning!
- -->
-
-<item>
-<tt/unsafePtrEq/ compares two values for pointer equality without
-evaluating them. The results are not referentially transparent and
-may vary significantly from one compiler to another or in the face of
-semantics-preserving program changes. However, pointer equality is useful
-in creating a number of referentially transparent constructs such as this
-simplified memoisation function:
-
-<tscreen><verb>
-> cache :: (a -> b) -> (a -> b)
-> cache f = \x -> unsafePerformIO (check x)
-> where
-> ref = unsafePerformIO (newIORef (error "cache", error "cache"))
-> check x = readIORef ref >>= \ (x',a) ->
-> if x `unsafePtrEq` x' then
-> return a
-> else
-> let a = f x in
-> writeIORef ref (x, a) >>
-> return a
-</verb></tscreen>
-
-</itemize>
-
-<tscreen><verb>
-module IOExts where
-
-fixIO :: (a -> IO a) -> IO a
-unsafePerformIO :: IO a -> a
-unsafeInterleaveIO :: IO a -> IO a
-
-data IORef a -- mutable variables containing values of type a
-newIORef :: a -> IO (IORef a)
-readIORef :: IORef a -> IO a
-writeIORef :: IORef a -> a -> IO ()
-instance Eq (IORef a)
-
-data IOArray ix elt -- mutable arrays indexed by values of type ix
- -- containing values of type a.
-newIOArray :: Ix ix => (ix,ix) -> elt -> IO (IOArray ix elt)
-boundsIOArray :: Ix ix => IOArray ix elt -> (ix, ix)
-readIOArray :: Ix ix => IOArray ix elt -> ix -> IO elt
-writeIOArray :: Ix ix => IOArray ix elt -> ix -> elt -> IO ()
-freezeIOArray :: Ix ix => IOArray ix elt -> IO (Array ix elt)
-instance Eq (IOArray ix elt)
-
-openFileEx :: FilePath -> IOModeEx -> IO Handle
-data IOModeEx = BinaryMode IO.IOMode | TextMode IO.IOMode
-instance Eq IOModeEx
-instance Read IOModeEx
-instance Show IOModeEx
-
-performGC :: IO ()
-trace :: String -> a -> a
-unsafePtrEq :: a -> a -> Bool
-
-</verb></tscreen>
-
diff --git a/ghc/docs/libraries/Int.sgml b/ghc/docs/libraries/Int.sgml
deleted file mode 100644
index 574f555c2cae..000000000000
--- a/ghc/docs/libraries/Int.sgml
+++ /dev/null
@@ -1,112 +0,0 @@
-<sect> <idx/Int/
-<label id="sec:Int">
-<p>
-
-This interface provides a collection of sized, signed integers. The
-types supported are as follows:
-
-<tabular ca="ll">
-type | number of bits @
-<!-- <hline> -->
-Int8 | 8 @
-Int16 | 16 @
-Int32 | 32 @
-Int64 | 64 @
-<!-- <hline> -->
-</tabular>
-
-For each type <it/I/ above, we provide the following instances.
-
-<tscreen><verb>
-data I -- Signed Ints
-iToInt :: I -> Int -- not provided for Int64
-intToI :: Int -> I -- not provided for Int64
-instance Eq I
-instance Ord I
-instance Show I
-instance Read I
-instance Bounded I
-instance Num I
-instance Real I
-instance Integral I
-instance Enum I
-instance Ix I
-instance Bits I
-</verb></tscreen>
-
-Plus the coercion functions
-
-<tscreen><verb>
-int8ToInt16 :: Int8 -> Int16
-int8ToInt32 :: Int8 -> Int32
-int8ToInt64 :: Int8 -> Int64
-
-int16ToInt8 :: Int16 -> Int8
-int16ToInt32 :: Int16 -> Int32
-int16ToInt64 :: Int16 -> Int64
-
-int32ToInt8 :: Int32 -> Int8
-int32ToInt16 :: Int32 -> Int16
-int32ToInt64 :: Int32 -> Int64
-
-int64ToInt8 :: Int64 -> Int8
-int64ToInt16 :: Int64 -> Int16
-int64ToInt32 :: Int64 -> Int32
-
-int8ToInt :: Int8 -> Int
-int16ToInt :: Int16 -> Int
-int32ToInt :: Int32 -> Int
-int64ToInt :: Int64 -> Int
-
-intToInt8 :: Int -> Int8
-intToInt16 :: Int -> Int16
-intToInt32 :: Int -> Int32
-intToInt64 :: Int -> Int64
-
-integerToInt8 :: Integer -> Int8
-integerToInt16 :: Integer -> Int16
-integerToInt32 :: Integer -> Int32
-integerToInt64 :: Integer -> Int64
-
-int64ToInteger :: Int64 -> Integer
-int32ToInteger :: Int32 -> Integer
-int16ToInteger :: Int16 -> Integer
-int8ToInteger :: Int8 -> Integer
-
-</verb></tscreen>
-
-<itemize>
-<item>
-The rules that hold for <tt/Enum/ instances over a bounded type
-such as <tt/Int/ (see the section of the Haskell report dealing
-with arithmetic sequences) also hold for the <tt/Enum/ instances
-over the various <tt/Int/ types defined here.
-
-<item>
-Right and left shifts by amounts greater than or equal to the width of
-the type result in either zero or -1, depending on the sign of the
-value being shifted. This is contrary to the behaviour in C, which is
-undefined; a common interpretation is to truncate the shift count to
-the width of the type, for example <tt>1 << 32 == 1</tt> in some
-C implementations.
-
-<item>
-Hugs does not provide <tt/Int64/ at the moment.
-
-</itemize>
-
-The <tt/Int/ module also exports the overloaded operations for
-converting to and from Haskell <tt/Int/s:
-
-<tscreen><verb>
-toInt :: (Integral a) => a -> Int
-fromInt :: (Num a) => Int -> a
-</verb></tscreen>
-
-Portability note: both Hugs98 and all releases of GHC prior to
-ghc-4.05 also exports these two via the Prelude. So, to have code
-that uses <tt>toInt</tt> and <tt>fromInt</tt> be maximally portable,
-make sure you add an import on <tt>Int</tt> (even if the version
-of Hugs or GHC you're currently using may not export these two
-from there.)
-
diff --git a/ghc/docs/libraries/Makefile b/ghc/docs/libraries/Makefile
deleted file mode 100644
index 070533962338..000000000000
--- a/ghc/docs/libraries/Makefile
+++ /dev/null
@@ -1,9 +0,0 @@
-#-----------------------------------------------------------------------------
-# $Id: Makefile,v 1.2 1998/12/02 13:20:22 simonm Exp $
-
-TOP=../..
-include $(TOP)/mk/boilerplate.mk
-
-SGML_DOC = libs
-
-include $(TOP)/mk/target.mk
diff --git a/ghc/docs/libraries/NumExts.sgml b/ghc/docs/libraries/NumExts.sgml
deleted file mode 100644
index 29ed938f58b5..000000000000
--- a/ghc/docs/libraries/NumExts.sgml
+++ /dev/null
@@ -1,72 +0,0 @@
-<sect> <idx/NumExts/
-<label id="sec:NumExts">
-<p>
-
-The <tt/NumExts/ interface collect together various numeric
-operations that have proven to be commonly useful
-
-<tscreen> <verb>
--- Going between Doubles and Floats:
-doubleToFloat :: Double -> Float
-floatToDouble :: Float -> Double
-
-showHex :: Integral a => a -> ShowS
-showOct :: Integral a => a -> ShowS
-showBin :: Integral a => a -> ShowS
-
-showIntAtBase :: Integral a
- => a -- base
- -> (a -> Char) -- digit to char
- -> a -- number to show.
- -> ShowS
-
-showListWith :: (a -> ShowS) -> [a] -> ShowS
-</verb> </tscreen>
-
-Notes:
-<itemize>
-<item>
- If <tt/doubleToFloat/ is applied to a <tt/Double/ that is within
- the representable range for <tt/Float/, the result may be the next
- higher or lower representable <tt/Float/ value. If the <tt/Double/
- is out of range, the result is undefined.
-<item>
- No loss of precision occurs in the other direction with
- <tt/floatToDouble/, the floating value remains unchanged.
-<item>
- <tt/showOct/, <tt/showHex/ and <tt/showBin/ will prefix <tt/0o/,
- <tt/0x/ and <tt/0b/, respectively. Like <tt/Numeric.showInt/,
- these show functions work on positive numbers only.
-<item>
- <tt/showIntAtBase/ is the more general function for converting
- a number at some base into a series of characters. The above
- <tt/show*/ functions use it, for instance, here's how <tt/showHex/
- could be defined
-
-<tscreen><verb>
-showHex :: Integral a => a -> ShowS
-showHex n r =
- showString "0x" $
- showIntAtBase 16 (toChrHex) n r
- where
- toChrHex d
- | d < 10 = chr (ord '0' + fromIntegral d)
- | otherwise = chr (ord 'a' + fromIntegral (d - 10))
-</verb></tscreen>
-
-<item>
- <tt/showListWith/ is strictly speaking not a '<tt/NumExts/' kind
- of function, but it's sometimes useful in conjunction with the
- other <tt/show*/ functions that <tt/NumExts/ exports. It is
- the non-overloaded version of <tt/showList/, allowing you to
- supply the <tt/shows/ function to use per list element. For
- instance,
-
-<tscreen><code>
- putStrLn (NumExts.showListWith NumExts.showHex [0..16])
-</code></tscreen>
-
- will print out the elements of <tt/[1..16]/ in hexidecimal form.
-
-
-</itemize>
diff --git a/ghc/docs/libraries/Pretty.sgml b/ghc/docs/libraries/Pretty.sgml
deleted file mode 100644
index aa711103a1d7..000000000000
--- a/ghc/docs/libraries/Pretty.sgml
+++ /dev/null
@@ -1,59 +0,0 @@
-<sect> <idx/Pretty/
-<label id="sec:Pretty">
-<p>
-
-This library contains Simon Peyton Jones' implementation of John
-Hughes's pretty printer combinators.
-
-<tscreen><verb>
-module Pretty where
-infixl 6 <>
-infixl 6 <+>
-infixl 5 $$, $+$
-data Doc -- the Document datatype
-
--- The primitive Doc values
-empty :: Doc
-text :: String -> Doc
-char :: Char -> Doc
-int :: Int -> Doc
-integer :: Integer -> Doc
-float :: Float -> Doc
-double :: Double -> Doc
-rational :: Rational -> Doc
-semi, comma, colon, space, equals :: Doc
-lparen, rparen, lbrack, rbrack, lbrace, rbrace :: Doc
-parens, brackets, braces :: Doc -> Doc
-quotes, doubleQuotes :: Doc -> Doc
-
--- Combining Doc values
-(<>) :: Doc -> Doc -> Doc -- Beside
-hcat :: [Doc] -> Doc -- List version of <>
-(<+>) :: Doc -> Doc -> Doc -- Beside, separated by space
-hsep :: [Doc] -> Doc -- List version of <+>
-($$) :: Doc -> Doc -> Doc -- Above; if there is no
- -- overlap it "dovetails" the two
-vcat :: [Doc] -> Doc -- List version of $$
-cat :: [Doc] -> Doc -- Either hcat or vcat
-sep :: [Doc] -> Doc -- Either hsep or vcat
-fcat :: [Doc] -> Doc -- ``Paragraph fill'' version of cat
-fsep :: [Doc] -> Doc -- ``Paragraph fill'' version of sep
-nest :: Int -> Doc -> Doc -- Nested
-hang :: Doc -> Int -> Doc -> Doc
-punctuate :: Doc -> [Doc] -> [Doc]
--- punctuate p [d1, ... dn] = [d1 <> p, d2 <> p, ... dn-1 <> p, dn]
-
--- Displaying Doc values
-instance Show Doc
-render :: Doc -> String -- Uses default style
-renderStyle :: Style -> Doc -> String
-data Style = Style { lineLength :: Int, -- In chars
- ribbonsPerLine :: Float, -- Ratio of ribbon length
- -- to line length
- mode :: Mode
- }
-data Mode = PageMode -- Normal
- | ZigZagMode -- With zig-zag cuts
- | LeftMode -- No indentation, infinitely long lines
- | OneLineMode -- All on one line
-</verb></tscreen>
diff --git a/ghc/docs/libraries/ST.sgml b/ghc/docs/libraries/ST.sgml
deleted file mode 100644
index 3be2067d4770..000000000000
--- a/ghc/docs/libraries/ST.sgml
+++ /dev/null
@@ -1,82 +0,0 @@
-<sect> <idx/ST/
-<label id="sec:ST">
-<p>
-
-This library provides support for <em/strict/ state threads, as
-described in the PLDI '94 paper by John Launchbury and Simon Peyton
-Jones <cite id="LazyStateThreads">. In addition to the monad <tt/ST/,
-it also provides mutable variables <tt/STRef/ and mutable arrays
-<tt/STArray/.
-
-<tscreen><verb>
-module ST( module ST, module Monad ) where
-import Monad
-
-data ST s a -- abstract type
-runST :: forall a. (forall s. ST s a) -> a
-fixST :: (a -> ST s a) -> ST s a
-unsafeInterleaveST :: ST s a -> ST s a
-instance Functor (ST s)
-instance Monad (ST s)
-
-data STRef s a -- mutable variables in state thread s
- -- containing values of type a.
-newSTRef :: a -> ST s (STRef s a)
-readSTRef :: STRef s a -> ST s a
-writeSTRef :: STRef s a -> a -> ST s ()
-instance Eq (STRef s a)
-
-data STArray s ix elt -- mutable arrays in state thread s
- -- indexed by values of type ix
- -- containing values of type a.
-newSTArray :: Ix ix => (ix,ix) -> elt -> ST s (STArray s ix elt)
-boundsSTArray :: Ix ix => STArray s ix elt -> (ix, ix)
-readSTArray :: Ix ix => STArray s ix elt -> ix -> ST s elt
-writeSTArray :: Ix ix => STArray s ix elt -> ix -> elt -> ST s ()
-thawSTArray :: Ix ix => Array ix elt -> ST s (STArray s ix elt)
-freezeSTArray :: Ix ix => STArray s ix elt -> ST s (Array ix elt)
-unsafeFreezeSTArray :: Ix ix => STArray s ix elt -> ST s (Array ix elt)
-instance Eq (STArray s ix elt)
-
-unsafeIOToST :: IO a -> ST s a
-stToIO :: ST s a -> IO a
-</verb></tscreen>
-
-Notes:
-<itemize>
-
-<item>
-GHC also supports ByteArrays --- these aren't supported by Hugs yet.
-
-<item>
-The operations <tt/freezeSTArray/ and <tt/thawSTArray/ convert mutable
-arrays to and from immutable arrays. Semantically, they are identical
-to copying the array and they are usually implemented that way. The
-operation <tt/unsafeFreezeSTArray/ is a faster version of
-<tt/freezeSTArray/ which omits the copying step. It's a safe substitute for
-<tt/freezeSTArray/ if you don't modify the mutable array after freezing it.
-
-<!--
- <item>
- Note that it is possible to install Hugs 1.4 without support for lazy
- state threads, and hence the primitives described here may not be
- available in all implementations. Also, in contrast with the
- implementation of lazy state threads in previous releases of Hugs and
- Gofer, there is no direct relationship between the
- <tt/<idx/ST monad// and the <tt/<idx/IO monad//.
- -->
-
-<item>
-Hugs provides <tt/thenLazyST/ and <tt/thenStrictST/ so that you can
-import <tt/LazyST/ (say) and still use the strict instance in those
-places where it matters. GHC implements LazyST and ST using different
-types, so this isn't possible.
-</item>
-
-<item>
-Operations for coercing an <tt/ST/ action into an <tt/IO/ one, and
-vice versa are also provided. Notice that coercing an <tt/IO/ action
-into an <tt/ST/ action is 'lossy', since any exception raised within the
-<tt/IO/ action will not be caught within the <tt/ST/ monad, as it
-doesn't support (monadic) exceptions.
-</itemize>
diff --git a/ghc/docs/libraries/Stable.sgml b/ghc/docs/libraries/Stable.sgml
deleted file mode 100644
index 2d1dc3674d57..000000000000
--- a/ghc/docs/libraries/Stable.sgml
+++ /dev/null
@@ -1,126 +0,0 @@
-<sect> <idx/Stable/
-<label id="sec:Stable">
-<p>
-
-This module provides two kinds of stable references to Haskell
-objects, stable names and stable pointers.
-
-<sect1> <idx/Stable Pointers/
-<label id="sec:stable-pointers">
-<p>
-
-A <em/stable pointer/ is a reference to a Haskell expression that
-can be passed to foreign functions via the foreign function
-interface.
-
-Normally a Haskell object will move around from time to time, because
-of garbage collection, hence we can't just pass the address of an
-object to a foreign function and expect it to remain valid. Stable
-pointers provide a level of indirection so that the foreign code can
-get the "real address" of the Haskell object by calling
-<tt/deRefStablePtr/ on the stable pointer object it has.
-
-The Haskell interface provided by the <tt/Stable/ module is as follows:
-
-<tscreen><verb>
-data StablePtr a -- abstract, instance of: Eq.
-makeStablePtr :: a -> IO (StablePtr a)
-deRefStablePtr :: StablePtr a -> IO a
-freeStablePtr :: StablePtr a -> IO ()
-</verb></tscreen>
-
-Care must be taken to free stable pointers that are no longer required
-using the <tt/freeStablePtr/ function, otherwise two bad things can
-happen:
-
-<itemize>
-<item> The object referenced by the stable pointer will be retained in
-the heap.
-<item> The runtime system's internal stable pointer table will grow,
-which imposes an overhead on garbage collection.
-</itemize>
-
-Notes:
-
-<itemize>
-<item> If <tt/sp1 :: StablePtr/ and <tt/sp2 :: StablePtr/ and <tt/sp1
-== sp2/ then <tt/sp1/ and <tt/sp2/ are either the same stable pointer,
-or they were created by calls to <tt/makeStablePtr/ on the same
-object. Another way to say this is "every time you call
-<tt/makeStablePtr/ on an object you get back the same stable pointer".
-<item> The reverse is not necessarily true: if two stable pointers are
-not equal, it doesn't mean that they don't refer to the same Haskell
-object (although they probably don't). <item> Calling
-<tt/deRefStablePtr/ on a stable pointer which has previously been
-freed results in undefined behaviour.
-</itemize>
-
-The C interface (which is brought into scope by <tt/#include
-<Stable.h>/) is as follows:
-
-<tscreen><verb>
-typedef StablePtr /* abstract, probably an unsigned long */
-extern StgPtr deRefStablePtr(StgStablePtr stable_ptr);
-static void freeStablePtr(StgStablePtr sp);
-static StgStablePtr splitStablePtr(StgStablePtr sp);
-</verb></tscreen>
-
-The functions <tt/deRefStablePtr/ and <tt/freeStablePtr/ are
-equivalent to the Haskell functions of the same name above.
-
-The function <tt/splitStablePtr/ allows a stable pointer to be
-duplicated without making a new one with <tt/makeStablePtr/. The
-stable pointer won't be removed from the runtime system's internal
-table until <tt/freeStablePtr/ is called on both pointers.
-
-<sect1>Stable Names
-<label id="sec:stable-pointers">
-<p>
-
-A haskell object can be given a <em/stable name/ by calling
-<tt/makeStableName/ on it. Stable names solve the following problem:
-suppose you want to build a hash table with Haskell objects as keys,
-but you want to use pointer equality for comparison; maybe because the
-keys are large and hashing would be slow, or perhaps because the keys
-are infinite in size. We can't build a hash table using the address
-of the object as the key, because objects get moved around by the
-garbage collector, meaning a re-hash would be necessary after every
-garbage collection.
-
-Enter stable names. A stable name is an abstract entity that supports
-equality and hashing, with the following interface:
-
-<tscreen><verb>
-data StableName a -- abstract, instance Eq.
-makeStableName :: a -> IO (StableName a)
-hashStableName :: StableName a -> Int
-</verb></tscreen>
-
-All these operations run in constant time.
-
-Stable names have the following properties:
-
-<enum>
-<item> If <tt/sn1 :: StablePtr/ and <tt/sn2 :: StablePtr/ and <tt/sn1
-== sn2/ then <tt/sn1/ and <tt/sn2/ are either the same stable name,
-or they were created by calls to <tt/makeStableName/ on the same
-object.
-<item> The reverse is not necessarily true: if two stable names are
-not equal, it doesn't mean that they don't refer to the same Haskell
-object (although they probably don't).
-<item> There is no <tt/freeStableName/ operation. Stable names are
-reclaimed by the runtime system when they are no longer needed.
-<item> There is no <tt/deRefStableName/ operation. You can't get back
-from a stable name to the original Haskell object. The reason for
-this is that the existence of a stable name for an object doesn't
-guarantee the existence of the object itself; it can still be garbage
-collected.
-<item> There is a <tt/hashStableName/ operation, which converts a
-stable name to an <tt/Int/. The <tt/Int/ returned is not necessarily
-unique (that is, it doesn't satisfy property (1) above), but it can be
-used for building hash tables of stable names.
-</enum>
-
-Properties (1) and (2) are similar to stable pointers, but the key
-differences are that you can't get back to the original object from a
-stable name, and you can convert one to an <tt/Int/ for hashing.
diff --git a/ghc/docs/libraries/Weak.sgml b/ghc/docs/libraries/Weak.sgml
deleted file mode 100644
index 16cb034b081a..000000000000
--- a/ghc/docs/libraries/Weak.sgml
+++ /dev/null
@@ -1,278 +0,0 @@
-<sect> <idx/Weak/
-<label id="sec:Weak">
-<p>
-
-The <tt/Weak/ library provides a "weak pointer" abstraction, giving
-the user some control over the garbage collection of specified
-objects, and allowing objects to be "finalized" with an arbitrary
-Haskell IO computation when they die.
-
-Weak pointers partially replace the old foreign object interface, as
-we will explain later.
-
-<sect1>Module Signature
-<p>
-
-<tscreen><verb>
-module Weak (
- Weak, -- abstract
- -- instance Eq (Weak v)
-
- mkWeak, -- :: k -> v -> Maybe (IO ()) -> IO (Weak v)
- deRefWeak, -- :: Weak v -> IO (Maybe v)
- finalize, -- :: Weak v -> IO ()
-
- -- Not yet implemented
- -- replaceFinalizer -- :: Weak v -> IO () -> IO ()
-
- mkWeakPtr, -- :: k -> Maybe (IO ()) -> IO (Weak k)
- mkWeakPair, -- :: k -> v -> Maybe (IO ()) -> IO (Weak (k,v))
- addFinalizer, -- :: k -> IO () -> IO ()
- addForeignFinalizer -- :: ForeignObj -> IO () -> IO ()
- ) where
-</verb></tscreen>
-
-<sect1>Weak pointers
-<p>
-
-In general terms, a weak pointer is a reference to an object that is
-not followed by the garbage collector --- that is, the existence of a
-weak pointer to an object has no effect on the lifetime of that
-object. A weak pointer can be de-referenced to find out
-whether the object it refers to is still alive or not, and if so
-to return the object itself.
-
-Weak pointers are particularly useful for caches and memo tables.
-To build a memo table, you build a data structure
-mapping from the function argument (the key) to its result (the
-value). When you apply the function to a new argument you first
-check whether the key/value pair is already in the memo table.
-The key point is that the memo table itself should not keep the
-key and value alive. So the table should contain a weak pointer
-to the key, not an ordinary pointer. The pointer to the value must
-not be weak, because the only reference to the value might indeed be
-from the memo table.
-
-So it looks as if the memo table will keep all its values
-alive for ever. One way to solve this is to purge the table
-occasionally, by deleting entries whose keys have died.
-
-The weak pointers in this library
-support another approach, called <em/finalization/.
-When the key referred to by a weak pointer dies, the storage manager
-arranges to run a programmer-specified finalizer. In the case of memo
-tables, for example, the finalizer could remove the key/value pair
-from the memo table.
-
-Another difficulty with the memo table is that the value of a
-key/value pair might itself contain a pointer to the key.
-So the memo table keeps the value alive, which keeps the key alive,
-even though there may be no other references to the key so both should
-die. The weak pointers in this library provide a slight
-generalisation of the basic weak-pointer idea, in which each
-weak pointer actually contains both a key and a value.
-We describe this in more detail below.
-
-<sect1>The simple interface
-<p>
-
-<tscreen><verb>
- mkWeakPtr :: a -> Maybe (IO ()) -> IO (Weak a)
- deRefWeak :: Weak a -> IO (Maybe a)
- addFinalizer :: a -> IO () -> IO ()
-</verb></tscreen>
-
-<tt/mkWeakPtr/ takes a value of any type <tt/a/, and maybe a finalizer
-of type <tt/IO ()/, and returns a weak pointer object referring to the
-value, of type <tt/Weak a/. It is in the <tt/IO/ monad because it has
-the side effect of arranging that the finalizer (if there is one) will
-be run when the object dies. In what follows, a ``weak pointer
-object'', or ``weak pointer'' for short, means precisely ``a Haskell
-value of type <tt/Weak t/'' for some type <tt/t/. A weak pointer
-(object) is a first-class Haskell value; it can be passed to
-functions, stored in data structures, and so on.
-
-<tt/deRefWeak/ dereferences a weak pointer, returning <tt/Just v/ if
-the value is still alive. If the key has already died, then
-<tt/deRefWeak/ returns <tt/Nothing/; that's why it's in the <tt/IO/
-monad - the return value of <tt/deRefWeak/ depends on when the garbage
-collector runs.
-
-<tt/addFinalizer/ is just another name for <tt/mkWeakPtr/ except that
-it throws the weak pointer itself away. (The runtime system will
-remember that the weak pointer and hence the finalizer exists even if
-the program has forgotten it.)
-
-<tscreen><verb>
- addFinalizer :: a -> IO () -> IO ()
- addFinalizer v f = do { mkWeakPtr v f; return () }
-</verb></tscreen>
-
-The effect of <tt/addFinalizer/ is simply that the finalizer runs when
-the referenced object dies.
-
-The following properties hold:
-
-<itemize>
-<item> <tt/deRefWeak/ returns the original object until
-that object is considered dead; it returns <tt/Nothing/
-subsequently.
-<item>
-Every finalizer will eventually be run, exactly once, either
-soon after the object dies, or at the end of the program.
-There is no requirement for the programmer to hold onto the
-weak pointer itself; finalization is completely unaffected by
-whether the weak pointer itself is alive.
-<item>
-There may be multiple weak pointers to a single object.
-In this case, the finalizers for each of these weak pointers will
-all be run in some arbitrary order, or perhaps concurrently,
-when the object dies. If the programmer specifies a finalizer that
-assumes it has the only reference to an object
-(for example, a file that it wishes to close), then the programmer
-must ensure that there is only one such finalizer.
-<item>
-The storage manager attempts to run the finalizer(s) for an
-object soon after the object dies, but promptness is not guaranteed.
-(What is guaranteed is that the finalizer will
-eventually run, exactly once.)
-<item>
-At the moment when a finalizer is run, a call to <tt/deRefWeak/
-will return <tt/Nothing/.
-<item>
-A finalizer may contain a pointer to the object, but that pointer
-will not keep the object alive. For example:
-<tscreen><verb>
- f :: Show a => a -> IO a
- f x = addFinalizer x (print (show x))
-</verb></tscreen>
-Here the finalizer <tt/print (show x)/ contains a reference to <tt/x/
-itself, but that does not keep <tt/x/ alive. When that is the only
-reference to <tt/x/, the finalizer is run; and the message appears
-on the screen.
-<item>
-A finalizer may even resurrect the object, by (say) storing it in
-some global data structure.
-</itemize>
-
-<sect1>The general interface
-<p>
-
-The <tt/Weak/ library offers a slight generalisation of
-the simple weak pointers described so far:
-<tscreen><verb>
- mkWeak :: k -> v -> Maybe (IO ()) -> IO (Weak v)
-</verb></tscreen>
-<tt/mkWeak/ takes a key of any type <tt/k/ and a value of any type
-<tt/v/, as well as a finalizer, and returns a weak pointer of type
-<tt/Weak v/.
-
-<tt/deRefWeak/ returns the <em/value/ only, not the key, as its
-type (given above) implies:
-<tscreen><verb>
- deRefWeak :: Weak a -> IO (Maybe a)
-</verb></tscreen>
-However, <tt/deRefWeak/ returns <tt/Nothing/ if the <em/key/, not the
-value, has died. Furthermore, references from the value to the key
-do not keep the key alive, in the same way that the finalizer does
-not keep the key alive.
-
-Simple weak pointers are readily defined in terms of these more general
-weak pointers:
-<tscreen><verb>
- mkWeakPtr :: a -> Maybe (IO ()) -> IO (Weak a)
- mkWeakPtr v f = mkWeak v v f
-</verb></tscreen>
-
-These more general weak pointers are enough to implement memo
-tables properly.
-
-A weak pointer can be finalized early, using the <tt/finalize/ operation:
-
-<tscreen><verb>
-finalize :: Weak v -> IO ()
-</verb></tscreen>
-
-<sect1> A precise semantics
-<p>
-The above informal specification is fine for simple situations,
-but matters can get complicated. In particular, it needs to
-be clear exactly when a key dies, so that any weak pointers
-that refer to it can be finalized.
-Suppose, for example, the value of one weak pointer refers
-to the key of another...does that keep the key alive?
-
-The behaviour is simply this:
-
-<itemize>
-<item> If a weak pointer (object) refers to an <em/unreachable/
-key, it may be finalized.
-<item> Finalization means (a) arrange that subsequent calls
-to <tt/deRefWeak/ return <tt/Nothing/; and (b) run the finalizer.
-</itemize>
-
-This behaviour depends on what it means for a key to be reachable.
-Informally,
-something is reachable if it can be reached by following ordinary
-pointers from the root set, but not following weak pointers.
-We define reachability more precisely as
-follows
-A heap object is reachable if:
-
-<itemize>
-<item> It is a member of the <em/root set/.
-<item> It is directly pointed to by a reachable object, other than
-a weak pointer object.
-<item> It is a weak pointer object whose key is reachable.
-<item> It is the value or finalizer of an object whose key is
-reachable.
-</itemize>
-
-The root set consists of all runnable threads, and all stable pointers
-(see Section <ref id="sec:stable-pointers" name="Stable Pointers">).
-NOTE: currently all top-level objects are considered to be reachable,
-although we hope to remove this restriction in the future. A
-<tt/Char/ or small <tt/Int/ will also be constantly reachable, since
-the garbage collector replaces heap-resident <tt/Char/s and small
-<tt/Int/s with pointers to static copies.
-
-Notice that a pointer to the key from its associated
-value or finalizer does not make the key reachable.
-However, if the key is reachable some other way, then the value
-and the finalizer are reachable, and so, therefore, are any other
-keys they refer to directly or indirectly.
-
-
-<sect1>Finalization for foreign objects
-<label id="foreign-finalizers">
-<p>
-
-A foreign object is some data that lives outside the Haskell heap, for
-example some <tt/malloc/ed data in C land. It's useful to be able to
-know when the Haskell program no longer needs the <tt/malloc/ed data,
-so it can be <tt/free/d. We can use weak pointers and finalizers for
-this, but we have to be careful: the foreign data is usually
-referenced by an address, ie. an <tt/Addr/ (see Section <ref
-name="Addr" id="sec:Addr">), and we must retain the invariant that
-<em/if the Haskell program still needs the foreign object, then it
-retains the <tt/Addr/ object in the heap/. This invariant isn't
-guaranteed to hold if we use <tt/Addr/, because an <tt/Addr/ consists
-of a box around a raw address <tt/Addr#/. If the Haskell program can
-manipulate the <tt/Addr#/ object independently of the heap-resident
-<tt/Addr/, then the foreign object could be inadvertently finalized
-early, because a weak pointer to the <tt/Addr/ would find no more
-references to its key and trigger the finalizer despite the fact that
-the program still holds the <tt/Addr#/ and intends to use it.
-
-To avoid this somewhat subtle race condition, we use another type of
-foreign address, called <tt/ForeignObj/ (see Section <ref
-id="sec:Foreign" name="Foreign">). Historical note: <tt/ForeignObj/
-is identical to the old <tt/ForeignObj/ except that it no longer
-supports finalization - that's provided by the weak
-pointer/finalization mechanism above.
-
-A <tt/ForeignObj/ is basically an address, but the <tt/ForeignObj/
-itself is a heap-resident object and can therefore be watched by weak
-pointers. A <tt/ForeignObj/ can be passed to C functions (in which
-case the C function gets a straightforward pointer), but it cannot be
-decomposed into an <tt/Addr#/.
diff --git a/ghc/docs/libraries/Word.sgml b/ghc/docs/libraries/Word.sgml
deleted file mode 100644
index bf85825f3954..000000000000
--- a/ghc/docs/libraries/Word.sgml
+++ /dev/null
@@ -1,119 +0,0 @@
-<sect> <idx/Word/
-<label id="sec:Word">
-<p>
-
-This library provides unsigned integers of various sizes.
-The types supported are as follows:
-
-<tabular ca="ll">
-<!-- ToDo: figure out why the ldoc DTD doesn't allow hline's - it looks as if -->
-<!-- it should. -->
-<!-- <hline> -->
-type | number of bits @
-Word8 | 8 @
-Word16 | 16 @
-Word32 | 32 @
-Word64 | 64 @
-<!-- <hline> -->
-</tabular>
-
-
-For each type <it/W/ above, we provide the following functions and
-instances. The type <it/I/ refers to the signed integer type of the
-same size.
-
-<tscreen><verb>
-data W -- Unsigned Ints
-instance Eq W
-instance Ord W
-instance Show W
-instance Read W
-instance Bounded W
-instance Num W
-instance Real W
-instance Integral W
-instance Enum W
-instance Ix W
-instance Bits W
-</verb></tscreen>
-Plus
-<tscreen><verb>
-word8ToWord16 :: Word8 -> Word16
-word8ToWord32 :: Word8 -> Word32
-word8ToWord64 :: Word8 -> Word64
-
-word16ToWord8 :: Word16 -> Word8
-word16ToWord32 :: Word16 -> Word32
-word16ToWord64 :: Word16 -> Word64
-
-word32ToWord8 :: Word32 -> Word8
-word32ToWord16 :: Word32 -> Word16
-word32ToWord64 :: Word32 -> Word64
-
-word64ToWord8 :: Word64 -> Word8
-word64ToWord16 :: Word64 -> Word16
-word64ToWord32 :: Word64 -> Word32
-
-word8ToInt :: Word8 -> Int
-word16ToInt :: Word16 -> Int
-word32ToInt :: Word32 -> Int
-word64ToInt :: Word64 -> Int
-
-intToWord8 :: Int -> Word8
-intToWord16 :: Int -> Word16
-intToWord32 :: Int -> Word32
-intToWord64 :: Int -> Word64
-
-word64ToInteger :: Word64 -> Integer
-integerToWord64 :: Integer -> Word64
-
-</verb></tscreen>
-
-Notes:
-<itemize>
-<item>
- All arithmetic is performed modulo 2^n
-
- One non-obvious consequence of this is that <tt/negate/
- should <em/not/ raise an error on negative arguments.
-
-<item>
-The coercion <tt/wToI/ converts an unsigned n-bit value to the
-signed n-bit value with the same representation. For example,
-<tt/word8ToInt8 0xff = -1/.
-Likewise, <tt/iToW/ converts signed n-bit values to the
-corresponding unsigned n-bit value.
-
-<item>
-Use <tt/Prelude.fromIntegral :: (Integral a, Num b) => a -> b/ to
-coerce between different sizes or to preserve sign when converting
-between values of the same size.
-
-<item>
-It would be very natural to add a type a type <tt/Natural/ providing
-an unbounded size unsigned integer --- just as <tt/Integer/ provides
-unbounded size signed integers. We do not do that yet since there is
-no demand for it. Doing so would require <tt/Bits.bitSize/ to return
-<tt/Maybe Int/.
-
-<item>
-The rules that hold for <tt/Enum/ instances over a bounded type
-such as <tt/Int/ (see the section of the Haskell report dealing
-with arithmetic sequences) also hold for the <tt/Enum/ instances
-over the various <tt/Word/ types defined here.
-
-<item>
-Right and left shifts by amounts greater than or equal to the width of
-the type result in a zero result. This is contrary to the behaviour
-in C, which is undefined; a common interpretation is to truncate
-the shift count to the width of the type, for example <tt>1 <<
-32 == 1</tt> in some C implementations.
-
-</itemize>
-
-<bf/Implementation notes:/
-
-<itemize>
-<item> Hugs only provides <tt/Eq/, <tt/Ord/, <tt/Read/ and <tt/Show/
-instances for <tt/Word64/ at the moment.
-</itemize>
diff --git a/ghc/docs/libraries/libs.sgml b/ghc/docs/libraries/libs.sgml
deleted file mode 100644
index a8fcc7b4bcc5..000000000000
--- a/ghc/docs/libraries/libs.sgml
+++ /dev/null
@@ -1,126 +0,0 @@
-<!doctype linuxdoc system [
- <!ENTITY addr SYSTEM "Addr.sgml">
- <!ENTITY bits SYSTEM "Bits.sgml">
- <!ENTITY concurrent SYSTEM "Concurrent.sgml">
- <!ENTITY dynamic SYSTEM "Dynamic.sgml">
- <!ENTITY exception SYSTEM "Exception.sgml">
- <!ENTITY foreign SYSTEM "Foreign.sgml">
- <!ENTITY glaexts SYSTEM "GlaExts.sgml">
- <!ENTITY getopt SYSTEM "GetOpt.sgml">
- <!ENTITY ioexts SYSTEM "IOExts.sgml">
- <!ENTITY int SYSTEM "Int.sgml">
- <!ENTITY ndset SYSTEM "NDSet.sgml">
- <!ENTITY numexts SYSTEM "NumExts.sgml">
- <!ENTITY pretty SYSTEM "Pretty.sgml">
- <!ENTITY st SYSTEM "ST.sgml">
- <!ENTITY stable SYSTEM "Stable.sgml">
- <!ENTITY weak SYSTEM "Weak.sgml">
- <!ENTITY word SYSTEM "Word.sgml">
-]>
-
-<!-- ToDo:
- o Add indexing support (to linuxdoc)
- o Fix citations in html
- -->
-
-<article>
-
-<title>The Hugs-GHC Extension Libraries
-<author>The Hugs/GHC Team
-<date>January 1999
-<abstract>
-Hugs and GHC provide a common set of libraries to aid portability.
-This document specifies the interfaces to these libraries and documents
-known differences.
-</abstract>
-
-<toc>
-
-<sect> <idx/Naming conventions/
-<label id="sec:Naming conventions">
-<p>
-
-The set of interfaces specified in this document try to adhere to the
-following naming conventions:
-
-<itemize>
-<item>
-Actions that create a new values have the prefix <tt/new/ followed by
-the name of the type of object they're creating, e.g., <tt/newIORef/,
-<tt/newChan/ etc.
-<item>
-Operations that read a value from a mutable object are prefixed with
-<tt/read/, and operations that update the contents have the prefix
-<tt/write/, e.g., <tt/readChan/, <tt/readIOArray/.
-
-Notes:
-<itemize>
-<item>
-This differs from the convention used to name the operations for
-reading and writing to a file <tt/Handle/, where <tt/get/ and <tt/put/
-are used instead.
-<item>
-Operations provided by various concurrency abstractions, e.g., <tt/MVar/,
-<tt/CVar/ , also deviate from this naming scheme. This is perhaps
-defensible, since the read and write operations have additional
-behaviour, e.g., <tt/takeMVar/ tries to read the current value
-of an <tt/MVar/, locking it if it succeeds.
-</itemize>
-<item>
-Conversions operators have the form <tt/AToB/ where <tt/A/ and <tt/B/
-are the types we're converting between.
-<item>
-Operations that lazily read values from a mutable object/handle, have
-the form <tt/getXContents/, e.g., <tt/Channel.getChanContents/ and
-<tt/IO.hGetContents/. (OK, so the latter isn't called
-<tt/getHandleContents/, but you hopefully get the picture.)
-</itemize>
-
-<!-- ========================= -->
-
-&addr
-&bits
-&concurrent
-&dynamic
-&exception
-&foreign
-&getopt
-&glaexts
-&ioexts
-&int
-
-&numexts
-&pretty
-&st
-&stable
-
-<sect> <idx/LazyST/
-<label id="sec:LazyST">
-<p>
-
-This library is identical to <tt/ST/ except that the <tt/ST/ monad
-instance is <em/lazy/. The lazy ST monad tends to be more prone to
-space leaks than the strict version, so most programmers will use the
-former unless laziness is explicitly required. <tt/LazyST/ provides
-two additional operations:
-
-<tscreen> <verb>
-lazyToStrictST :: LazyST.ST s a -> ST.ST s a
-strictToLazyST :: ST.ST s a -> LazyST.ST s a
-</verb> </tscreen>
-
-These are used to convert between lazy and strict state threads. The
-semantics with respect to laziness are as you would expect: the strict
-state thread passed to <tt/strictToLazyST/ is not performed until the
-result of the lazy state thread it returns is demanded.
-
-&weak
-&word
-
-<!-- ========================= -->
-
-<biblio files="refs" style="abbrv">
-
-
-</article>
-
diff --git a/ghc/docs/libraries/refs.bib b/ghc/docs/libraries/refs.bib
deleted file mode 100644
index 2a1d99145df0..000000000000
--- a/ghc/docs/libraries/refs.bib
+++ /dev/null
@@ -1,113 +0,0 @@
-
-@article{Haskell1.2,
- author = "Hudak, P. and Peyton Jones, S. and Wadler (editors), P.",
- title = "Report on the {P}rogramming {L}anguage {H}askell, {A} {N}on-strict {P}urely {F}unctional {L}anguage ({V}ersion 1.2)",
- journal = "ACM SIGPLAN Notices",
- volume = "27",
- number = "5",
- month = "May",
- year = "1992"
-}
-
-@techreport{Haskell1.4,
- author = "Peterson, J. and Hammond (editors), K.",
- title = "Report on the {P}rogramming {L}anguage {H}askell 1.4, {A} {N}on-strict {P}urely {F}unctional {L}anguage",
- institution = "Yale University",
- address = "Department of Computer Science",
- type = "Research Report",
- number = "YALEU/DCS/RR-1106",
- month = "April",
- year = "1997"
-}
-
-@techreport{Haskell1.4libs,
- author = "Peterson, J. and Hammond (editors), K.",
- title = "The {Haskell} library report version 1.4",
- institution = "Yale University",
- address = "Department of Computer Science",
- type = "Research Report",
- number = "YALEU/DCS/RR-1105",
- month = "April",
- year = "1997"
-}
-
-@inproceedings{ImperativeFP,
- author = "Peyton Jones, S. and Wadler, P.",
- title = "Imperative Functional Programming",
- booktitle = "Proceedings 20th Symposium on Principles of Programming Languages",
- organization = "ACM",
- month = "January",
- year = "1993"
-}
-
-@inproceedings{LazyStateThreads,
- author = "Launchbury, J. and Peyton Jones, S.L.",
- title = "Lazy functional state threads",
- booktitle = "Conference on Programming Language Design and Implementation",
- address = "Orlando, FL",
- year = "1994",
- month = "June"
-}
-
-@book{BW,
- author = "Bird, R. and Wadler, P.",
- title = "Introduction to functional programming",
- publisher = "Prentice Hall",
- year = "1988"
-}
-
-@article{GentleIntro,
- author = "Hudak, P. and Fasel, J.",
- title = "A gentle introduction to {Haskell}",
- journal = "ACM SIGPLAN Notices",
- volume = "27",
- number = "5",
- month = "May",
- year = "1992",
- note = "Also available as Research Report YALEU/DCS/RR-901,
- Yale University, Department of Computer Science, April 1992."
-}
-
-@techreport{Gofer,
- author = "Jones, M.P.",
- title = "The implementation of the {G}ofer functional programming system",
- institution = "Yale University",
- year = "1994",
- month = "May",
- address = "New Haven, Connecticut, USA",
- type = "Research Report",
- number = "YALEU/DCS/RR-1030",
- note = "Available on the World-Wide Web from {\tt http://www.cs.nott.ac.uk/Department/Staff/mpj/pubs.html}"
-}
-
-@unpublished{MonParse,
- title = "Monadic parser combinators",
- author = "Hutton, G. and Meijer, E.",
- note = "Available from {\tt http://www.cs.nott.ac.uk/Department/Staff/gmh/bib.html}",
- year = "1996"
-}
-
-@inproceedings{concurrentHaskell:popl96,
- author = "Simon {Peyton Jones} and Andrew Gordon and Sigbj\orn Finne",
- title = "Concurrent {H}askell",
- pages = "295--308",
- booktitle = "Conference record of {POPL '96}: 23rd {ACM SIGPLAN-SIGACT}
- {S}ymposium on {P}rinciples of {P}rogramming
- {L}anguages",
- publisher = "ACM press",
- address = "St. Petersburg Beach, FL",
- year = "1996",
- month = "January"
-}
-
-@inproceedings{Wadler:Essence,
- author = "P. Wadler",
- title = "The essence of functional programming (invited talk)",
- booktitle = "Conference record of the Nineteenth annual {ACM}
- {SIGPLAN-SIGACT} symposium on {P}rinciples of {P}rogramming
- {L}anguages",
- month = "Jan",
- year = "1992",
- pages = "1--14"
-}
-
--
GitLab