diff options
| -rw-r--r-- | ghc/docs/users_guide/ByteArray.sgml | 104 | ||||
| -rw-r--r-- | ghc/docs/users_guide/Makefile | 4 | ||||
| -rw-r--r-- | ghc/docs/users_guide/MutableArray.sgml | 403 | ||||
| -rw-r--r-- | ghc/docs/users_guide/win32-dlls.sgml | 195 |
4 files changed, 422 insertions, 284 deletions
diff --git a/ghc/docs/users_guide/ByteArray.sgml b/ghc/docs/users_guide/ByteArray.sgml index 69fae3e583..e378be3c6a 100644 --- a/ghc/docs/users_guide/ByteArray.sgml +++ b/ghc/docs/users_guide/ByteArray.sgml @@ -1,45 +1,77 @@ -<sect2>The <idx/ByteArray/ interface -<label id="sec:byte-array"> -<p> -<nidx>ByteArray interface (GHC extensions)</nidx> +<Sect2 id="sec-byte-array"> +<Title>The ByteArray +<IndexTerm><Primary>ByteArray</Primary></IndexTerm> +interface +</Title> -<tt/ByteArray/s are chunks of immutable Haskell heap: +<Para> +<IndexTerm><Primary>ByteArray interface (GHC extensions)</Primary></IndexTerm> +</Para> -<tscreen><code> +<Para> +<Literal>ByteArray</Literal>s are chunks of immutable Haskell heap: +</Para> + +<Para> + +<ProgramListing> 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> +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 +</ProgramListing> + +<IndexTerm><Primary>newByteArray</Primary></IndexTerm> +<IndexTerm><Primary>indexCharArray</Primary></IndexTerm> +<IndexTerm><Primary>indexIntArray</Primary></IndexTerm> +<IndexTerm><Primary>indexAddrArray</Primary></IndexTerm> +<IndexTerm><Primary>indexFloatArray</Primary></IndexTerm> +<IndexTerm><Primary>indexDoubleArray</Primary></IndexTerm> +<IndexTerm><Primary>indexDoubleArray</Primary></IndexTerm> +<IndexTerm><Primary>sizeofByteArray</Primary></IndexTerm> +</Para> + +<Para> +<Emphasis>Remarks:</Emphasis> +</Para> + +<Para> + +<ItemizedList> +<ListItem> + +<Para> +The operation <Literal>newByteArray</Literal> creates a byte array of length +equal to the range of its indices <Emphasis>in bytes</Emphasis>. +</Para> +</ListItem> +<ListItem> + +<Para> +<Literal>sizeofByteArray</Literal> returns the size of the byte array, <Emphasis>in bytes</Emphasis>. + +</Para> +</ListItem> +<ListItem> + +<Para> 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> +</Para> +</ListItem> + +</ItemizedList> + +</Para> + +</Sect2> diff --git a/ghc/docs/users_guide/Makefile b/ghc/docs/users_guide/Makefile index 3e78ce823e..a45ac788c8 100644 --- a/ghc/docs/users_guide/Makefile +++ b/ghc/docs/users_guide/Makefile @@ -5,10 +5,6 @@ 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 # Generating index is semi-automatic, you need to: diff --git a/ghc/docs/users_guide/MutableArray.sgml b/ghc/docs/users_guide/MutableArray.sgml index 9abd85095d..9639366ea8 100644 --- a/ghc/docs/users_guide/MutableArray.sgml +++ b/ghc/docs/users_guide/MutableArray.sgml @@ -1,211 +1,270 @@ -<sect2> <idx/MutableArray/ -<label id="MutableArray"> -<p> +<Sect2 id="MutableArray"> +<Title>MutableArray +<IndexTerm><Primary>MutableArray</Primary></IndexTerm> +</Title> -The <tt/MutableArray/ interface provide operations for reading and +<Para> +The <Literal>MutableArray</Literal> 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. +mutable arrays, the mutatable version of Haskell <Literal>Array</Literal>s +and <Emphasis>mutable byte arrays</Emphasis>, chunks of memory containing +values of some basic type. +</Para> -<sect3> <idx/Mutable arrays/ -<label id="MutableArray:mutable-arrays"> -<p> +<Sect3 id="MutableArray-mutable-arrays"> +<Title>Mutable arrays +<IndexTerm><Primary>Mutable arrays</Primary></IndexTerm> +</Title> +<Para> The mutable array section of the API provides the following operations: +</Para> -<tscreen><code> +<Para> +<ProgramListing> -- 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) -unsafeThawArray :: Ix ix => Array ix elt -> ST s (MutableArray s 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> -<nidx>unsafeThawArray</nidx> - -<bf/Remarks:/ - -<itemize> -<item> -The <tt/freezeArray/ action converts a mutable array into an -immutable one by copying, whereas <tt/unsafeFreezeArray/ returns +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) +unsafeThawArray :: Ix ix => Array ix elt -> ST s (MutableArray s ix elt) +</ProgramListing> + +<IndexTerm><Primary>newArray</Primary></IndexTerm> +<IndexTerm><Primary>boundsOfArray</Primary></IndexTerm> +<IndexTerm><Primary>readArray</Primary></IndexTerm> +<IndexTerm><Primary>writeArray</Primary></IndexTerm> +<IndexTerm><Primary>freezeArray</Primary></IndexTerm> +<IndexTerm><Primary>thawArray</Primary></IndexTerm> +<IndexTerm><Primary>unsafeFreezeArray</Primary></IndexTerm> +<IndexTerm><Primary>unsafeThawArray</Primary></IndexTerm> +</Para> + +<Para> +<Emphasis>Remarks:</Emphasis> +</Para> + +<Para> + +<ItemizedList> +<ListItem> + +<Para> +The <Literal>freezeArray</Literal> action converts a mutable array into an +immutable one by copying, whereas <Literal>unsafeFreezeArray</Literal> 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 also provided, +</Para> +</ListItem> +<ListItem> + +<Para> +The operation <Literal>thawArray</Literal> goes the other way, converting +an immutable <Literal>Array</Literal> into a mutable one. This is done by +copying. The operation <Literal>unsafeThawArray</Literal> is also provided, which places the same kind of proof obligation on the programmer -as <tt/unsafeFreezeArray/ does. -</itemize> +as <Literal>unsafeFreezeArray</Literal> does. +</Para> +</ListItem> + +</ItemizedList> -<sect3> <idx/Mutable byte arrays/ -<label id="MutableArray:mutable-byte-arrays"> -<p> +</Para> -<tscreen><code> +</Sect3> + +<Sect3 id="MutableArray-mutable-byte-arrays"> +<Title>Mutable byte arrays +<IndexTerm><Primary>Mutable byte arrays</Primary></IndexTerm> +</Title> + +<Para> +<ProgramListing> -- 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 -> ix -> ST s Word8 -readWord16Array :: Ix ix => MutableByteArray s ix -> ix -> ST s Word16 -readWord32Array :: Ix ix => MutableByteArray s ix -> ix -> ST s Word32 -readWord64Array :: Ix ix => MutableByteArray s ix -> ix -> ST s Word64 -readInt8Array :: Ix ix => MutableByteArray s ix -> ix -> ST s Int8 -readInt16Array :: Ix ix => MutableByteArray s ix -> ix -> ST s Int16 -readInt32Array :: Ix ix => MutableByteArray s ix -> ix -> ST s Int32 -readInt64Array :: Ix ix => MutableByteArray s ix -> ix -> 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 -> ix -> Word8 -> ST s () -writeWord16Array :: Ix ix => MutableByteArray s ix -> ix -> Word16 -> ST s () -writeWord32Array :: Ix ix => MutableByteArray s ix -> ix -> Word32 -> ST s () -writeWord64Array :: Ix ix => MutableByteArray s ix -> ix -> Word64 -> ST s () -writeInt8Array :: Ix ix => MutableByteArray s ix -> ix -> Int8 -> ST s () -writeInt16Array :: Ix ix => MutableByteArray s ix -> ix -> Int16 -> ST s () -writeInt32Array :: Ix ix => MutableByteArray s ix -> ix -> Int32 -> ST s () -writeInt64Array :: Ix ix => MutableByteArray s ix -> ix -> 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 - -thawByteArray :: Ix ix => ByteArray ixt -> ST s (MutableByteArray s ix) -unsafeThawByteArray :: Ix ix => ByteArray ixt -> ST s (MutableByteArray s ix) - -</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> -<nidx>unsafeThawByteArray</nidx> -<nidx>thawByteArray</nidx> - -<bf/Remarks:/ -<itemize> -<item> +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 -> ix -> ST s Word8 +readWord16Array :: Ix ix => MutableByteArray s ix -> ix -> ST s Word16 +readWord32Array :: Ix ix => MutableByteArray s ix -> ix -> ST s Word32 +readWord64Array :: Ix ix => MutableByteArray s ix -> ix -> ST s Word64 +readInt8Array :: Ix ix => MutableByteArray s ix -> ix -> ST s Int8 +readInt16Array :: Ix ix => MutableByteArray s ix -> ix -> ST s Int16 +readInt32Array :: Ix ix => MutableByteArray s ix -> ix -> ST s Int32 +readInt64Array :: Ix ix => MutableByteArray s ix -> ix -> 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 -> ix -> Word8 -> ST s () +writeWord16Array :: Ix ix => MutableByteArray s ix -> ix -> Word16 -> ST s () +writeWord32Array :: Ix ix => MutableByteArray s ix -> ix -> Word32 -> ST s () +writeWord64Array :: Ix ix => MutableByteArray s ix -> ix -> Word64 -> ST s () +writeInt8Array :: Ix ix => MutableByteArray s ix -> ix -> Int8 -> ST s () +writeInt16Array :: Ix ix => MutableByteArray s ix -> ix -> Int16 -> ST s () +writeInt32Array :: Ix ix => MutableByteArray s ix -> ix -> Int32 -> ST s () +writeInt64Array :: Ix ix => MutableByteArray s ix -> ix -> 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 + +thawByteArray :: Ix ix => ByteArray ixt -> ST s (MutableByteArray s ix) +unsafeThawByteArray :: Ix ix => ByteArray ixt -> ST s (MutableByteArray s ix) +</ProgramListing> + +<IndexTerm><Primary>newCharArray</Primary></IndexTerm> +<IndexTerm><Primary>newAddrArray</Primary></IndexTerm> +<IndexTerm><Primary>newIntArray</Primary></IndexTerm> +<IndexTerm><Primary>newFloatArray</Primary></IndexTerm> +<IndexTerm><Primary>newDoubleArray</Primary></IndexTerm> +<IndexTerm><Primary>boundsOfMutableByteArray</Primary></IndexTerm> +<IndexTerm><Primary>readCharArray</Primary></IndexTerm> +<IndexTerm><Primary>readIntArray</Primary></IndexTerm> +<IndexTerm><Primary>readAddrArray</Primary></IndexTerm> +<IndexTerm><Primary>readFloatArray</Primary></IndexTerm> +<IndexTerm><Primary>readDoubleArray</Primary></IndexTerm> +<IndexTerm><Primary>readWord8Array</Primary></IndexTerm> +<IndexTerm><Primary>readWord16Array</Primary></IndexTerm> +<IndexTerm><Primary>readWord32Array</Primary></IndexTerm> +<IndexTerm><Primary>readWord64Array</Primary></IndexTerm> +<IndexTerm><Primary>readInt8Array</Primary></IndexTerm> +<IndexTerm><Primary>readInt16Array</Primary></IndexTerm> +<IndexTerm><Primary>readInt32Array</Primary></IndexTerm> +<IndexTerm><Primary>readInt64Array</Primary></IndexTerm> +<IndexTerm><Primary>writeCharArray</Primary></IndexTerm> +<IndexTerm><Primary>writeIntArray</Primary></IndexTerm> +<IndexTerm><Primary>writeAddrArray</Primary></IndexTerm> +<IndexTerm><Primary>writeFloatArray</Primary></IndexTerm> +<IndexTerm><Primary>writeDoubleArray</Primary></IndexTerm> +<IndexTerm><Primary>writeWord8Array</Primary></IndexTerm> +<IndexTerm><Primary>writeWord16Array</Primary></IndexTerm> +<IndexTerm><Primary>writeWord32Array</Primary></IndexTerm> +<IndexTerm><Primary>writeWord64Array</Primary></IndexTerm> +<IndexTerm><Primary>writeInt8Array</Primary></IndexTerm> +<IndexTerm><Primary>writeInt16Array</Primary></IndexTerm> +<IndexTerm><Primary>writeInt32Array</Primary></IndexTerm> +<IndexTerm><Primary>writeInt64Array</Primary></IndexTerm> +<IndexTerm><Primary>freezeCharArray</Primary></IndexTerm> +<IndexTerm><Primary>freezeIntArray</Primary></IndexTerm> +<IndexTerm><Primary>freezeAddrArray</Primary></IndexTerm> +<IndexTerm><Primary>freezeFloatArray</Primary></IndexTerm> +<IndexTerm><Primary>freezeDoubleArray</Primary></IndexTerm> +<IndexTerm><Primary>unsafeFreezeByteArray</Primary></IndexTerm> +<IndexTerm><Primary>unsafeThawByteArray</Primary></IndexTerm> +<IndexTerm><Primary>thawByteArray</Primary></IndexTerm> +</Para> + +<Para> +<Emphasis>Remarks:</Emphasis> + +<ItemizedList> +<ListItem> + +<Para> 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 +<ProgramListing> +mkPair :: ST s (MutableByteArray s Int) +mkPair = newIntArray (0,1) +</ProgramListing> + + +creates a mutable array capable of storing two <Literal>Int</Literal>s. Notice +that the range size <Emphasis>is not in bytes</Emphasis>, but in units of the basic type. -<item> +</Para> +</ListItem> +<ListItem> + +<Para> 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> +<ProgramListing> +isLitteEndian :: IO Bool +isLitteEndian = stToIO $ do + x <- newIntArray (0,1) + writeIntArray x 1 + v <- readCharArray x 0 + return (v == chr 1) +</ProgramListing> + 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> +</Para> +</ListItem> +<ListItem> +<Para> As for mutable arrays, operations for turning mutable byte arrays -into immutable byte arrays are also provided by the <tt/freeze*/ +into immutable byte arrays are also provided by the <Literal>freeze*</Literal> class of actions. There's also the non-copying -<tt/unsafeFreezeByteArray/. -<p> -<item> +<Literal>unsafeFreezeByteArray</Literal>. +</Para> +</ListItem> +<ListItem> + +<Para> Operations for going the other way, where an immutable byte -array is 'thawed' are also provided. <tt/thawByteArray/ does -this by copying, whereas <tt/unsafeThawByteArray/ does not +array is 'thawed' are also provided. <Literal>thawByteArray</Literal> does +this by copying, whereas <Literal>unsafeThawByteArray</Literal> does not + +</Para> +</ListItem> +<ListItem> + +<Para> +The operation <Literal>sizeofMutableByteArray</Literal> returns the size of +the array, <Emphasis>in bytes.</Emphasis> +</Para> +</ListItem> + +</ItemizedList> + +</Para> + +</Sect3> -<item> -The operation <tt/sizeofMutableByteArray/ returns the size of -the array, <em/in bytes./ -</itemize> +</Sect2> diff --git a/ghc/docs/users_guide/win32-dlls.sgml b/ghc/docs/users_guide/win32-dlls.sgml index 8c3090bea2..a26db275c6 100644 --- a/ghc/docs/users_guide/win32-dlls.sgml +++ b/ghc/docs/users_guide/win32-dlls.sgml @@ -1,31 +1,29 @@ -%************************************************************************ -%* * -<sect>Building and using Win32 DLLs -<label id="win32-dlls"> -<p> -<nidx>Dynamic link libraries, Win32</nidx> -<nidx>DLLs, Win32</nidx> -%* * -%************************************************************************ +<Chapter id="win32-dlls"> +<Title>Building and using Win32 DLLs +</Title> +<Para> +<IndexTerm><Primary>Dynamic link libraries, Win32</Primary></IndexTerm> +<IndexTerm><Primary>DLLs, Win32</Primary></IndexTerm> On Win32 platforms, the compiler is capable of both producing and using dynamic link libraries (DLLs) containing ghc-compiled code. This section shows you how to make use of this facility. +</Para> -%************************************************************************ -%* * -<sect1>Linking with DLLs -<label id="win32-dlls:link"> -<p> -%* * -%************************************************************************ +<Sect1 id="win32-dlls-link"> +<Title>Linking with DLLs +</Title> +<Para> The default on Win32 platforms is to link applications in such a way that the executables will use the Prelude and system libraries DLLs, rather than contain (large chunks of) them. This is transparent at the command-line, so +</Para> -<tscreen><verb> +<Para> + +<Screen> sh$ cat main.hs module Main where main = putStrLn "hello, world!" @@ -37,133 +35,186 @@ sh$ ls -l main.exe sh$ ./main hello, world! sh$ -</verb></tscreen> +</Screen> + +</Para> -will give you a binary as before, but the <tt>main.exe</tt> generated +<Para> +will give you a binary as before, but the <Literal>main.exe</Literal> generated will use the Prelude and RTS DLLs instead. +</Para> + +<Para> +6K for a <Literal>"hello, world"</Literal> application - not bad, huh? :-) +</Para> -6K for a <tt>"hello, world"</tt> application - not bad, huh? :-) +</Sect1> -%************************************************************************ -%* * -<sect1>Not linking with DLLs -<label id="win32-dlls:linking-static"> -<nidx>-static option (Win32)</nidx> -<p> -%* * -%************************************************************************ +<Sect1 id="win32-dlls-linking-static"> +<Title>Not linking with DLLs +<IndexTerm><Primary>-static option (Win32)</Primary></IndexTerm></Title> +<Para> If you want to build an executable that doesn't depend on any -ghc-compiled DLLs, use the <tt>-static</tt> option to link in +ghc-compiled DLLs, use the <Literal>-static</Literal> option to link in the code statically. +</Para> +<Para> Notice that you cannot mix code that has been compiled with -<tt>-static</tt> and not, so you have to use the <tt>-static</tt> +<Literal>-static</Literal> and not, so you have to use the <Literal>-static</Literal> option on all the Haskell modules that make up your application. +</Para> -%************************************************************************ -%* * -<sect1>Creating a DLL -<label id="win32-dlls:create"> -<p> -<nidx>Creating a Win32 DLL</nidx> -<nidx>--mk-dll</nidx> -%* * -%************************************************************************ +</Sect1> +<Sect1 id="win32-dlls-create"> +<Title>Creating a DLL +</Title> + +<Para> +<IndexTerm><Primary>Creating a Win32 DLL</Primary></IndexTerm> +<IndexTerm><Primary>--mk-dll</Primary></IndexTerm> Sealing up your Haskell library inside a DLL is quite straightforward; compile up the object files that make up the library, and then build the DLL by issuing the following command: +</Para> -<tscreen><verb> +<Para> +<Screen> sh$ ghc --mk-dll -o HSsuper.dll A.o Super.o B.o libmine.a -lgdi32 -</verb></tscreen> +</Screen> +</Para> -By feeding the ghc compiler driver the option <tt>--mk-dll</tt>, it +<Para> +By feeding the ghc compiler driver the option <Literal>--mk-dll</Literal>, it will build a DLL rather than produce an executable. The DLL will consist of all the object files and archives given on the command line. +</Para> +<Para> A couple of things to notice: +</Para> + +<Para> + +<ItemizedList> +<ListItem> -<itemize> -<item> -When compiling the module <tt>A</tt>, the code emitted by the compiler +<Para> +When compiling the module <Literal>A</Literal>, the code emitted by the compiler differs depending on whether or not the functions and data it is importing from other Haskell modules correspond to symbols that are packaged up in a ghc-compiled DLL. To resolve whether such imports are 'DLL imports' or not, the following rules are used: -<itemize> -<item> + +<ItemizedList> +<ListItem> + +<Para> If the compiler imports from a module that's in the same directory as the one being compiled, it is assumed to not belong to a different DLL (or executable) than the module being processed, so none of the same-directory imports are considered 'DLL imports'. -<item> +</Para> +</ListItem> +<ListItem> + +<Para> If a directory contains the (probably empty) file -<tt>dLL_ifs.hi</tt>, the code corresponding to the interface +<Literal>dLL_ifs.hi</Literal>, the code corresponding to the interface files found in that directory are assumed to live in a DLL separate from the one being compiled. Notice that the first rule takes precedence over this one, so if you're compiling a module that imports from a Haskell module whose -interface file live in the same directory, <em>and</em> that directory -also contains the file <tt>dLL_ifs.hi</tt>, the import is still not +interface file live in the same directory, <Emphasis>and</Emphasis> that directory +also contains the file <Literal>dLL_ifs.hi</Literal>, the import is still not being considered to be a 'DLL import'. -<item> -If compiling with the option <tt>-static</tt>, the previous rule +</Para> +</ListItem> +<ListItem> + +<Para> +If compiling with the option <Literal>-static</Literal>, the previous rule is disabled. -</itemize> +</Para> +</ListItem> + +</ItemizedList> + So, in short, after having built your Haskell DLL, make sure you -create the file <tt>dLL_ifs.hi</tt> in the directory that contains +create the file <Literal>dLL_ifs.hi</Literal> in the directory that contains its interface files. If you don't, Haskell code that calls upon entry points in that DLL, will do so incorrectly, and a crash will result. (it is unfortunate that this isn't currently caught at compile-time). -<item> +</Para> +</ListItem> +<ListItem> + +<Para> By default, the entry points of all the object files will -be exported from the DLL when using <tt>--mk-dll</tt>. Should you want -to constrain this, you can specify the <em>module definition file</em> +be exported from the DLL when using <Literal>--mk-dll</Literal>. Should you want +to constrain this, you can specify the <Emphasis>module definition file</Emphasis> to use on the command line as follows: -<tscreen><verb> + +<Screen> sh$ ghc --mk-dll -o .... -optdll--def -optdllMyDef.def -</verb></tscreen> +</Screen> + See Microsoft documentation for details, but a module definition file simply lists what entry points you want to export. Here's one that's suitable when building a Haskell COM server DLL: -<tscreen><verb> + +<ProgramListing> EXPORTS DllCanUnloadNow = DllCanUnloadNow@0 DllGetClassObject = DllGetClassObject@12 DllRegisterServer = DllRegisterServer@0 DllUnregisterServer = DllUnregisterServer@0 +</ProgramListing> + -</verb></tscreen> +</Para> +</ListItem> +<ListItem> -<item> -In addition to creating a DLL, the <tt>--mk-dll</tt> option will also +<Para> +In addition to creating a DLL, the <Literal>--mk-dll</Literal> option will also create an import library. The import library name is derived from the name of the DLL, as follows: -<tscreen><verb> - DLL: HScool.dll ==> import lib: libHScool_imp.a -</verb></tscreen> +<ProgramListing> +DLL: HScool.dll ==> import lib: libHScool_imp.a +</ProgramListing> + The naming scheme may look a bit weird, but it has the purpose of allowing the co-existence of import libraries with ordinary static -libraries (e.g., <tt>libHSfoo.a</tt> and <tt>libHSfoo_imp.a</tt>. +libraries (e.g., <Literal>libHSfoo.a</Literal> and <Literal>libHSfoo_imp.a</Literal>. Additionally, when the compiler driver is linking in non-static mode, -it will rewrite occurrence of <tt>-lHSfoo</tt> on the command line to -<tt>-lHSfoo_imp</tt>. By doing this for you, switching from non-static -to static linking is simply a question of adding <tt>-static</tt> to +it will rewrite occurrence of <Literal>-lHSfoo</Literal> on the command line to +<Literal>-lHSfoo_imp</Literal>. By doing this for you, switching from non-static +to static linking is simply a question of adding <Literal>-static</Literal> to your command line. -</itemize> +</Para> +</ListItem> + +</ItemizedList> + +</Para> + +</Sect1> + +</Chapter> |