Commit 01d61152 authored by simonm's avatar simonm
Browse files

[project @ 1997-12-17 13:57:27 by simonm]

remove GHC/Hugs extension document from the user guide.
parent 0cd4f382
......@@ -736,578 +736,10 @@ the given @IO@-like value on the current state of the world.
errorIO# :: (State# RealWorld# -> a -> a
\end{verbatim}
%------------------------------------------------------------
\subsection{GHC/Hugs Extension Libraries}
\subsubsection{@LazyST@}
\index{LazyST module}
This library provides support for both {\em lazy\/} and {\em strict\/}
state threads. In addition to the monad {\tt ST}, it also provides
mutable variables {\tt STRef} and mutable arrays {\tt STArray}. As
the name suggests, the monad {\tt ST} instance is {\em lazy\/}.
\begin{verbatim}
module LazyST( module LazyST, module Monad ) where
import Monad
data ST s a -- abstract type
runST :: forall a. (forall s. ST s a) -> a
returnST :: a -> ST s a
thenLazyST :: ST s a -> (a -> ST s b) -> ST s b
thenStrictST :: ST s a -> (a -> ST s b) -> ST s b
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)
\end{verbatim}
Notes:
\begin{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 In the current version of Hugs, the {\tt runST} operation,
used to specify encapsulation, is implemented as a language construct,
and {\tt runST} is treated as a keyword. We plan to change this to match
GHC soon.
\item The only difference between the lazy and strict instances of the
{\tt ST} monad is in their bind operators. The monadic bind operators
{\tt thenLazyST} and {\tt thenStrictST} are provided so that you can
import {\tt LazyST} (say) and still use the strict instance in those
places where it matters. GHC also allows you to write {\tt LazyST.>>=}
and {\tt ST.>>=} but this is not supported by Hugs yet.
\end{itemize}
\subsubsection{@ST@}
\index{ST module}
This library is identical to {\tt LazyST} except that the {\tt ST} monad
instance is {\em strict\/}. Most programmers use the {\em strict\/} instance
to avoid the space leaks associated with the {\em lazy\/} instance.
\subsubsection{@IOExts@}
\index{IOExts module}
This library provides the following extensions to the IO monad:
\begin{itemize}
\item The operations {\tt fixIO}, {\tt unsafePerformIO} and {\tt
unsafeInterleaveIO}.
\item References (aka mutable variables) and mutable arrays (but no form of
mutable byte arrays)
\item {\tt performGC} triggers an immediate garbage collection
\item When called, {\tt trace} prints the string in its first argument, and then
returns 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.
\end{itemize}
\begin{verbatim}
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)
trace :: String -> a -> a
performGC :: IO ()
\end{verbatim}
\subsubsection{@Bits@}
\index{Bits module}
This library defines bitwise operations for signed and unsigned ints.
\begin{verbatim}
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)
\end{verbatim}
Notes:
\begin{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 (or {\tt Nothing} for unbounded types); and
{\tt isSigned} returns whether the type is signed or not.
\item {\tt shift} performs sign extension.
That is, right shifts fill the top bits with 1 if the number is negative
and with 0 otherwise.
(Since unsigned types are always positive, the top bit is always filled with
0.)
\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 bit i} is the value with the i'th bit set.
\end{itemize}
\subsubsection{@Word@}
\index{Word module}
This library provides unsigned integers of various sizes.
The types supported are as follows:
\begin{tabular}{|l|l|}
type & number of bits \\
\hline
Word8 & 8 \\
Word16 & 16 \\
Word32 & 32 \\
Word64 & 64 \\
\hline
\end{tabular}
For each type {\em W} above, we provide the following functions and
instances. The type {\em I} refers to the signed integer type of the
same size.
\begin{verbatim}
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
\end{verbatim}
Plus
\begin{verbatim}
word8ToWord32 :: Word8 -> Word32
word32ToWord8 :: Word32 -> Word8
word16ToWord32 :: Word16 -> Word32
word32ToWord16 :: Word32 -> Word16
word8ToInt :: Word8 -> Int
intToWord8 :: Int -> Word8
word16ToInt :: Word16 -> Int
intToWord16 :: Int -> Word16
word32ToInt :: Word32 -> Int
intToWord32 :: Int -> Word32
\end{verbatim}
Notes:
\begin{itemize}
\item All arithmetic is performed modulo @2^n@.
One non-obvious consequequence 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 ToDo: complete the set of coercion functions.
\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 {\tt Enum} instances stop when they reach their upper or lower
bound --- they don't overflow the way the {\tt Int} and {\tt Float}
instances do.
\item It would be useful to provide a function (or a family of functions?)
which coerced between any two Word types (without going through
Integer).
\end{itemize}
Hugs only provides {\tt Eq}, {\tt Ord}, {\tt Read} and {\tt Show}
instances for {\tt Word64} at the moment.
\subsubsection{@Int@}
\index{Int module}
This library provides signed integers of various sizes. The types
supported are as follows:
\begin{tabular}{|l|l|l|}
type & number of bits \\
\hline
Int8 & 8 \\
Int16 & 16 \\
Int32 & 32 \\
Int64 & 64 \\
\hline
\end{tabular}
For each type {\em I} above, we provide the following instances.
\begin{verbatim}
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
\end{verbatim}
Plus
\begin{verbatim}
int8ToInt :: Int8 -> Int
intToInt8 :: Int -> Int8
int16ToInt :: Int16 -> Int
intToInt16 :: Int -> Int16
int32ToInt :: Int32 -> Int
intToInt32 :: Int -> Int32
\end{verbatim}
\begin{itemize}
\item Hugs does not provide {\tt Int64} at the moment.
\item ToDo: complete the set of coercion functions.
\end{itemize}
\subsubsection{@Addr@}
\index{Addr module}
This library provides machine addresses and is primarily intended for
use in creating foreign function interfaces using GreenCard.
\begin{verbatim}
module Addr where
data Addr -- Address type
instance Eq Addr
nullAddr :: Addr
plusAddr :: Addr -> Int -> Addr
-- read value out of _immutable_ memory
indexCharOffAddr :: Addr -> Int -> Char
indexIntOffAddr :: Addr -> Int -> Int -- should we drop this?
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 -- should we drop this?
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 () -- should we drop this?
writeAddrOffAddr :: Addr -> Int -> Addr -> 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 ()
\end{verbatim}
Hugs and GHC provide {\tt Addr} and {\tt nullAddr} but do not provide
any of the index, read or write functions. They can be implemented
using GreenCard if required.
\subsubsection{@Concurrent@}
\index{Concurrent module}
This library provides the Concurrent Haskell extensions.
We are grateful to the Glasgow Haskell Project for allowing us to
redistribute their implementation of this module.
\begin{verbatim}
module Concurrent where
data ThreadId -- thread identifiers
instance Eq ThreadId
forkIO :: IO () -> IO ThreadId
killThread :: ThreadId -> IO ()
data MVar a -- Synchronisation variables
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
instance Eq (MVar a)
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 ()
readChanContents :: 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 ()
\end{verbatim}
Notes:
\begin{itemize}
\item
GHC uses preemptive multitasking:
Context switches can occur at any time, except if you call a C
function (like \verb"getchar") that blocks waiting for input.
Hugs uses cooperative multitasking:
Context switches only occur when you use one of the primitives
defined in this module. This means that programs such as:
\begin{verbatim}
main = forkIO (write 'a') >> write 'b'
where write c = putChar c >> write c
\end{verbatim}
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.
\item Hugs does not provide the functions {\tt mergeIO} or {\tt nmergeIO} since these
require preemptive multitasking.
\item {\tt killThread} has not been implemented yet on either system.
The plan is that {\tt killThread} will raise an IO exception in the
killed thread which it can catch --- perhaps allowing it to kill its
children before exiting.
\item The {\tt Ord} instance for {\tt ThreadId}s provides an arbitrary total ordering
which might be used to build an ordered binary tree, say.
\end{itemize}
\subsubsection{@Pretty@}
\index{Pretty module}
This library contains Simon Peyton Jones' implementation of John
Hughes's pretty printer combinators.
\begin{verbatim}
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
\end{verbatim}
The extension libraries provided by both GHC and Hugs are described in
a separate document ``The Hugs-GHC Extension Libraries''.
\subsection{GHC-only Extension Libraries}
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment