-\begin{onlystandalone}
-\documentstyle[a4wide,grasp]{article}
-\begin{rawlatex}
-\renewcommand{\textfraction}{0.1}
-\renewcommand{\floatpagefraction}{0.9}
-\renewcommand{\dblfloatpagefraction}{0.9}
-
-\sloppy
-\renewcommand{\today}{November 1997}
-\end{rawlatex}
-
-\begin{document}
-\title{The GHC Prelude and Libraries}
-\author{Simon L Peyton Jones \and Simon Marlow \and Will Partain}
-
-\maketitle
-\begin{rawlatex}
-\tableofcontents
-\end{rawlatex}
-\end{onlystandalone}
+%
+% $Id: libraries.vsgml,v 1.1 1998/01/30 17:02:32 simonm Exp $
+%
+% GHC Prelude and Libraries.
+%
-\section[ghc-prelude]{The GHC prelude and libraries}
+<sect>The GHC prelude and libraries
+<label id="ghc-prelude">
+<p>
This document describes GHC's prelude and libraries. The basic story is that of
the Haskell 1.4 Report and Libraries document (which we do not reproduce here),
but this document describes in addition:
-\begin{itemize}
-\item GHC's additional non-standard libraries and types, such as
+
+<itemize>
+
+<item> GHC's additional non-standard libraries and types, such as
state transformers, packed strings, foreign objects, stable
pointers, and so on.
-\item GHC's primitive types and operations. The standard Haskell
+<item> GHC's primitive types and operations. The standard Haskell
functions are implemented on top of these, and it is sometimes
useful to use them directly.
-\item The organisation of these libraries into directories.
-\item Short description of programmer interface to the non-standard,
- `built-in' libraries provided in addition to the standard
- prelude and libraries.
-\end{itemize}
-
-In addition to the GHC prelude libraries, GHC comes with a number of
-system libraries, which are presented in Section \ref{syslibs}.
-
-\subsection{Prelude library organisation}
-
-{\em Probably only of interest to implementors...}
-
-The prelude libraries are organised into the following three groups,
-each of which is kept in a separate sub-directory of GHC's source
-@lib/@ directory:
-\begin{description}
-\item[@lib/required/@] These are the libraries {\em required} by the
-Haskell definition. All are defined by the Haskell Report, or by the
-Haskell Libraries Report.
-They currently comprise:
-\begin{itemize}
-\item @Array@: monolithic arrays.
-\item @Char@: more functions on characters.
-\item @Complex@: interface defining complex number type and functions
-over it.
-\item @CPUTime@: get the CPU time used by the program.
-\item @Directory@: basic functions for accessing the file system.
-\item @Ix@: the @Ix@ class of indexing operations.
-\item @IO@: additional input/output functions.
-\item @List@: more functions on lists.
-\item @Locale@: localisation functions.
-\item @Maybe@: more functions on @Maybe@ types.
-\item @Monad@: functions on monads.
-\item @Numeric@: operations for reading and showing number values.
-\item @Prelude@: standard prelude interface.
-\item @Random@: pseudo-random number generator.
-\item @Ratio@: functions on rational numbers.
-\item @System@: basic operating-system interface functions.
-\item @Time@: operations on time.
-\end{itemize}
-
-\item[@lib/glaExts@] Extension libraries, currently comprising:
-\begin{itemize}
-\item @Addr@: primitive pointer type.
-\item @Bits@: a class of bitwise operations.
-\item @ByteArray@: operations over immutable chunks of (heap allocated) bytes.
-\item @CCall@: classes @CCallable@ and @CReturnable@ for calling C.
-\item @Foreign@: types and operations for GHC's foreign-language
-interface.
-\item @GlaExts@: interface for extensions that are only implemented in
-GHC: namely unboxed types and primitive operations.
-\item @IOExts@: extensions to the @IO@ library.
-\item @Int@: 8, 16, 32 and 64-bit integers with bit operations.
-\item @LazyST@: a lazy version of the @ST@ monad.
-\item @MutableArray@: operations over mutable arrays.
-\item @ST@: the state transformer monad, @STRef@s and @STArray@s.
-\item @Word@: 8, 16, 32 and 64-bit naturals with bit operations.
-\end{itemize}
-
-\item[@lib/concurrent@] GHC extension libraries to support Concurrent Haskell, currently comprising:
-\begin{itemize}
-\item @Concurrent@: main library.
-\item @Parallel@: stuff for multi-processor parallelism.
-\item @Channel@
-\item @ChannelVar@
-\item @Merge@
-\item @SampleVar@
-\item @Semaphore@
-\end{itemize}
-
-\item[@lib/ghc@] These libraries are the pieces on which all the
-others are built. They aren't typically imported by Joe Programmer,
-but there's nothing to stop you doing so if you want. In general, the
-modules prefixed by @Prel@ are pieces that go towards building
-@Prelude@.
-
-\begin{itemize}
-\item @GHC@: this ``library'' brings into scope all the primitive
-types and operations, such as @Int#@, @+#@, @encodeFloat#@, etc etc.
-It is unique in that there is no Haskell source code for it. Details
-in Section \ref{sect:ghc}.
-
-\item @PrelBase@: defines the basic types and classes without which
-very few Haskell programs can work. The classes are: @Eq@, @Ord@,
-@Enum@, @Bounded@, @Num@, @Show@, @Eval@, @Monad@, @MonadZero@,
-@MonadPlus@. The types are: list, @Bool@, @Char@, @Ordering@,
-@String@, @Int@, @Integer@.
-
-\item @PrelMaybe@: defines the @Maybe@ type.
-
-\item @PrelEither@: defines the @Either@ type.
-
-\item @PrelTup@: defines tuples and their instances.
-
-\item @PrelList@: defines most of the list operations required by
-@Prelude@. (A few are in @PrelBase@, to avoid gratuitous mutual
-recursion between modules.)
-
-\item @PrelNum@ defines: the numeric classes beyond @Num@, namely
-@Real@, @Integral@, @Fractional@, @Floating@, @RealFrac@, @RealFloat@;
-instances for appropriate classes for @Int@ and @Integer@; the types
-@Float@, @Double@, and @Ratio@ and their instances.
-
-\item @PrelRead@: the @Read@ class and all its instances. It's kept
-separate because many programs don't use @Read@ at all, so we don't
-even want to link in its code. (If the prelude libraries are built by
-splitting the object files, this is all a non-issue)
-
-\item @ConcBase@: substrate stuff for Concurrent Haskell.
-
-\item @IOBase@: substrate stuff for the main I/O libraries.
-\item @IOHandle@: large blob of code for doing I/O on handles.
-\item @PrelIO@: the remaining small pieces to produce the I/O stuff
-needed by @Prelude@.
-
-\item @STBase@: substrate stuff for @ST@.
-\item @ArrBase@: substrate stuff for @Array@.
-
-\item @GHCerr@: error reporting code, called from code that the
-compiler plants in compiled programs.
-
-\item @GHCmain@: the definition of @mainIO@, which is what {\em
- really} gets called by the runtime system. @mainIO@ in turn
- calls @main@.
-
-\item @PackBase@: low-level packing/unpacking operations.
-
-\item @Error@: the definition of @error@, placed in its own module
-with a hand-written @.hi-boot@ file in order to break recursive
-dependencies in the libraries (everything needs @error@, but the
-definition of @error@ itself needs a few things...).
-\end{itemize}
-\end{description}
-
-The @...Base@ modules generally export representation information that
-is hidden from the public interface. For example the module @STBase@
-exports the type @ST@ including its representation, whereas the module
-@ST@ exports @ST@ abstractly.
-
-None of these modules are involved in any mutual recursion, with the
-sole exception that many modules import @Error.error@.
-
-\subsection[ghc-libs-ghc]{The module @GHC@: really primitive stuff}
-\label{sect:ghc}
+<item> The organisation of these libraries into directories.
+
+<item> Short description of programmer interface to the non-standard
+ libraries provided in addition to the standard prelude.
+</itemize>
+
+A number of the libraries that provide access to GHC's language
+extensions are shared by Hugs, and are described in the <htmlurl
+name="GHC/Hugs Extension Libraries" url="libs.html"> document.
+
+<sect1>Prelude extensions
+<label id="ghc-prelude-exts">
+<p>
+
+GHC's prelude contains the following non-standard extensions:
+
+<descrip>
+
+<tag>@fromInt@ method in class @Num@:</tag> It's there. Converts from
+an @Int@ to the type.
+
+<tag>@toInt@ method in class @Integral@:</tag> Converts from type type
+to an @Int@.
+
+</descrip>
+
+GHC also internally uses a number of modules that begin with the
+string @Prel@: for this reason, we don't recommend that you use any
+module names beginning with @Prel@ in your own programs. The @Prel@
+modules are always available: in fact, you can get access to several
+extensions this way (for some you might need to give the
+@-fglasgow-exts@<nidx>-fglasgow-exts option</nidx> flag).
+
+<sect1>The module @PrelGHC@: really primitive stuff
+<label id="ghc-libs-ghc">
+<p>
This section defines all the types which are primitive in Glasgow
Haskell, and the operations provided for them.
This section also describes a few non-primitive types, which are needed
to express the result types of some primitive operations.
-\subsubsection{Character and numeric types}
+<sect2>Character and numeric types
+<p>
+<nidx>character types, primitive</nidx>
+<nidx>numeric types, primitive</nidx>
+<nidx>integer types, primitive</nidx>
+<nidx>floating point types, primitive</nidx>
There are the following obvious primitive types:
-\begin{verbatim}
+
+<tscreen><verb>
type Char#
type Int# -- see also Word# and Addr#, later
type Float#
type Double#
-\end{verbatim}
+</verb></tscreen>
+<ncdx>Char#</ncdx>
+<ncdx>Int#</ncdx>
+<ncdx>Float#</ncdx>
+<ncdx>Double#</ncdx>
+
If you really want to know their exact equivalents in C, see
@ghc/includes/StgTypes.lh@ in the GHC source tree.
Literals for these types may be written as follows:
-\begin{verbatim}
+
+<tscreen><verb>
1# an Int#
1.2# a Float#
1.34## a Double#
'a'# a Char#; for weird characters, use '\o<octal>'#
"a"# an Addr# (a `char *')
-\end{verbatim}
+</verb></tscreen>
+<nidx>literals, primitive</nidx>
+<nidx>constants, primitive</nidx>
+<nidx>numbers, primitive</nidx>
-\subsubsubsection{Comparison operations}
-\begin{verbatim}
+<sect2> Comparison operations
+<p>
+<nidx>comparisons, primitive</nidx>
+<nidx>operators, comparison</nidx>
+
+<tscreen><verb>
{>,>=,==,/=,<,<=}# :: Int# -> Int# -> Bool
{gt,ge,eq,ne,lt,le}Char# :: Char# -> Char# -> Bool
- -- ditto for Word#, Float#, Double#, and Addr#
-\end{verbatim}
-
-\subsubsubsection{Unboxed-character operations}
-\begin{verbatim}
+ -- ditto for Word# and Addr#
+</verb></tscreen>
+<ncdx>>#</ncdx>
+<ncdx>>=#</ncdx>
+<ncdx>==#</ncdx>
+<ncdx>/=#</ncdx>
+<ncdx><#</ncdx>
+<ncdx><=#</ncdx>
+<ncdx>gt{Char,Word,Addr}#</ncdx>
+<ncdx>ge{Char,Word,Addr}#</ncdx>
+<ncdx>eq{Char,Word,Addr}#</ncdx>
+<ncdx>ne{Char,Word,Addr}#</ncdx>
+<ncdx>lt{Char,Word,Addr}#</ncdx>
+<ncdx>le{Char,Word,Addr}#</ncdx>
+
+<sect2> Primitive-character operations
+<p>
+<nidx>characters, primitive</nidx>
+<nidx>operators, primitive character</nidx>
+
+<tscreen><verb>
ord# :: Char# -> Int#
chr# :: Int# -> Char#
-\end{verbatim}
+</verb></tscreen>
+<ncdx>ord#</ncdx>
+<ncdx>chr#</ncdx>
-\subsubsubsection{Unboxed-@Int@ operations}
-\begin{verbatim}
+<sect2> Primitive-@Int@ operations
+<p>
+<nidx>integers, primitive</nidx>
+<nidx>operators, primitive integer</nidx>
+
+<tscreen><verb>
{+,-,*,quotInt,remInt}# :: Int# -> Int# -> Int#
negateInt# :: Int# -> Int#
iShiftL#, iShiftRA#, iShiftRL# :: Int# -> Int# -> Int#
-- shift left, right arithmetic, right logical
-\end{verbatim}
-
-{\bf Note:} No error/overflow checking!
-
-\subsubsubsection{Unboxed-@Double@ and @Float@ operations}
-\begin{verbatim}
-{plus,minus,times,divide}Double# :: Double# -> Double# -> Double#
-negateDouble# :: Double# -> Double#
-
-float2Int# :: Double# -> Int# -- just a cast, no checking!
-int2Double# :: Int# -> Double#
-
+</verb></tscreen>
+<ncdx>+#</ncdx>
+<ncdx>-#</ncdx>
+<ncdx>*#</ncdx>
+<ncdx>quotInt#</ncdx>
+<ncdx>remInt#</ncdx>
+<ncdx>iShiftL#</ncdx>
+<ncdx>iShiftRA#</ncdx>
+<ncdx>iShiftRL#</ncdx>
+<nidx>shift operations, integer</nidx>
+
+<bf>Note:</bf> No error/overflow checking!
+
+<sect2> Primitive-@Double@ and @Float@ operations
+<p>
+<nidx>floating point numbers, primitive</nidx>
+<nidx>operators, primitive floating point</nidx>
+
+<tscreen><verb>
+{+,-,*,/}## :: Double# -> Double# -> Double#
+{<,<=,==,/=,>=,>}## :: Double# -> Double# -> Bool
+negateDouble# :: Double# -> Double#
+double2Int# :: Double# -> Int#
+int2Double# :: Int# -> Double#
+
+{plus,minux,times,divide}Float# :: Float# -> Float# -> Float#
+{gt,ge,eq,ne,lt,le}Float# :: Float# -> Float# -> Bool
+negateFloat# :: Float# -> Float#
+float2Int# :: Float# -> Int#
+int2Float# :: Int# -> Float#
+</verb></tscreen>
+
+<ncdx>+##</ncdx>
+<ncdx>-##</ncdx>
+<ncdx>*##</ncdx>
+<ncdx>/##</ncdx>
+<ncdx><##</ncdx>
+<ncdx><=##</ncdx>
+<ncdx>==##</ncdx>
+<ncdx>=/##</ncdx>
+<ncdx>>=##</ncdx>
+<ncdx>>##</ncdx>
+<ncdx>negateDouble#</ncdx>
+<ncdx>double2Int#</ncdx>
+<ncdx>int2Double#</ncdx>
+
+<ncdx>plusFloat#</ncdx>
+<ncdx>minusFloat#</ncdx>
+<ncdx>timesFloat#</ncdx>
+<ncdx>divideFloat#</ncdx>
+<ncdx>gtFloat#</ncdx>
+<ncdx>geFloat#</ncdx>
+<ncdx>eqFloat#</ncdx>
+<ncdx>neFloat#</ncdx>
+<ncdx>ltFloat#</ncdx>
+<ncdx>leFloat#</ncdx>
+<ncdx>negateFloat#</ncdx>
+<ncdx>float2Int#</ncdx>
+<ncdx>int2Float#</ncdx>
+
+And a full complement of trigonometric functions:
+
+<tscreen> <verb>
expDouble# :: Double# -> Double#
logDouble# :: Double# -> Double#
sqrtDouble# :: Double# -> Double#
coshDouble# :: Double# -> Double#
tanhDouble# :: Double# -> Double#
powerDouble# :: Double# -> Double# -> Double#
-\end{verbatim}
+</verb></tscreen>
+<nidx>trigonometric functions, primitive</nidx>
+
+similarly for @Float#@.
-There's an exactly-matching set of unboxed-@Float@ ops; replace
-@Double#@ with @Float#@ in the list above. There are two
-coercion functions for @Float#@/@Double#@:
-\begin{verbatim}
+There are two coercion functions for @Float#@/@Double#@:
+
+<tscreen><verb>
float2Double# :: Float# -> Double#
double2Float# :: Double# -> Float#
-\end{verbatim}
+</verb></tscreen>
+<ncdx>float2Double#</ncdx>
+<ncdx>double2Float#</ncdx>
The primitive versions of @encodeDouble@/@decodeDouble@:
-\begin{verbatim}
+
+<tscreen><verb>
encodeDouble# :: Int# -> Int# -> ByteArray# -- Integer mantissa
-> Int# -- Int exponent
-> Double#
decodeDouble# :: Double# -> PrelNum.ReturnIntAndGMP
-\end{verbatim}
+</verb></tscreen>
+<ncdx>encodeDouble#</ncdx>
+<ncdx>decodeDouble#</ncdx>
(And the same for @Float#@s.)
-\subsubsection{Operations on/for @Integers@ (interface to GMP)}
-\label{sect:horrid-Integer-pairing-types}
+<sect2>Operations on/for @Integers@ (interface to GMP)
+<label id="horrid-Integer-pairing-types">
+<p>
+<nidx>arbitrary precision integers</nidx>
+<nidx>Integer, operations on</nidx>
We implement @Integers@ (arbitrary-precision integers) using the GNU
multiple-precision (GMP) package (version 1.3.2).
-{\bf Note:} some of this might change when we upgrade to using GMP~2.x.
+<bf>Note:</bf> some of this might change when we upgrade to using
+GMP~2.x.
The data type for @Integer@ must mirror that for @MP_INT@ in @gmp.h@
-(see @gmp.info@ in \tr{ghc/includes/runtime/gmp}). It comes out as:
-\begin{verbatim}
+(see @gmp.info@ in @ghc/includes/runtime/gmp@). It comes out as:
+
+<tscreen><verb>
data Integer = J# Int# Int# ByteArray#
-\end{verbatim}
+</verb></tscreen>
+<nidx>Integer type</nidx>
So, @Integer@ is really just a ``pairing'' type for a particular
collection of primitive types.
The operations in the GMP return other combinations of
GMP-plus-something, so we need ``pairing'' types for those, too:
-\begin{verbatim}
+
+<tscreen><verb>
data Return2GMPs = Return2GMPs Int# Int# ByteArray# Int# Int# ByteArray#
data ReturnIntAndGMP = ReturnIntAndGMP Int# Int# Int# ByteArray#
-- ????? something to return a string of bytes (in the heap?)
-\end{verbatim}
+</verb></tscreen>
+<ncdx>Return2GMPs</ncdx>
+<ncdx>ReturnIntAndGMP</ncdx>
The primitive ops to support @Integers@ use the ``pieces'' of the
representation, and are as follows:
-\begin{verbatim}
+
+<tscreen><verb>
negateInteger# :: Int# -> Int# -> ByteArray# -> Integer
{plus,minus,times}Integer# :: Int# -> Int# -> ByteArray#
addr2Integer# :: Addr# -> Integer
-- the Addr# is taken to be a `char *' string
-- to be converted into an Integer.
-\end{verbatim}
-
-
-\subsubsection{Words and addresses}
+</verb></tscreen>
+<ncdx>negateInteger#</ncdx>
+<ncdx>plusInteger#</ncdx>
+<ncdx>minusInteger#</ncdx>
+<ncdx>timesInteger#</ncdx>
+<ncdx>cmpInteger#</ncdx>
+<ncdx>divModInteger#</ncdx>
+<ncdx>quotRemInteger#</ncdx>
+<ncdx>integer2Int#</ncdx>
+<ncdx>int2Integer#</ncdx>
+<ncdx>word2Integer#</ncdx>
+<ncdx>addr2Integer#</ncdx>
+
+<sect2>Words and addresses
+<p>
+<nidx>word, primitive type</nidx>
+<nidx>address, primitive type</nidx>
+<nidx>unsigned integer, primitive type</nidx>
+<nidx>pointer, primitive type</nidx>
A @Word#@ is used for bit-twiddling operations. It is the same size as
an @Int#@, but has no sign nor any arithmetic operations.
-\begin{verbatim}
+<tscreen><verb>
type Word# -- Same size/etc as Int# but *unsigned*
type Addr# -- A pointer from outside the "Haskell world" (from C, probably);
-- described under "arrays"
-\end{verbatim}
+
+</verb></tscreen>
+<ncdx>Word#</ncdx>
+<ncdx>Addr#</ncdx>
@Word#@s and @Addr#@s have the usual comparison operations.
Other unboxed-@Word@ ops (bit-twiddling and coercions):
-\begin{verbatim}
+
+<tscreen><verb>
and#, or#, xor# :: Word# -> Word# -> Word#
-- standard bit ops.
int2Word# :: Int# -> Word# -- just a cast, really
word2Int# :: Word# -> Int#
-\end{verbatim}
+</verb></tscreen>
+<nidx>bit operations, Word and Addr</nidx>
+<ncdx>and#</ncdx>
+<ncdx>or#</ncdx>
+<ncdx>xor#</ncdx>
+<ncdx>not#</ncdx>
+<ncdx>quotWord#</ncdx>
+<ncdx>remWord#</ncdx>
+<ncdx>shiftL#</ncdx>
+<ncdx>shiftRA#</ncdx>
+<ncdx>shiftRL#</ncdx>
+<ncdx>int2Word#</ncdx>
+<ncdx>word2Int#</ncdx>
Unboxed-@Addr@ ops (C casts, really):
-\begin{verbatim}
+<tscreen><verb>
int2Addr# :: Int# -> Addr#
addr2Int# :: Addr# -> Int#
-\end{verbatim}
+</verb></tscreen>
+<ncdx>int2Addr#</ncdx>
+<ncdx>addr2Int#</ncdx>
The casts between @Int#@, @Word#@ and @Addr#@ correspond to null
operations at the machine level, but are required to keep the Haskell
Operations for indexing off of C pointers (@Addr#@s) to snatch values
are listed under ``arrays''.
-\subsubsection{Arrays}
+<sect2>Arrays
+<p>
+<nidx>arrays, primitive</nidx>
-The type @Array# elt@ is the type of primitive, unboxed arrays of
+The type @Array# elt@ is the type of primitive, unpointed arrays of
values of type @elt@.
-\begin{verbatim}
+<tscreen><verb>
type Array# elt
-\end{verbatim}
+</verb></tscreen>
+<ncdx>Array#</ncdx>
@Array#@ is more primitive than a Haskell array --- indeed, the
Haskell @Array@ interface is implemented using @Array#@ --- in that an
@Array#@ is indexed only by @Int#@s, starting at zero. It is also
more primitive by virtue of being unboxed. That doesn't mean that it
-isn't a heap-allocated object --- of course, it is. Rather, being
+isn't a heap-allocated object - of course, it is. Rather, being
unboxed means that it is represented by a pointer to the array itself,
and not to a thunk which will evaluate to the array (or to bottom).
The components of an @Array#@ are themselves boxed.
The type @ByteArray#@ is similar to @Array#@, except that it contains
just a string of (non-pointer) bytes.
-\begin{verbatim}
+<tscreen><verb>
type ByteArray#
-\end{verbatim}
+</verb></tscreen>
+<ncdx>ByteArray#</ncdx>
Arrays of these types are useful when a Haskell program wishes to
construct a value to pass to a C procedure. It is also possible to
collector. In other respects they are just like @ByteArray#@. They
are only needed in order to pass values from C to Haskell.
-\subsubsubsection{Reading and writing.}
+<sect2>Reading and writing
+<p>
Primitive arrays are linear, and indexed starting at zero.
type, which is often needed when preparing data for and unpicking
results from C. (Umm... not true of indices... WDP 95/09)
-{\em Should we provide some @sizeOfDouble#@ constants?}
+<em>Should we provide some @sizeOfDouble#@ constants?</em>
Out-of-range errors on indexing should be caught by the code which
uses the primitive operation; the primitive operations themselves do
-{\em not} check for out-of-range indexes. The intention is that the
+<em>not</em> check for out-of-range indexes. The intention is that the
primitive ops compile to one machine instruction or thereabouts.
We use the terms ``reading'' and ``writing'' to refer to accessing
-{\em mutable} arrays (see Section~\ref{sect:mutable}), and
-``indexing'' to refer to reading a value from an {\em immutable}
+<em>mutable</em> arrays (see Section~<ref name="Mutable arrays" id="sect:mutable">), and
+``indexing'' to refer to reading a value from an <em>immutable</em>
array.
Immutable byte arrays are straightforward to index (all indices in bytes):
-\begin{verbatim}
+<tscreen><verb>
indexCharArray# :: ByteArray# -> Int# -> Char#
indexIntArray# :: ByteArray# -> Int# -> Int#
indexAddrArray# :: ByteArray# -> Int# -> Addr#
indexDoubleOffAddr# :: Addr# -> Int# -> Double#
indexAddrOffAddr# :: Addr# -> Int# -> Addr#
-- Get an Addr# from an Addr# offset
-\end{verbatim}
-\index{indexCharArray# function}
-\index{indexIntArray# function}
-\index{indexAddrArray# function}
-\index{indexFloatArray# function}
-\index{indexDoubleArray# function}
-\index{indexCharOffAddr# function}
-\index{indexIntOffAddr# function}
-\index{indexFloatOffAddr# function}
-\index{indexDoubleOffAddr# function}
-\index{indexAddrOffAddr# function}
+</verb></tscreen>
+<ncdx>indexCharArray#</ncdx>
+<ncdx>indexIntArray#</ncdx>
+<ncdx>indexAddrArray#</ncdx>
+<ncdx>indexFloatArray#</ncdx>
+<ncdx>indexDoubleArray#</ncdx>
+<ncdx>indexCharOffAddr#</ncdx>
+<ncdx>indexIntOffAddr#</ncdx>
+<ncdx>indexFloatOffAddr#</ncdx>
+<ncdx>indexDoubleOffAddr#</ncdx>
+<ncdx>indexAddrOffAddr#</ncdx>
The last of these, @indexAddrOffAddr#@, extracts an @Addr#@ using an offset
from another @Addr#@, thereby providing the ability to follow a chain of
object! This is a pain: primitive ops aren't supposed to do
complicated things like enter objects. The current solution is to
return a lifted value, but I don't like it!
-\begin{verbatim}
+
+<tscreen><verb>
indexArray# :: Array# elt -> Int# -> PrelBase.Lift elt -- Yuk!
-\end{verbatim}
+</verb></tscreen>
+<ncdx>indexArray#</ncdx>
-\subsubsection{The state type}
-\index{State# type}
+<sect2>The state type
+<p>
+<ncdx>state, primitive type</ncdx>
+<ncdx>State#</ncdx>
-The primitive type @State#@ represents the state of a state transformer.
-It is parameterised on the desired type of state, which serves to keep
-states from distinct threads distinct from one another. But the {\em only}
-effect of this parameterisation is in the type system: all values of type
-@State#@ are represented in the same way. Indeed, they are all
-represented by nothing at all! The code generator ``knows'' to generate no
-code, and allocate no registers etc, for primitive states.
-\begin{verbatim}
-type State# s
-\end{verbatim}
+The primitive type @State#@ represents the state of a state
+transformer. It is parameterised on the desired type of state, which
+serves to keep states from distinct threads distinct from one another.
+But the <em>only</em> effect of this parameterisation is in the type
+system: all values of type @State#@ are represented in the same way.
+Indeed, they are all represented by nothing at all! The code
+generator ``knows'' to generate no code, and allocate no registers
+etc, for primitive states.
+<tscreen><verb>
+type State# s
+</verb></tscreen>
The type @GHC.RealWorld@ is truly opaque: there are no values defined
of this type, and no operations over it. It is ``primitive'' in that
-sense---but it is {\em not unboxed!} Its only role in life is to be
+sense - but it is <em>not unboxed!</em> Its only role in life is to be
the type which distinguishes the @IO@ state transformer.
-\begin{verbatim}
+
+<tscreen><verb>
data RealWorld
-\end{verbatim}
+</verb></tscreen>
-\subsubsubsection{State of the world}
+<sect2>State of the world
+<p>
A single, primitive, value of type @State# RealWorld@ is provided.
-\begin{verbatim}
+
+<tscreen><verb>
realWorld# :: State# GHC.RealWorld
-\end{verbatim}
-\index{realWorld# state object}
+</verb></tscreen>
+<nidx>realWorld# state object</nidx>
(Note: in the compiler, not a @PrimOp@; just a mucho magic
@Id@. Exported from @GHC@, though).
-\subsubsection{State pairing types}
-\label{sect:horrid-pairing-types}
+<sect2>State pairing types
+<p>
+<label id="horrid-pairing-types">
This subsection defines some types which, while they aren't quite
primitive because we can define them in Haskell, are very nearly so.
They define constructors which pair a primitive state with a value of
each primitive type. They are required to express the result type of
the primitive operations in the state monad.
-\begin{verbatim}
+<tscreen><verb>
data StateAndPtr# s elt = StateAndPtr# (State# s) elt
data StateAndChar# s = StateAndChar# (State# s) Char#
data StateAndMutableArray# s elt = StateAndMutableArray# (State# s) (MutableArray# s elt)
data StateAndByteArray# s = StateAndByteArray# (State# s) ByteArray#
data StateAndMutableByteArray# s = StateAndMutableByteArray# (State# s) (MutableByteArray# s)
-\end{verbatim}
+</verb></tscreen>
Hideous.
-\subsubsection{Mutable arrays}
-\label{sect:mutable}
-\index{Mutable arrays}
+<sect2>Mutable arrays
+<p>
+<label id="sect:mutable">
+<nidx>mutable arrays</nidx>
+<nidx>arrays, mutable</nidx>
Corresponding to @Array#@ and @ByteArray#@, we have the types of
mutable versions of each. In each case, the representation is a
pointer to a suitable block of (mutable) heap-allocated storage.
-\begin{verbatim}
+
+<tscreen><verb>
type MutableArray# s elt
type MutableByteArray# s
-\end{verbatim}
+</verb></tscreen>
+<ncdx>MutableArray#</ncdx>
+<ncdx>MutableByteArray#</ncdx>
-\subsubsubsection{Allocation}
-\index{Mutable arrays, allocation}
-\index{Allocation, of mutable arrays}
+<sect3>Allocation
+<p>
+<nidx>mutable arrays, allocation</nidx>
+<nidx>arrays, allocation</nidx>
+<nidx>allocation, of mutable arrays</nidx>
Mutable arrays can be allocated. Only pointer-arrays are initialised;
arrays of non-pointers are filled in by ``user code'' rather than by
the array-allocation primitive. Reason: only the pointer case has to
worry about GC striking with a partly-initialised array.
-\begin{verbatim}
+<tscreen><verb>
newArray# :: Int# -> elt -> State# s -> StateAndMutableArray# s elt
newCharArray# :: Int# -> State# s -> StateAndMutableByteArray# s
newAddrArray# :: Int# -> State# s -> StateAndMutableByteArray# s
newFloatArray# :: Int# -> State# s -> StateAndMutableByteArray# s
newDoubleArray# :: Int# -> State# s -> StateAndMutableByteArray# s
-\end{verbatim}
+</verb></tscreen>
+<ncdx>newArray#</ncdx>
+<ncdx>newCharArray#</ncdx>
+<ncdx>newIntArray#</ncdx>
+<ncdx>newAddrArray#</ncdx>
+<ncdx>newFloatArray#</ncdx>
+<ncdx>newDoubleArray#</ncdx>
The size of a @ByteArray#@ is given in bytes.
-\subsubsubsection{Reading and writing}
+<sect3>Reading and writing
+<p>
+<nidx>arrays, reading and writing</nidx>
-%OLD: Remember, offsets in a @MutableByteArray#@ are in bytes.
-\begin{verbatim}
+<tscreen><verb>
readArray# :: MutableArray# s elt -> Int# -> State# s -> StateAndPtr# s elt
readCharArray# :: MutableByteArray# s -> Int# -> State# s -> StateAndChar# s
readIntArray# :: MutableByteArray# s -> Int# -> State# s -> StateAndInt# s
writeAddrArray# :: MutableByteArray# s -> Int# -> Addr# -> State# s -> State# s
writeFloatArray# :: MutableByteArray# s -> Int# -> Float# -> State# s -> State# s
writeDoubleArray# :: MutableByteArray# s -> Int# -> Double# -> State# s -> State# s
-\end{verbatim}
-
-
-\subsubsubsection{Equality.}
+</verb></tscreen>
+<ncdx>readArray#</ncdx>
+<ncdx>readCharArray#</ncdx>
+<ncdx>readIntArray#</ncdx>
+<ncdx>readAddrArray#</ncdx>
+<ncdx>readFloatArray#</ncdx>
+<ncdx>readDoubleArray#</ncdx>
+<ncdx>writeArray#</ncdx>
+<ncdx>writeCharArray#</ncdx>
+<ncdx>writeIntArray#</ncdx>
+<ncdx>writeAddrArray#</ncdx>
+<ncdx>writeFloatArray#</ncdx>
+<ncdx>writeDoubleArray#</ncdx>
+
+
+<sect3>Equality
+<p>
+<nidx>arrays, testing for equality</nidx>
One can take ``equality'' of mutable arrays. What is compared is the
-{\em name} or reference to the mutable array, not its contents.
-\begin{verbatim}
+<em>name</em> or reference to the mutable array, not its contents.
+
+<tscreen><verb>
sameMutableArray# :: MutableArray# s elt -> MutableArray# s elt -> Bool
sameMutableByteArray# :: MutableByteArray# s -> MutableByteArray# s -> Bool
-\end{verbatim}
+</verb></tscreen>
+<ncdx>sameMutableArray#</ncdx>
+<ncdx>sameMutableByteArray#</ncdx>
-
-\subsubsubsection{Freezing mutable arrays}
+<sect3>Freezing mutable arrays
+<p>
+<nidx>arrays, freezing mutable</nidx>
+<nidx>freezing mutable arrays</nidx>
+<nidx>mutable arrays, freezing</nidx>
Only unsafe-freeze has a primitive. (Safe freeze is done directly in Haskell
by copying the array and then using @unsafeFreeze@.)
-\begin{verbatim}
+
+<tscreen><verb>
unsafeFreezeArray# :: MutableArray# s elt -> State# s -> StateAndArray# s elt
unsafeFreezeByteArray# :: MutableByteArray# s -> State# s -> StateAndByteArray# s
-\end{verbatim}
+</verb></tscreen>
+<ncdx>unsafeFreezeArray#</ncdx>
+<ncdx>unsafeFreezeByteArray#</ncdx>
-
-\subsubsection{Stable pointers}
-\index{Stable pointers}
+<sect2>Stable pointers
+<p>
+<nidx>stable pointers</nidx>
+<nidx>pointers, stable</nidx>
A stable pointer is a name for a Haskell object which can be passed to
the external world. It is ``stable'' in the sense that the name does
The stable pointer type is parameterised by the type of the thing
which is named.
-\begin{verbatim}
+
+<tscreen><verb>
type StablePtr# a
-\end{verbatim}
+</verb></tscreen>
+<ncdx>StablePtr#</ncdx>
A stable pointer is represented by an index into the (static)
@StablePointerTable@. The Haskell garbage collector treats the
pointer. It is part of the @IO@ monad, because we want to be sure
we don't allocate one twice by accident, and then only free one of the
copies.
-\begin{verbatim}
+
+<tscreen><verb>
makeStablePointer# :: a -> State# RealWorld -> StateAndStablePtr# RealWorld a
freeStablePointer# :: StablePtr# a -> State# RealWorld -> State# RealWorld
deRefStablePointer# :: StablePtr# a -> State# RealWorld -> StateAndPtr RealWorld a
-\end{verbatim}
+</verb></tscreen>
+<ncdx>makeStablePointer#</ncdx>
+<ncdx>freeStablePointer#</ncdx>
+<ncdx>deRefStablePointer#</ncdx>
There is also a C procedure @FreeStablePtr@ which frees a stable pointer.
-%{\em Andy's comment.} {\bf Errors:} The following is not strictly true: the current
+%<em>Andy's comment.</em> {\bf Errors:} The following is not strictly true: the current
%implementation is not as polymorphic as claimed. The reason for this
%is that the C programmer will have to use a different entry-routine
%for each type of stable pointer. At present, we only supply a very
%increase the range of these routines by providing general purpose
%entry points to apply stable pointers to (stable pointers to)
%arguments and to enter (stable pointers to) boxed primitive values.
-%{\em End of Andy's comment.}
+%<em>End of Andy's comment.</em>
-%
-% Rewritten and updated for MallocPtr++ -- 4/96 SOF
-%
-\subsubsection{Foreign objects}
-\index{Foreign objects}
-\index{ForeignObj type}
+<sect2>Foreign objects
+<p>
+<nidx>Foreign objects</nidx>
A @ForeignObj#@ is a reference to an object outside the Haskell world
(i.e., from the C world, or a reference to an object on another
machine completely.), where the Haskell world has been told ``Let me
know when you're finished with this ...''.
-\begin{verbatim}
+<tscreen><verb>
type ForeignObj#
-\end{verbatim}
+</verb></tscreen>
+<ncdx>ForeignObj#</ncdx>
GHC provides two primitives on @ForeignObj#@:
-\begin{verbatim}
+<tscreen><verb>
makeForeignObj#
:: Addr# -- foreign reference
-> Addr# -- pointer to finalisation routine
-> Addr# -- datum
-> State# RealWorld
-> State# RealWorld
-\end{verbatim}
+</verb></tscreen>
+<ncdx>makeForeignObj#</ncdx>
+<ncdx>writeForeignObj#</ncdx>
-The module @Foreign@ (Section \ref{sec:foreign-obj}) provides a more
-programmer-friendly interface to foreign objects.
+The module @Foreign@ (Section <ref name="Foreign objects"
+id="sec:foreign-obj">) provides a more programmer-friendly interface
+to foreign objects.
-\subsubsection{Synchronizing variables (M-vars)}
-\index{Synchronising variables (M-vars)}
-\index{M-Vars}
+<sect2>Synchronizing variables (M-vars)
+<p>
+<nidx>synchronising variables (M-vars)</nidx>
+<nidx>M-Vars</nidx>
Synchronising variables are the primitive type used to implement
Concurrent Haskell's MVars (see the Concurrent Haskell paper for
the operational behaviour of these operations).
-\begin{verbatim}
+<tscreen><verb>
type SynchVar# s elt -- primitive
newSynchVar#:: State# s -> StateAndSynchVar# s elt
takeMVar# :: SynchVar# s elt -> State# s -> StateAndPtr# s elt
putMVar# :: SynchVar# s elt -> State# s -> State# s
-\end{verbatim}
+</verb></tscreen>
+<ncdx>SynchVar#</ncdx>
+<ncdx>newSynchVar#</ncdx>
+<ncdx>takeMVar</ncdx>
+<ncdx>putMVar</ncdx>
-\subsubsection{@spark#@ primitive operation (for parallel execution)}
+<sect2>@spark#@ primitive operation (for parallel execution)
+<p>
+<nidx>spark primitive operation</nidx>
-{\em ToDo: say something} It's used in the unfolding for @par@.
+<em>ToDo: say something</em> It's used in the unfolding for @par@.
-\subsubsection{The @errorIO#@ primitive operation}
+<sect2>The @errorIO#@ primitive operation
+<p>
+<nidx>errors, primitive</nidx>
The @errorIO#@ primitive takes an argument much like @IO@. It aborts
execution of the current program, and continues instead by performing
the given @IO@-like value on the current state of the world.
-\begin{verbatim}
-errorIO# :: (State# RealWorld# -> a -> a
-\end{verbatim}
+<tscreen><verb>
+errorIO# :: (State# RealWorld# -> a) -> a
+</verb></tscreen>
+<ncdx>errorIO#</ncdx>
-\subsection{GHC/Hugs Extension Libraries}
+<sect1>GHC/Hugs Extension Libraries
+<p>
The extension libraries provided by both GHC and Hugs are described in
-a separate document ``The Hugs-GHC Extension Libraries''.
+the <htmlurl name="GHC/Hugs Extension Libraries" url="libs.html">
+document.
-\subsection{GHC-only Extension Libraries}
+<sect1>GHC-only Extension Libraries
+<p>
+<nidx>libraries, ghc-only</nidx>
+<nidx>extension libraries, ghc-only</nidx>
If you rely on the implicit @import Prelude@ that GHC normally does
for you, and if you don't use any weird flags (notably
@-fglasgow-exts@), and if you don't import the Glasgow extensions
-interface, @GlaExts@, then GHC should work {\em exactly} as the
-Haskell report says, and the full user namespaces should be available
-to you.
-
-If you mess about with @import Prelude@... innocent hiding, e.g.,
-
-\begin{verbatim}
-import Prelude hiding ( fromIntegral )
-\end{verbatim}
-
-should work just fine.
-
-% this should work now?? -- SDM
-
-%There are some things you can do that will make GHC crash, e.g.,
-%hiding a standard class:
-%\begin{verbatim}
-%import Prelude hiding ( Eq(..) )
-%\end{verbatim}
-%
-%Don't do that.
+interface, @GlaExts@, then GHC should work <em>exactly</em> as the
+Haskell report says (modulo a few minor issues, see Section <ref
+id="vs-Haskell-defn" name="Language Non-compliance">).
If you turn on @-fglasgow-exts@, the compiler will recognise and parse
-unboxed values properly. To get at the primitive operations described
-herein, import the relevant interfaces.
+unboxed values properly, and provide access to the various interfaces
+libraries described here.
-\subsubsection{The @GlaExts@ interface}
-\index{GlaExts interface (GHC extensions)}
+<sect2>The @GlaExts@ interface
+<p>
+<nidx>GlaExts interface (GHC extensions)</nidx>
The @GlaExts@ interface provides access to extensions that only GHC
implements. These currently are: unboxed types, including the
@GlaExts@ for compatibility, but this facility will likely be removed
in the future).
-\begin{verbatim}
+<tscreen><verb>
-- the representation of some basic types:
data Char = C# Char#
data Int = I# Int#
data Integer = J# Int# Int# ByteArray#
module GHC -- all primops and primitive types.
-\end{verbatim}
+</verb></tscreen>
-\subsubsection{The @MutableArray@ interface}
-\label{sec:mutable-array}
-\index{MutableArray interface (GHC extensions)}
+<sect2>The @MutableArray@ interface
+<label id="sec:mutable-array">
+<p>
+<nidx>MutableArray interface (GHC extensions)</nidx>
The @MutableArray@ interface defines a general set of operations over
mutable arrays (@MutableArray@) and mutable chunks of memory
(@MutableByteArray@):
-\begin{verbatim}
+<tscreen><verb>
data MutableArray s ix elt -- abstract
data MutableByteArray s ix -- abstract
-- instance of : CCallable
unsafeFreezeArray :: Ix ix => MutableArray s ix elt -> ST s (Array ix elt)
unsafeFreezeByteArray :: Ix ix => MutableByteArray s ix -> ST s (ByteArray ix)
thawArray :: Ix ix => Array ix elt -> ST s (MutableArray s ix elt)
-\end{verbatim}
+</verb></tscreen>
+
+%ToDo: index these.
-\subsubsection{The @ByteArray@ interface}
-\label{sec:byte-array}
-\index{ByteArray interface (GHC extensions)}
+<sect2>The @ByteArray@ interface
+<label id="sec:byte-array">
+<p>
+<nidx>ByteArray interface (GHC extensions)</nidx>
@ByteArray@s are chunks of immutable Haskell heap:
-\begin{verbatim}
+<tscreen><verb>
data ByteArray ix -- abstract
-- instance of: CCallable
indexAddrOffAddr :: Addr -> Int -> Addr
indexFloatOffAddr :: Addr -> Int -> Float
indexDoubleOffAddr :: Addr -> Int -> Double
-\end{verbatim}
+</verb></tscreen>
-\subsubsection{Stable pointers}
+<sect2>Stable pointers
+<p>
Nothing exciting here, just simple boxing up.
-\begin{verbatim}
+<tscreen><verb>
data StablePtr a = StablePtr (StablePtr# a)
makeStablePointer :: a -> StablePtr a
freeStablePointer :: StablePtr a -> IO ()
-\end{verbatim}
+</verb></tscreen>
-\subsubsection{Foreign objects}
-\label{sec:foreign-obj}
-\index{Foreign objects}
+<sect2>Foreign objects
+<label id="sec:foreign-obj">
+<p>
+<nidx>Foreign objects</nidx>
This module provides the @ForeignObj@ type and wrappers around the
primitive operations on foreign objects.
-\begin{verbatim}
+<tscreen><verb>
data ForeignObj = ForeignObj ForeignObj#
makeForeignObj
-> Addr -- new value
-> IO ()
-\end{verbatim}
-\index{ForeignObj type}
-\index{makeForeignObj function}
-\index{writeForeignObj function}
+</verb></tscreen>
+<ncdx>ForeignObj</ncdx>
+<ncdx>makeForeignObj</ncdx>
+<ncdx>writeForeignObj</ncdx>
A typical use of @ForeignObj@ is in constructing Haskell bindings
to external libraries. A good example is that of writing a binding to
the library insist on allocating them internally or we (sensibly)
decide to spare the GC from having to heave heavy images around.
-\begin{verbatim}
+<tscreen><verb>
data Image = Image ForeignObj
-\end{verbatim}
+</verb></tscreen>
The @ForeignObj@ type is then used to refer to the externally
allocated image, and to acheive some type safety, the Haskell binding
used to ``box'' up an external reference into a Haskell heap object
that we can then indirectly reference:
-\begin{verbatim}
+<tscreen><verb>
createImage :: (Int,Int) -> IO Image
-\end{verbatim}
+</verb></tscreen>
So far, this looks just like an @Addr@ type, but @ForeignObj@ offers a
-bit more, namely that we can specify a {\em finalisation routine} to
+bit more, namely that we can specify a <em>finalisation routine</em> to
invoke when the @ForeignObj@ is discarded by the GC. The garbage
collector invokes the finalisation routine associated with the
@ForeignObj@, saying `` Thanks, I'm through with this now..'' For the
Upon controlled termination of the Haskell program, all @ForeignObjs@
are freed, invoking their respective finalisers before terminating.
-\subsubsection{The @CCall@ module}
+<sect2>The @CCall@ module
+<p>
The @CCall@ module defines the classes @CCallable@ and @CReturnable@,
along with instances for the primitive types (@Int@, @Int#@, @Float@,
will need to import @CCall@ explicitly.
More information on how to use @_ccall_@ can be found in Section
-\ref{glasgow-ccalls}.
-
-\begin{onlystandalone}
-\end{document}
-\end{onlystandalone}
+<ref name="Calling~C directly from Haskell" id="glasgow-ccalls">.
projects / ghc-hetmet.git / blobdiff