From 8b71efe0f44c79401f42c8d37ab13ce61dcf5516 Mon Sep 17 00:00:00 2001 From: sof 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 69b565b..9180795 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. Two functions exported from Two new functions exported from diff --git a/ghc/docs/users_guide/ByteArray.sgml b/ghc/docs/users_guide/ByteArray.sgml new file mode 100644 index 0000000..69fae3e --- /dev/null +++ b/ghc/docs/users_guide/ByteArray.sgml @@ -0,0 +1,45 @@ +The +

+ByteArray interface (GHC extensions) + + +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 + + + +The operation + +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. + + diff --git a/ghc/docs/users_guide/Makefile b/ghc/docs/users_guide/Makefile index da031a0..3425899 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 0000000..31c705f --- /dev/null +++ b/ghc/docs/users_guide/MutableArray.sgml @@ -0,0 +1,200 @@ + +

+ +The +

+ +The mutable array section of the API provides the following +operations: + + + +-- 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) + +newArray +boundsOfArray +readArray +writeArray +freezeArray +thawArray +unsafeFreezeArray + + + +The +The operation + + +

+ + +-- 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 + + +newCharArray +newAddrArray +newIntArray +newFloatArray +newDoubleArray +boundsOfMutableByteArray +readCharArray +readIntArray +readAddrArray +readFloatArray +readDoubleArray +readWord8Array +readWord16Array +readWord32Array +readWord64Array +readInt8Array +readInt16Array +readInt32Array +readInt64Array +writeCharArray +writeIntArray +writeAddrArray +writeFloatArray +writeDoubleArray +writeWord8Array +writeWord16Array +writeWord32Array +writeWord64Array +writeInt8Array +writeInt16Array +writeInt32Array +writeInt64Array +freezeCharArray +freezeIntArray +freezeAddrArray +freezeFloatArray +freezeDoubleArray +unsafeFreezeByteArray + + + +A Mutable byte array is created by specifying its size in units of +some basic type. For example, + + + mkPair :: ST s (MutableByteArray s Int) + mkPair = newIntArray (0,1) + + +creates a mutable array capable of storing two +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., + + + isLitteEndian :: IO Bool + isLitteEndian = stToIO $ do + x <- newIntArray (0,1) + writeIntArray x 1 + v <- readCharArray x 0 + return (v == chr 1) + + +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.. + + +As for mutable arrays, operations for turning mutable byte arrays +into immutable byte arrays are also provided by the +Thawing of byte arrays is currently not supported. + + +The operation diff --git a/ghc/docs/users_guide/libraries.vsgml b/ghc/docs/users_guide/libraries.vsgml index 9e666b5..cd83792 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@-fglasgow-exts option flag). + +GHC/Hugs Extension Libraries +

+ +The extension libraries provided by both GHC and Hugs are described in +the + + +GHC-only Extension Libraries +

+libraries, ghc-only +extension libraries, ghc-only + +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 exactly as the +Haskell report says (modulo a few minor issues, see Section ). + +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; + +The @CCall@ module +

+ +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 +. + +The @GlaExts@ interface +

+GlaExts interface (GHC extensions) + +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). + + +-- 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. + + The module @PrelGHC@: really primitive stuff

@@ -823,257 +890,3 @@ putMVar# :: SynchVar# s elt -> State# s -> State# s newSynchVar# takeMVar putMVar - -GHC/Hugs Extension Libraries -

- -The extension libraries provided by both GHC and Hugs are described in -the -document. - -GHC-only Extension Libraries -

-libraries, ghc-only -extension libraries, ghc-only - -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 exactly as the -Haskell report says (modulo a few minor issues, see Section ). - -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. - -The @GlaExts@ interface -

-GlaExts interface (GHC extensions) - -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). - - --- 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. - - -The @MutableArray@ interface -

-MutableArray interface (GHC extensions) - -The @MutableArray@ interface defines a general set of operations over -mutable arrays (@MutableArray@) and mutable chunks of memory -(@MutableByteArray@): - - -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) - - -newArray -newCharArray -newAddrArray -newIntArray -newFloatArray -newDoubleArray -boundsOfArray -boundsOfByteArray -readArray -readCharArray -readIntArray -readAddrArray -readFloatArray -readDoubleArray -writeArray -writeCharArray -writeIntArray -writeAddrArray -writeFloatArray -writeDoubleArray -freezeArray -freezeCharArray -freezeIntArray -freezeAddrArray -freezeFloatArray -freezeDoubleArray -unsafeFreezeArray -unsafeFreezeByteArray -thawArray - -The @ByteArray@ interface -

-ByteArray interface (GHC extensions) - -@ByteArray@s are chunks of immutable Haskell heap: - - -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 - - -Stable pointers -

- -Nothing exciting here, just simple boxing up. - -data StablePtr a = StablePtr (StablePtr# a) - -makeStablePointer :: a -> StablePtr a -freeStablePointer :: StablePtr a -> IO () - - -Foreign objects -

-Foreign objects - -This module provides the @ForeignObj@ type and wrappers around the -primitive operations on foreign objects. - - -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 () - - -ForeignObj -makeForeignObj -writeForeignObj - -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. - - -data Image = Image ForeignObj - - -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: - - -createImage :: (Int,Int) -> IO Image - - -So far, this looks just like an @Addr@ type, but @ForeignObj@ offers a -bit more, namely that we can specify a finalisation routine 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. - -The @CCall@ module -

- -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 -. - diff --git a/ghc/docs/users_guide/runtime_control.vsgml b/ghc/docs/users_guide/runtime_control.vsgml index ccb553e..eb1da49 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 - + + ]>

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 -- 1.7.10.4