% % $Id: libraries.vsgml,v 1.1 1998/01/30 17:02:32 simonm Exp $ % % GHC Prelude and Libraries. % The GHC prelude and libraries

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: GHC's additional non-standard libraries and types, such as state transformers, packed strings, foreign objects, stable pointers, and so on. 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. The organisation of these libraries into directories. Short description of programmer interface to the non-standard libraries provided in addition to the standard prelude. A number of the libraries that provide access to GHC's language extensions are shared by Hugs, and are described in the document. Prelude extensions

GHC's prelude contains the following non-standard extensions: @fromInt@ method in class @Num@: It's there. Converts from an @Int@ to the type. @toInt@ method in class @Integral@: Converts from type type to an @Int@. 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@-fglasgow-exts option flag). The module @PrelGHC@: really primitive stuff

This section defines all the types which are primitive in Glasgow Haskell, and the operations provided for them. A primitive type is one which cannot be defined in Haskell, and which is therefore built into the language and compiler. Primitive types are always unboxed; that is, a value of primitive type cannot be bottom. Primitive values are often represented by a simple bit-pattern, such as @Int#@, @Float#@, @Double#@. But this is not necessarily the case: a primitive value might be represented by a pointer to a heap-allocated object. Examples include @Array#@, the type of primitive arrays. You might think this odd: doesn't being heap-allocated mean that it has a box? No, it does not. A primitive array is heap-allocated because it is too big a value to fit in a register, and would be too expensive to copy around; in a sense, it is accidental that it is represented by a pointer. If a pointer represents a primitive value, then it really does point to that value: no unevaluated thunks, no indirections...nothing can be at the other end of the pointer than the primitive value. This section also describes a few non-primitive types, which are needed to express the result types of some primitive operations. Character and numeric types

character types, primitive numeric types, primitive integer types, primitive floating point types, primitive There are the following obvious primitive types: type Char# type Int# -- see also Word# and Addr#, later type Float# type Double# Char# Int# Float# Double# 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: 1# an Int# 1.2# a Float# 1.34## a Double# 'a'# a Char#; for weird characters, use '\o'# "a"# an Addr# (a `char *') literals, primitive constants, primitive numbers, primitive Comparison operations

comparisons, primitive operators, comparison {>,>=,==,/=,<,<=}# :: Int# -> Int# -> Bool {gt,ge,eq,ne,lt,le}Char# :: Char# -> Char# -> Bool -- ditto for Word# and Addr# ># >=# ==# /=# <# <=# gt{Char,Word,Addr}# ge{Char,Word,Addr}# eq{Char,Word,Addr}# ne{Char,Word,Addr}# lt{Char,Word,Addr}# le{Char,Word,Addr}# Primitive-character operations

characters, primitive operators, primitive character ord# :: Char# -> Int# chr# :: Int# -> Char# ord# chr# Primitive-@Int@ operations

integers, primitive operators, primitive integer {+,-,*,quotInt,remInt}# :: Int# -> Int# -> Int# negateInt# :: Int# -> Int# iShiftL#, iShiftRA#, iShiftRL# :: Int# -> Int# -> Int# -- shift left, right arithmetic, right logical +# -# *# quotInt# remInt# iShiftL# iShiftRA# iShiftRL# shift operations, integer Note: No error/overflow checking! Primitive-@Double@ and @Float@ operations

floating point numbers, primitive operators, primitive floating point {+,-,*,/}## :: 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# +## -## *## /## <## <=## ==## =/## >=## >## negateDouble# double2Int# int2Double# plusFloat# minusFloat# timesFloat# divideFloat# gtFloat# geFloat# eqFloat# neFloat# ltFloat# leFloat# negateFloat# float2Int# int2Float# And a full complement of trigonometric functions: expDouble# :: Double# -> Double# logDouble# :: Double# -> Double# sqrtDouble# :: Double# -> Double# sinDouble# :: Double# -> Double# cosDouble# :: Double# -> Double# tanDouble# :: Double# -> Double# asinDouble# :: Double# -> Double# acosDouble# :: Double# -> Double# atanDouble# :: Double# -> Double# sinhDouble# :: Double# -> Double# coshDouble# :: Double# -> Double# tanhDouble# :: Double# -> Double# powerDouble# :: Double# -> Double# -> Double# trigonometric functions, primitive similarly for @Float#@. There are two coercion functions for @Float#@/@Double#@: float2Double# :: Float# -> Double# double2Float# :: Double# -> Float# float2Double# double2Float# The primitive versions of @encodeDouble@/@decodeDouble@: encodeDouble# :: Int# -> Int# -> ByteArray# -- Integer mantissa -> Int# -- Int exponent -> Double# decodeDouble# :: Double# -> PrelNum.ReturnIntAndGMP encodeDouble# decodeDouble# (And the same for @Float#@s.) Operations on/for @Integers@ (interface to GMP)

arbitrary precision integers Integer, operations on We implement @Integers@ (arbitrary-precision integers) using the GNU multiple-precision (GMP) package (version 1.3.2). Note: 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 @ghc/includes/runtime/gmp@). It comes out as: data Integer = J# Int# Int# ByteArray# Integer type 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: 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?) Return2GMPs ReturnIntAndGMP The primitive ops to support @Integers@ use the ``pieces'' of the representation, and are as follows: negateInteger# :: Int# -> Int# -> ByteArray# -> Integer {plus,minus,times}Integer# :: Int# -> Int# -> ByteArray# -> Int# -> Int# -> ByteArray# -> Integer cmpInteger# :: Int# -> Int# -> ByteArray# -> Int# -> Int# -> ByteArray# -> Int# -- -1 for <; 0 for ==; +1 for > divModInteger#, quotRemInteger# :: Int# -> Int# -> ByteArray# -> Int# -> Int# -> ByteArray# -> PrelNum.Return2GMPs integer2Int# :: Int# -> Int# -> ByteArray# -> Int# int2Integer# :: Int# -> Integer -- NB: no error-checking on these two! word2Integer# :: Word# -> Integer addr2Integer# :: Addr# -> Integer -- the Addr# is taken to be a `char *' string -- to be converted into an Integer. negateInteger# plusInteger# minusInteger# timesInteger# cmpInteger# divModInteger# quotRemInteger# integer2Int# int2Integer# word2Integer# addr2Integer# Words and addresses

word, primitive type address, primitive type unsigned integer, primitive type pointer, primitive type A @Word#@ is used for bit-twiddling operations. It is the same size as an @Int#@, but has no sign nor any arithmetic operations. type Word# -- Same size/etc as Int# but *unsigned* type Addr# -- A pointer from outside the "Haskell world" (from C, probably); -- described under "arrays" Word# Addr# @Word#@s and @Addr#@s have the usual comparison operations. Other unboxed-@Word@ ops (bit-twiddling and coercions): and#, or#, xor# :: Word# -> Word# -> Word# -- standard bit ops. quotWord#, remWord# :: Word# -> Word# -> Word# -- word (i.e. unsigned) versions are different from int -- versions, so we have to provide these explicitly. not# :: Word# -> Word# shiftL#, shiftRA#, shiftRL# :: Word# -> Int# -> Word# -- shift left, right arithmetic, right logical int2Word# :: Int# -> Word# -- just a cast, really word2Int# :: Word# -> Int# bit operations, Word and Addr and# or# xor# not# quotWord# remWord# shiftL# shiftRA# shiftRL# int2Word# word2Int# Unboxed-@Addr@ ops (C casts, really): int2Addr# :: Int# -> Addr# addr2Int# :: Addr# -> Int# int2Addr# addr2Int# The casts between @Int#@, @Word#@ and @Addr#@ correspond to null operations at the machine level, but are required to keep the Haskell type checker happy. Operations for indexing off of C pointers (@Addr#@s) to snatch values are listed under ``arrays''. Arrays

arrays, primitive The type @Array# elt@ is the type of primitive, unpointed arrays of values of type @elt@. type Array# elt Array# @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 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. type ByteArray# ByteArray# 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 use them to build (say) arrays of unboxed characters for internal use in a Haskell program. Given these uses, @ByteArray#@ is deliberately a bit vague about the type of its components. Operations are provided to extract values of type @Char#@, @Int#@, @Float#@, @Double#@, and @Addr#@ from arbitrary offsets within a @ByteArray#@. (For type @Foo#@, the $i$th offset gets you the $i$th @Foo#@, not the @Foo#@ at byte-position $i$. Mumble.) (If you want a @Word#@, grab an @Int#@, then coerce it.) Lastly, we have static byte-arrays, of type @Addr#@ [mentioned previously]. (Remember the duality between arrays and pointers in C.) Arrays of this types are represented by a pointer to an array in the world outside Haskell, so this pointer is not followed by the garbage collector. In other respects they are just like @ByteArray#@. They are only needed in order to pass values from C to Haskell. Reading and writing

Primitive arrays are linear, and indexed starting at zero. The size and indices of a @ByteArray#@, @Addr#@, and @MutableByteArray#@ are all in bytes. It's up to the program to calculate the correct byte offset from the start of the array. This allows a @ByteArray#@ to contain a mixture of values of different type, which is often needed when preparing data for and unpicking results from C. (Umm... not true of indices... WDP 95/09) Should we provide some @sizeOfDouble#@ constants? Out-of-range errors on indexing should be caught by the code which uses the primitive operation; the primitive operations themselves do not 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 mutable arrays (see Section~), and ``indexing'' to refer to reading a value from an immutable array. Immutable byte arrays are straightforward to index (all indices in bytes): indexCharArray# :: ByteArray# -> Int# -> Char# indexIntArray# :: ByteArray# -> Int# -> Int# indexAddrArray# :: ByteArray# -> Int# -> Addr# indexFloatArray# :: ByteArray# -> Int# -> Float# indexDoubleArray# :: ByteArray# -> Int# -> Double# indexCharOffAddr# :: Addr# -> Int# -> Char# indexIntOffAddr# :: Addr# -> Int# -> Int# indexFloatOffAddr# :: Addr# -> Int# -> Float# indexDoubleOffAddr# :: Addr# -> Int# -> Double# indexAddrOffAddr# :: Addr# -> Int# -> Addr# -- Get an Addr# from an Addr# offset indexCharArray# indexIntArray# indexAddrArray# indexFloatArray# indexDoubleArray# indexCharOffAddr# indexIntOffAddr# indexFloatOffAddr# indexDoubleOffAddr# indexAddrOffAddr# The last of these, @indexAddrOffAddr#@, extracts an @Addr#@ using an offset from another @Addr#@, thereby providing the ability to follow a chain of C pointers. Something a bit more interesting goes on when indexing arrays of boxed objects, because the result is simply the boxed object. So presumably it should be entered --- we never usually return an unevaluated 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! indexArray# :: Array# elt -> Int# -> PrelBase.Lift elt -- Yuk! indexArray# The state type

state, primitive type State# 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 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. type State# s 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 not unboxed! Its only role in life is to be the type which distinguishes the @IO@ state transformer. data RealWorld State of the world

A single, primitive, value of type @State# RealWorld@ is provided. realWorld# :: State# GHC.RealWorld realWorld# state object (Note: in the compiler, not a @PrimOp@; just a mucho magic @Id@. Exported from @GHC@, though). State 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. data StateAndPtr# s elt = StateAndPtr# (State# s) elt data StateAndChar# s = StateAndChar# (State# s) Char# data StateAndInt# s = StateAndInt# (State# s) Int# data StateAndWord# s = StateAndWord# (State# s) Word# data StateAndFloat# s = StateAndFloat# (State# s) Float# data StateAndDouble# s = StateAndDouble# (State# s) Double# data StateAndAddr# s = StateAndAddr# (State# s) Addr# data StateAndStablePtr# s a = StateAndStablePtr# (State# s) (StablePtr# a) data StateAndForeignObj# s = StateAndForeignObj# (State# s) ForeignObj# data StateAndSynchVar# s a = StateAndSynchVar# (State# s) (SynchVar# a) data StateAndArray# s elt = StateAndArray# (State# s) (Array# elt) 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) Hideous. Mutable arrays

mutable arrays arrays, mutable 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. type MutableArray# s elt type MutableByteArray# s MutableArray# MutableByteArray# Allocation

mutable arrays, allocation arrays, allocation allocation, of mutable arrays 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. newArray# :: Int# -> elt -> State# s -> StateAndMutableArray# s elt newCharArray# :: Int# -> State# s -> StateAndMutableByteArray# s newIntArray# :: Int# -> State# s -> StateAndMutableByteArray# s newAddrArray# :: Int# -> State# s -> StateAndMutableByteArray# s newFloatArray# :: Int# -> State# s -> StateAndMutableByteArray# s newDoubleArray# :: Int# -> State# s -> StateAndMutableByteArray# s newArray# newCharArray# newIntArray# newAddrArray# newFloatArray# newDoubleArray# The size of a @ByteArray#@ is given in bytes. Reading and writing

arrays, reading and writing 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 readAddrArray# :: MutableByteArray# s -> Int# -> State# s -> StateAndAddr# s readFloatArray# :: MutableByteArray# s -> Int# -> State# s -> StateAndFloat# s readDoubleArray# :: MutableByteArray# s -> Int# -> State# s -> StateAndDouble# s writeArray# :: MutableArray# s elt -> Int# -> elt -> State# s -> State# s writeCharArray# :: MutableByteArray# s -> Int# -> Char# -> State# s -> State# s writeIntArray# :: MutableByteArray# s -> Int# -> Int# -> State# s -> State# 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 readArray# readCharArray# readIntArray# readAddrArray# readFloatArray# readDoubleArray# writeArray# writeCharArray# writeIntArray# writeAddrArray# writeFloatArray# writeDoubleArray# Equality

arrays, testing for equality One can take ``equality'' of mutable arrays. What is compared is the name or reference to the mutable array, not its contents. sameMutableArray# :: MutableArray# s elt -> MutableArray# s elt -> Bool sameMutableByteArray# :: MutableByteArray# s -> MutableByteArray# s -> Bool sameMutableArray# sameMutableByteArray# Freezing mutable arrays

arrays, freezing mutable freezing mutable arrays mutable arrays, freezing Only unsafe-freeze has a primitive. (Safe freeze is done directly in Haskell by copying the array and then using @unsafeFreeze@.) unsafeFreezeArray# :: MutableArray# s elt -> State# s -> StateAndArray# s elt unsafeFreezeByteArray# :: MutableByteArray# s -> State# s -> StateAndByteArray# s unsafeFreezeArray# unsafeFreezeByteArray# Stable pointers

stable pointers pointers, stable 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 not change when the Haskell garbage collector runs --- in contrast to the address of the object which may well change. The stable pointer type is parameterised by the type of the thing which is named. type StablePtr# a StablePtr# A stable pointer is represented by an index into the (static) @StablePointerTable@. The Haskell garbage collector treats the @StablePointerTable@ as a source of roots for GC. The @makeStablePointer@ function converts a value into a stable 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. makeStablePointer# :: a -> State# RealWorld -> StateAndStablePtr# RealWorld a freeStablePointer# :: StablePtr# a -> State# RealWorld -> State# RealWorld deRefStablePointer# :: StablePtr# a -> State# RealWorld -> StateAndPtr RealWorld a makeStablePointer# freeStablePointer# deRefStablePointer# There is also a C procedure @FreeStablePtr@ which frees a stable pointer. %Andy's comment. {\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 %limited number (3) of these routines. It might be possible to %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. %End of Andy's comment. Foreign objects

Foreign objects 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 ...''. type ForeignObj# ForeignObj# GHC provides two primitives on @ForeignObj#@: makeForeignObj# :: Addr# -- foreign reference -> Addr# -- pointer to finalisation routine -> StateAndForeignObj# RealWorld ForeignObj# writeForeignObj :: ForeignObj# -- foreign object -> Addr# -- datum -> State# RealWorld -> State# RealWorld makeForeignObj# writeForeignObj# The module @Foreign@ (Section ) provides a more programmer-friendly interface to foreign objects. Synchronizing variables (M-vars)

synchronising variables (M-vars) M-Vars 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). 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 SynchVar# newSynchVar# takeMVar putMVar @spark#@ primitive operation (for parallel execution)

spark primitive operation ToDo: say something It's used in the unfolding for @par@. The @errorIO#@ primitive operation

errors, primitive 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. errorIO# :: (State# RealWorld# -> a) -> a errorIO# 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) %ToDo: index these. 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 .