From 8b71efe0f44c79401f42c8d37ab13ce61dcf5516 Mon Sep 17 00:00:00 2001
From: sof <unknown>
Date: Tue, 2 Feb 1999 14:14:13 +0000
Subject: [PATCH] [project @ 1999-02-02 14:14:11 by sof] Updated and re-org'ed
the library parts.
---
ghc/docs/users_guide/4-02-notes.vsgml | 4 +-
ghc/docs/users_guide/ByteArray.sgml | 45 +++
ghc/docs/users_guide/Makefile | 4 +
ghc/docs/users_guide/MutableArray.sgml | 200 +++++++++++++
ghc/docs/users_guide/libraries.vsgml | 323 +++++----------------
ghc/docs/users_guide/runtime_control.vsgml | 4 +-
ghc/docs/users_guide/users_guide.vsgml | 10 +-
7 files changed, 324 insertions(+), 266 deletions(-)
create mode 100644 ghc/docs/users_guide/ByteArray.sgml
create mode 100644 ghc/docs/users_guide/MutableArray.sgml
diff --git a/ghc/docs/users_guide/4-02-notes.vsgml b/ghc/docs/users_guide/4-02-notes.vsgml
index 69b565b214ae..918079558a00 100644
--- a/ghc/docs/users_guide/4-02-notes.vsgml
+++ b/ghc/docs/users_guide/4-02-notes.vsgml
@@ -38,7 +38,7 @@ occur in the source code.
<item> <tt/isEmptyMVar/ operation added to the <tt/Concurrent/ library.
-<item> Two functions exported from <tt/IOExts/: <tt/unsafeIOToST/ and
-<tt/stToIO/.
+<item> Two new functions exported from <tt/ST/ (and <tt/LazyST/):
+<tt/unsafeIOToST/ and <tt/stToIO/.
</itemize>
diff --git a/ghc/docs/users_guide/ByteArray.sgml b/ghc/docs/users_guide/ByteArray.sgml
new file mode 100644
index 000000000000..69fae3e583a0
--- /dev/null
+++ b/ghc/docs/users_guide/ByteArray.sgml
@@ -0,0 +1,45 @@
+<sect2>The <idx/ByteArray/ interface
+<label id="sec:byte-array">
+<p>
+<nidx>ByteArray interface (GHC extensions)</nidx>
+
+<tt/ByteArray/s are chunks of immutable Haskell heap:
+
+<tscreen><code>
+data ByteArray ix -- abstract
+ -- instance of: Eq, CCallable.
+
+newByteArray :: Ix ix => (ix,ix) -> ST s (ByteArray ix)
+
+indexCharArray :: Ix ix => ByteArray ix -> ix -> Char
+indexIntArray :: Ix ix => ByteArray ix -> ix -> Int
+indexAddrArray :: Ix ix => ByteArray ix -> ix -> Addr
+indexFloatArray :: Ix ix => ByteArray ix -> ix -> Float
+indexDoubleArray :: Ix ix => ByteArray ix -> ix -> Double
+
+sizeofByteArray :: Ix ix => ByteArray ix -> Int
+</code></tscreen>
+<nidx/newByteArray/
+<nidx/indexCharArray/
+<nidx/indexIntArray/
+<nidx/indexAddrArray/
+<nidx/indexFloatArray/
+<nidx/indexDoubleArray/
+<nidx/indexDoubleArray/
+<nidx/sizeofByteArray/
+
+<bf/Remarks:/
+
+<itemize>
+<item>
+The operation <tt/newByteArray/ creates a byte array of length
+equal to the range of its indices <em/in bytes/.
+<item>
+<tt/sizeofByteArray/ returns the size of the byte array, <em/in bytes/.
+
+<item>
+Equality on byte arrays is value equality, not pointer equality (as is
+the case for its mutable variant.) Two byte arrays are equal if
+they're of the same length and they're pairwise equal.
+
+</itemize>
diff --git a/ghc/docs/users_guide/Makefile b/ghc/docs/users_guide/Makefile
index da031a072c0e..342589978dac 100644
--- a/ghc/docs/users_guide/Makefile
+++ b/ghc/docs/users_guide/Makefile
@@ -5,6 +5,10 @@ ifeq "$(BIN_DIST)" "1"
install :: html dvi info
endif
+# Split up the pages on a per-sect2 basis. Big HTML docs
+# are a pain to flick through and use.
+SRC_SGML2HTML_OPTS += -s 1
+
SGML_DOC = users_guide
include $(TOP)/mk/target.mk
diff --git a/ghc/docs/users_guide/MutableArray.sgml b/ghc/docs/users_guide/MutableArray.sgml
new file mode 100644
index 000000000000..31c705f0717e
--- /dev/null
+++ b/ghc/docs/users_guide/MutableArray.sgml
@@ -0,0 +1,200 @@
+<sect2> <idx/MutableArray/
+<label id="sec:MutableArray">
+<p>
+
+The <tt/MutableArray/ interface provide operations for reading and
+writing values to mutable arrays. There's two kinds of
+mutable arrays, the mutatable version of Haskell <tt/Array/s
+and <em/mutable byte arrays/, chunks of memory containing
+values of some basic type.
+
+<sect3> <idx/Mutable arrays/
+<label id="sec:MutableArray:mutable-arrays">
+<p>
+
+The mutable array section of the API provides the following
+operations:
+
+<tscreen><code>
+
+-- mutable arrays:
+newArray :: Ix ix -> (ix,ix) -> elt -> ST s (MutableArray s ix elt)
+boundsOfArray :: Ix ix => MutableArray s ix elt -> (ix, ix)
+readArray :: Ix ix => MutableArray s ix elt -> ix -> ST s elt
+writeArray :: Ix ix => MutableArray s ix elt -> ix -> elt -> ST s ()
+freezeArray :: Ix ix => MutableArray s ix elt -> ST s (Array ix elt)
+thawArray :: Ix ix => Array ix elt -> ST s (MutableArray s ix elt)
+
+unsafeFreezeArray :: Ix ix => MutableArray s ix elt -> ST s (Array ix elt)
+</code></tscreen>
+<nidx>newArray</nidx>
+<nidx>boundsOfArray</nidx>
+<nidx>readArray</nidx>
+<nidx>writeArray</nidx>
+<nidx>freezeArray</nidx>
+<nidx>thawArray</nidx>
+<nidx>unsafeFreezeArray</nidx>
+
+<bf/Remarks:/
+
+<itemize>
+<item>
+The <tt/freezeArray/ action converts a mutable array into an
+immutable one by copying, whereas <tt/unsafeFreezeArray/ returns
+an immutable array that is effectively just the type cast version
+of the mutable array. Should you write to the mutable array after
+it has been (unsafely) frozen, you'll side-effect the immutable
+array in the process. Please don't :-)
+
+<item>
+The operation <tt/thawArray/ goes the other way, converting
+an immutable <tt/Array/ into a mutable one. This is done by
+copying. The operation <tt/unsafeThawArray/ is not provided
+(allthough it conceivably could be.)
+</itemize>
+
+<sect3> <idx/Mutable byte arrays/
+<label id="sec:MutableArray:mutable-byte-arrays">
+<p>
+
+<tscreen><code>
+-- creators:
+newCharArray :: Ix ix => (ix,ix) -> ST s (MutableByteArray s ix)
+newAddrArray :: Ix ix => (ix,ix) -> ST s (MutableByteArray s ix)
+newIntArray :: Ix ix => (ix,ix) -> ST s (MutableByteArray s ix)
+newWordArray :: Ix ix => (ix,ix) -> ST s (MutableByteArray s ix)
+newFloatArray :: Ix ix => (ix,ix) -> ST s (MutableByteArray s ix)
+newDoubleArray :: Ix ix => (ix,ix) -> ST s (MutableByteArray s ix)
+newStablePtrArray :: Ix ix => (ix,ix) -> ST s (MutableByteArray s ix)
+
+boundsOfMutableByteArray
+ :: Ix ix => MutableByteArray s ix -> (ix, ix)
+
+readCharArray :: Ix ix => MutableByteArray s ix -> ix -> ST s Char
+readIntArray :: Ix ix => MutableByteArray s ix -> ix -> ST s Int
+readAddrArray :: Ix ix => MutableByteArray s ix -> ix -> ST s Addr
+readFloatArray :: Ix ix => MutableByteArray s ix -> ix -> ST s Float
+readDoubleArray :: Ix ix => MutableByteArray s ix -> ix -> ST s Double
+readStablePtrArray :: Ix ix => MutableByteArray s ix -> ix -> ST s (StablePtr a)
+readWord8Array :: Ix ix => MutableByteArray s ix -> Int -> ST s Word8
+readWord16Array :: Ix ix => MutableByteArray s ix -> Int -> ST s Word16
+readWord32Array :: Ix ix => MutableByteArray s ix -> Int -> ST s Word32
+readWord64Array :: Ix ix => MutableByteArray s ix -> Int -> ST s Word64
+readInt8Array :: Ix ix => MutableByteArray s ix -> Int -> ST s Int8
+readInt16Array :: Ix ix => MutableByteArray s ix -> Int -> ST s Int16
+readInt32Array :: Ix ix => MutableByteArray s ix -> Int -> ST s Int32
+readInt64Array :: Ix ix => MutableByteArray s ix -> Int -> ST s Int64
+
+writeCharArray :: Ix ix => MutableByteArray s ix -> ix -> Char -> ST s ()
+writeIntArray :: Ix ix => MutableByteArray s ix -> ix -> Int -> ST s ()
+writeAddrArray :: Ix ix => MutableByteArray s ix -> ix -> Addr -> ST s ()
+writeFloatArray :: Ix ix => MutableByteArray s ix -> ix -> Float -> ST s ()
+writeDoubleArray :: Ix ix => MutableByteArray s ix -> ix -> Double -> ST s ()
+writeStablePtrArray :: Ix ix => MutableByteArray s ix -> ix -> StablePtr a -> ST s ()
+writeWord8Array :: Ix ix => MutableByteArray s ix -> Int -> Word8 -> ST s ()
+writeWord16Array :: Ix ix => MutableByteArray s ix -> Int -> Word16 -> ST s ()
+writeWord32Array :: Ix ix => MutableByteArray s ix -> Int -> Word32 -> ST s ()
+writeWord64Array :: Ix ix => MutableByteArray s ix -> Int -> Word64 -> ST s ()
+writeInt8Array :: Ix ix => MutableByteArray s ix -> Int -> Int8 -> ST s ()
+writeInt16Array :: Ix ix => MutableByteArray s ix -> Int -> Int16 -> ST s ()
+writeInt32Array :: Ix ix => MutableByteArray s ix -> Int -> Int32 -> ST s ()
+writeInt64Array :: Ix ix => MutableByteArray s ix -> Int -> Int64 -> ST s ()
+
+freezeCharArray :: Ix ix => MutableByteArray s ix -> ST s (ByteArray ix)
+freezeIntArray :: Ix ix => MutableByteArray s ix -> ST s (ByteArray ix)
+freezeAddrArray :: Ix ix => MutableByteArray s ix -> ST s (ByteArray ix)
+freezeFloatArray :: Ix ix => MutableByteArray s ix -> ST s (ByteArray ix)
+freezeDoubleArray :: Ix ix => MutableByteArray s ix -> ST s (ByteArray ix)
+freezeStablePtrArray :: Ix ix => MutableByteArray s ix -> ST s (ByteArray ix)
+
+unsafeFreezeByteArray :: Ix ix => MutableByteArray s ix -> ST s (ByteArray ix)
+
+sizeofMutableByteArray :: Ix ix => MutableByteArray s ix -> Int
+
+</code></tscreen>
+<nidx>newCharArray</nidx>
+<nidx>newAddrArray</nidx>
+<nidx>newIntArray</nidx>
+<nidx>newFloatArray</nidx>
+<nidx>newDoubleArray</nidx>
+<nidx>boundsOfMutableByteArray</nidx>
+<nidx>readCharArray</nidx>
+<nidx>readIntArray</nidx>
+<nidx>readAddrArray</nidx>
+<nidx>readFloatArray</nidx>
+<nidx>readDoubleArray</nidx>
+<nidx>readWord8Array</nidx>
+<nidx>readWord16Array</nidx>
+<nidx>readWord32Array</nidx>
+<nidx>readWord64Array</nidx>
+<nidx>readInt8Array</nidx>
+<nidx>readInt16Array</nidx>
+<nidx>readInt32Array</nidx>
+<nidx>readInt64Array</nidx>
+<nidx>writeCharArray</nidx>
+<nidx>writeIntArray</nidx>
+<nidx>writeAddrArray</nidx>
+<nidx>writeFloatArray</nidx>
+<nidx>writeDoubleArray</nidx>
+<nidx>writeWord8Array</nidx>
+<nidx>writeWord16Array</nidx>
+<nidx>writeWord32Array</nidx>
+<nidx>writeWord64Array</nidx>
+<nidx>writeInt8Array</nidx>
+<nidx>writeInt16Array</nidx>
+<nidx>writeInt32Array</nidx>
+<nidx>writeInt64Array</nidx>
+<nidx>freezeCharArray</nidx>
+<nidx>freezeIntArray</nidx>
+<nidx>freezeAddrArray</nidx>
+<nidx>freezeFloatArray</nidx>
+<nidx>freezeDoubleArray</nidx>
+<nidx>unsafeFreezeByteArray</nidx>
+
+<bf/Remarks:/
+<itemize>
+<item>
+A Mutable byte array is created by specifying its size in units of
+some basic type. For example,
+
+<tscreen><code>
+ mkPair :: ST s (MutableByteArray s Int)
+ mkPair = newIntArray (0,1)
+</code></tscreen>
+
+creates a mutable array capable of storing two <tt/Int/s. Notice
+that the range size <em/is not in bytes/, but in units of the
+basic type.
+
+<item>
+A mutable byte array is not parameterised over the kind of values
+it contains. A consequence of this is that it is possible to
+have byte arrays containing a mix of basic types, or even read
+a value from the array at a different type from which it was
+written, e.g.,
+
+<tscreen><code>
+ isLitteEndian :: IO Bool
+ isLitteEndian = stToIO $ do
+ x <- newIntArray (0,1)
+ writeIntArray x 1
+ v <- readCharArray x 0
+ return (v == chr 1)
+</code></tscreen>
+
+It's left as an exercise for the reader to determine whether having
+byte arrays not be parameterised over the type of values they
+contain is a bug or a feature..
+
+<item>
+As for mutable arrays, operations for turning mutable byte arrays
+into immutable byte arrays are also provided by the <tt/freeze*/
+class of actions. There's also the non-copying
+<tt/unsafeFreezeByteArray/.
+<p>
+Thawing of byte arrays is currently not supported.
+
+<item>
+The operation <tt/sizeofMutableByteArray/ returns the size of
+the array, <em/in bytes./
+</itemize>
diff --git a/ghc/docs/users_guide/libraries.vsgml b/ghc/docs/users_guide/libraries.vsgml
index 9e666b5e268e..cd837929e6b0 100644
--- a/ghc/docs/users_guide/libraries.vsgml
+++ b/ghc/docs/users_guide/libraries.vsgml
@@ -1,5 +1,5 @@
%
-% $Id: libraries.vsgml,v 1.3 1998/12/02 13:20:40 simonm Exp $
+% $Id: libraries.vsgml,v 1.4 1999/02/02 14:14:12 sof Exp $
%
% GHC Prelude and Libraries.
%
@@ -56,6 +56,73 @@ 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>GHC/Hugs Extension Libraries
+<p>
+
+The extension libraries provided by both GHC and Hugs are described in
+the
+<htmlurl name="GHC/Hugs Extension Library Document" url="http://www.dcs.gla.ac.uk/fp/software/ghc/hg-libs/hg-libs.html">
+
+<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</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@, a new world opesn up to you and the compiler
+will recognise and parse unboxed values properly, and provide access to the
+various interfaces libraries described here (and piles of other goodies.)
+
+&mutablearray;
+&bytearray;
+
+<sect2>The @CCall@ module
+<p>
+
+The @CCall@ module defines the classes @CCallable@ and @CReturnable@,
+along with instances for the primitive types (@Int@, @Int#@, @Float@,
+@Float#@ etc.) GHC knows to import this module if you use @_ccall_@,
+but if you need to define your own instances of these classes, you
+will need to import @CCall@ explicitly.
+
+More information on how to use @_ccall_@ can be found in Section
+<ref name="Calling~C directly from Haskell" id="glasgow-ccalls">.
+
+<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
+representations of the primitive types (Int, Float, etc.), and the
+GHC primitive operations (@+#@, @==#@, etc.).
+
+This module used to provide access to all the Glasgow extensions, but
+these have since been moved into separate libraries for compatibility
+with Hugs (version 2.09: in fact, you can still get at this stuff via
+@GlaExts@ for compatibility, but this facility will likely be removed
+in the future).
+
+<tscreen><verb>
+-- the representation of some basic types:
+data Char = C# Char#
+data Int = I# Int#
+data Addr = A# Addr#
+data Word = W# Word#
+data Float = F# Float#
+data Double = D# Double#
+data Integer = J# Int# Int# ByteArray#
+
+module GHC -- all primops and primitive types.
+</verb></tscreen>
+
<sect1>The module @PrelGHC@: really primitive stuff
<label id="ghc-libs-ghc">
<p>
@@ -823,257 +890,3 @@ putMVar# :: SynchVar# s elt -> State# s -> State# s
<ncdx>newSynchVar#</ncdx>
<ncdx>takeMVar</ncdx>
<ncdx>putMVar</ncdx>
-
-<sect1>GHC/Hugs Extension Libraries
-<p>
-
-The extension libraries provided by both GHC and Hugs are described in
-the <htmlurl name="GHC/Hugs Extension Libraries" url="libs.html">
-document.
-
-<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</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, and provide access to the various interfaces
-libraries described here.
-
-<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
-representations of the primitive types (Int, Float, etc.), and the
-GHC primitive operations (@+#@, @==#@, etc.).
-
-This module used to provide access to all the Glasgow extensions, but
-these have since been moved into separate libraries for compatibility
-with Hugs (version 2.09: in fact, you can still get at this stuff via
-@GlaExts@ for compatibility, but this facility will likely be removed
-in the future).
-
-<tscreen><verb>
--- the representation of some basic types:
-data Char = C# Char#
-data Int = I# Int#
-data Addr = A# Addr#
-data Word = W# Word#
-data Float = F# Float#
-data Double = D# Double#
-data Integer = J# Int# Int# ByteArray#
-
-module GHC -- all primops and primitive types.
-</verb></tscreen>
-
-<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@):
-
-<tscreen><verb>
-data MutableArray s ix elt -- abstract
-data MutableByteArray s ix -- abstract
- -- instance of : CCallable
--- Creators:
-newArray :: Ix ix => (ix,ix) -> elt -> ST s (MutableArray s ix elt)
-newCharArray :: Ix ix => (ix,ix) -> ST s (MutableByteArray s ix)
-newAddrArray :: Ix ix => (ix,ix) -> ST s (MutableByteArray s ix)
-newIntArray :: Ix ix => (ix,ix) -> ST s (MutableByteArray s ix)
-newFloatArray :: Ix ix => (ix,ix) -> ST s (MutableByteArray s ix)
-newDoubleArray :: Ix ix => (ix,ix) -> ST s (MutableByteArray s ix)
-
-boundsOfArray :: Ix ix => MutableArray s ix elt -> (ix, ix)
-boundsOfByteArray :: Ix ix => MutableByteArray s ix -> (ix, ix)
-
-
-readArray :: Ix ix => MutableArray s ix elt -> ix -> ST s elt
-
-readCharArray :: Ix ix => MutableByteArray s ix -> ix -> ST s Char
-readIntArray :: Ix ix => MutableByteArray s ix -> ix -> ST s Int
-readAddrArray :: Ix ix => MutableByteArray s ix -> ix -> ST s Addr
-readFloatArray :: Ix ix => MutableByteArray s ix -> ix -> ST s Float
-readDoubleArray :: Ix ix => MutableByteArray s ix -> ix -> ST s Double
-
-writeArray :: Ix ix => MutableArray s ix elt -> ix -> elt -> ST s ()
-writeCharArray :: Ix ix => MutableByteArray s ix -> ix -> Char -> ST s ()
-writeIntArray :: Ix ix => MutableByteArray s ix -> ix -> Int -> ST s ()
-writeAddrArray :: Ix ix => MutableByteArray s ix -> ix -> Addr -> ST s ()
-writeFloatArray :: Ix ix => MutableByteArray s ix -> ix -> Float -> ST s ()
-writeDoubleArray :: Ix ix => MutableByteArray s ix -> ix -> Double -> ST s ()
-
-freezeArray :: Ix ix => MutableArray s ix elt -> ST s (Array ix elt)
-freezeCharArray :: Ix ix => MutableByteArray s ix -> ST s (ByteArray ix)
-freezeIntArray :: Ix ix => MutableByteArray s ix -> ST s (ByteArray ix)
-freezeAddrArray :: Ix ix => MutableByteArray s ix -> ST s (ByteArray ix)
-freezeFloatArray :: Ix ix => MutableByteArray s ix -> ST s (ByteArray ix)
-freezeDoubleArray :: Ix ix => MutableByteArray s ix -> ST s (ByteArray ix)
-
-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)
-</verb></tscreen>
-
-<nidx>newArray</nidx>
-<nidx>newCharArray</nidx>
-<nidx>newAddrArray</nidx>
-<nidx>newIntArray</nidx>
-<nidx>newFloatArray</nidx>
-<nidx>newDoubleArray</nidx>
-<nidx>boundsOfArray</nidx>
-<nidx>boundsOfByteArray</nidx>
-<nidx>readArray</nidx>
-<nidx>readCharArray</nidx>
-<nidx>readIntArray</nidx>
-<nidx>readAddrArray</nidx>
-<nidx>readFloatArray</nidx>
-<nidx>readDoubleArray</nidx>
-<nidx>writeArray</nidx>
-<nidx>writeCharArray</nidx>
-<nidx>writeIntArray</nidx>
-<nidx>writeAddrArray</nidx>
-<nidx>writeFloatArray</nidx>
-<nidx>writeDoubleArray</nidx>
-<nidx>freezeArray</nidx>
-<nidx>freezeCharArray</nidx>
-<nidx>freezeIntArray</nidx>
-<nidx>freezeAddrArray</nidx>
-<nidx>freezeFloatArray</nidx>
-<nidx>freezeDoubleArray</nidx>
-<nidx>unsafeFreezeArray</nidx>
-<nidx>unsafeFreezeByteArray</nidx>
-<nidx>thawArray</nidx>
-
-<sect2>The @ByteArray@ interface
-<label id="sec:byte-array">
-<p>
-<nidx>ByteArray interface (GHC extensions)</nidx>
-
-@ByteArray@s are chunks of immutable Haskell heap:
-
-<tscreen><verb>
-data ByteArray ix -- abstract
- -- instance of: CCallable
-
-indexCharArray :: Ix ix => ByteArray ix -> ix -> Char
-indexIntArray :: Ix ix => ByteArray ix -> ix -> Int
-indexAddrArray :: Ix ix => ByteArray ix -> ix -> Addr
-indexFloatArray :: Ix ix => ByteArray ix -> ix -> Float
-indexDoubleArray :: Ix ix => ByteArray ix -> ix -> Double
-
-indexCharOffAddr :: Addr -> Int -> Char
-indexIntOffAddr :: Addr -> Int -> Int
-indexAddrOffAddr :: Addr -> Int -> Addr
-indexFloatOffAddr :: Addr -> Int -> Float
-indexDoubleOffAddr :: Addr -> Int -> Double
-</verb></tscreen>
-
-<sect2>Stable pointers
-<p>
-
-Nothing exciting here, just simple boxing up.
-<tscreen><verb>
-data StablePtr a = StablePtr (StablePtr# a)
-
-makeStablePointer :: a -> StablePtr a
-freeStablePointer :: StablePtr a -> IO ()
-</verb></tscreen>
-
-<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.
-
-<tscreen><verb>
-data ForeignObj = ForeignObj ForeignObj#
-
-makeForeignObj
- :: Addr -- object to be boxed up as a ForeignObj
- -> Addr -- finaliser
- -> IO ForeignObj
-
-writeForeignObj
- :: ForeignObj -- previously created foreign object
- -> Addr -- new value
- -> IO ()
-
-</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
-an image-processing library (which was actually the main motivation
-for implementing @ForeignObj@'s precursor, @MallocPtr#@). The
-images manipulated are not stored in the Haskell heap, either because
-the library insist on allocating them internally or we (sensibly)
-decide to spare the GC from having to heave heavy images around.
-
-<tscreen><verb>
-data Image = Image ForeignObj
-</verb></tscreen>
-
-The @ForeignObj@ type is then used to refer to the externally
-allocated image, and to acheive some type safety, the Haskell binding
-defines the @Image@ data type. So, a value of type @ForeignObj@ is
-used to ``box'' up an external reference into a Haskell heap object
-that we can then indirectly reference:
-
-<tscreen><verb>
-createImage :: (Int,Int) -> IO Image
-</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</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
-image-processing library, the finalisation routine could for the
-images free up memory allocated for them. The finalisation routine has
-currently to be written in C (the finalisation routine can in turn
-call on @FreeStablePtr@ to deallocate a stable pointer).
-
-Associating a finalisation routine with an external object is done by
-calling @makeForeignObj@. {\bf Note:} the foreign object value and
-its finaliser are contained in the @ForeignObj@, so there's no danger
-of an aggressive optimiser somehow separating the two (with the result
-that the foreign reference would not be freed).
-
-(Implementation: a linked list of all @ForeignObj#@s is maintained to
- allow the garbage collector to detect when a @ForeignObj#@ becomes
- garbage.)
-
-Like @Array@, @ForeignObj#@s are represented by heap objects.
-
-Upon controlled termination of the Haskell program, all @ForeignObjs@
-are freed, invoking their respective finalisers before terminating.
-
-<sect2>The @CCall@ module
-<p>
-
-The @CCall@ module defines the classes @CCallable@ and @CReturnable@,
-along with instances for the primitive types (@Int@, @Int#@, @Float@,
-@Float#@ etc.) GHC knows to import this module if you use @_ccall_@,
-but if you need to define your own instances of these classes, you
-will need to import @CCall@ explicitly.
-
-More information on how to use @_ccall_@ can be found in Section
-<ref name="Calling~C directly from Haskell" id="glasgow-ccalls">.
-
diff --git a/ghc/docs/users_guide/runtime_control.vsgml b/ghc/docs/users_guide/runtime_control.vsgml
index ccb553e06a5a..eb1da49a073b 100644
--- a/ghc/docs/users_guide/runtime_control.vsgml
+++ b/ghc/docs/users_guide/runtime_control.vsgml
@@ -71,12 +71,12 @@ maximum performance.
collector. The default of 2 seems to be good, but the garbage
collector can support any number of generations. Anything larger than
about 4 is probably not a good idea unless your program runs for a
-<emph/long/ time, because the oldest generation will never get
+<em/long/ time, because the oldest generation will never get
collected.
Specifying 1 generation with @+RTS -G1@ gives you a simple 2-space
collector, as you would expect. In a 2-space collector, the @-A@
-option (see below) specifies the <emph/minimum/ allocation area size,
+option (see below) specifies the <em/minimum/ allocation area size,
since the allocation area will grow with the amount of live data in
the heap. In a multi-generational collector the allocation area is a
fixed size.
diff --git a/ghc/docs/users_guide/users_guide.vsgml b/ghc/docs/users_guide/users_guide.vsgml
index fa8c83dd22fb..a0fea5f4b05d 100644
--- a/ghc/docs/users_guide/users_guide.vsgml
+++ b/ghc/docs/users_guide/users_guide.vsgml
@@ -15,18 +15,14 @@
<!ENTITY libmisc SYSTEM "libmisc.sgml" >
<!ENTITY wrong SYSTEM "gone_wrong.sgml" >
<!ENTITY utils SYSTEM "utils.sgml" >
+ <!ENTITY mutablearray SYSTEM "MutableArray.sgml">
+ <!ENTITY bytearray SYSTEM "ByteArray.sgml">
]>
<article>
<title>The Glasgow Haskell Compiler User's Guide, Version~4.02
-<author>The GHC Team,
-Department of Computing Science,
-University of Glasgow,
-Glasgow, Scotland,
-G12 8QQ
-
+<author>The GHC Team,
Email: @glasgow-haskell-{bugs,users}-request@@dcs.gla.ac.uk@
-
<toc>
&intro
--
GitLab