2 \documentstyle[a4wide,grasp]{article}
4 \renewcommand{\textfraction}{0.1}
5 \renewcommand{\floatpagefraction}{0.9}
6 \renewcommand{\dblfloatpagefraction}{0.9}
9 \renewcommand{\today}{March 1997}
13 \title{The GHC Prelude and Libraries}
14 \author{Simon L Peyton Jones \and Will Partain}
22 \section[ghc-prelude]{The GHC prelude and libraries}
24 This document describes GHC's prelude and libraries. The basic story is that of
25 the Haskell 1.4 Report and Libraries document (which we do not reproduce here),
26 but this document describes in addition:
28 \item GHC's additional non-standard libraries and types, such as
29 state transformers, packed strings, foreign objects, stable
32 \item GHC's primitive types and operations. The standard Haskell
33 functions are implemented on top of these, and it is sometimes
34 useful to use them directly.
36 \item The organisation of these libraries into directories.
37 \item Short description of programmer interface to the non-standard,
38 `built-in' libraries provided in addition to the standard
39 prelude and libraries.
42 In addition to the GHC prelude libraries, GHC comes with a number of
43 system libraries, which are presented in \ref{syslibs}.
45 \subsection{Prelude library organisation}
47 {\em Probably only of interest to implementors..}
49 The prelude libraries are organised into the following three groups,
50 each of which is kept in a separate sub-directory of GHC's source
53 \item[@lib/required/@] These are the libraries {\em required} by the
54 Haskell definition. All are defined by the Haskell Report, or by the
55 Haskell Libraries Report.
56 They currently comprise:
59 \item @List@: more functions on lists.
60 \item @Char@: more functions on characters.
61 \item @Maybe@: more functions on @Maybe@ types.
62 \item @Complex@: interface defining complex number type and functions over it.
63 \item @Ratio@: functions on rational numbers.
64 \item @Monad@: functions on monads.
65 \item @Ix@: the @Ix@ class of indexing operations.
66 \item @Array@: monolithic arrays.
67 \item @IO@: additional input/output functions.
68 \item @Directory@: basic functions for accessing the file system.
69 \item @System@: basic operating-system interface functions.
70 \item @Numeric@: operations for reading and showing number values.
73 \item[@lib/glaExts@] GHC extension libraries, currently comprising:
75 \item @GlaExts@: collector interface to the various Glasgow
76 extensions, primitive operations.
77 \item @PackedString@: functions that manipulate strings packed efficiently, one character per byte.
78 \item @ST@: the state transformer monad.
79 \item @Foreign@: types and operations for GHC's foreign-language interface.
80 \item @ByteArray@: operations over immutable chunks of (heap allocated) bytes.
81 \item @MutableArray@: operations over mutable arrays.
82 \item @MutVar@: operations over mutable variables.
85 \item[@lib/concurrent@] GHC extension libraries to support Concurrent Haskell, currently comprising:
87 \item @Concurrent@: main library.
88 \item @Parallel@: stuff for multi-processor parallelism.
96 \item[@lib/ghc@] These libraries are the pieces on which all the others are built.
97 They aren't typically imported by Joe Programmer, but there's nothing to stop you
98 doing so if you want. In general, the modules prefixed by @Prel@ are pieces that go
99 towards building @Prelude@.
102 \item @GHC@: this ``library'' brings into scope all the primitive types and operations, such as
103 @Int#@, @+#@, @encodeFloat#@, etc etc. It is unique in that there is no Haskell
104 source code for it. Details in Section \ref{sect:ghc}.
106 \item @PrelBase@: defines the basic types and classes without which very few Haskell programs can work.
107 The classes are: @Eq@, @Ord@, @Enum@, @Bounded@, @Num@, @Show@, @Eval@, @Monad@, @MonadZero@, @MonadPlus@.
108 The types are: list, @Bool@, @Char@, @Ordering@, @String@, @Int@, @Integer@, @Maybe@, @Either@.
110 \item @PrelTup@: defines tuples and their instances.
111 \item @PrelList@: defines most of the list operations required by @Prelude@. (A few are in @PrelBase@,
112 to avoid gratuitous mutual recursion between modules.)
114 \item @PrelNum@ defines: the numeric classes beyond @Num@, namely
115 @Real@, @Integral@, @Fractional@, @Floating@, @RealFrac@, @RealFloat@;
116 instances for appropriate classes for @Int@ and @Integer@; the types
117 @Float@, @Double@, and @Ratio@ and their instances.
119 \item @PrelRead@: the @Read@ class and all its instances. It's kept
120 separate because many programs don't use @Read@ at all, so we don't
121 even want to link in its code. (If the prelude libraries are built by
122 splitting the object files, this is all a non-issue)
124 \item @ConcBase@: substrate stuff for Concurrent Haskell.
126 \item @IOBase@: substrate stuff for the main I/O libraries.
127 \item @IOHandle@: large blob of code for doing I/O on handles.
128 \item @PrelIO@: the remaining small pieces to produce the I/O stuff needed by @Prelude@.
130 \item @STBase@: substrate stuff for @ST@.
131 \item @ArrBase@: substrate stuff for @Array@.
133 \item @GHCerr@: error reporting code, called from code that the compiler plants in compiled programs.
134 \item @GHCmain@: the definition of @mainPrimIO@, which is what {\em really} gets
135 called by the runtime system. @mainPrimIO@ in turn calls @main@.
139 The @...Base@ modules generally export representation information that
140 is hidden from the public interface. For example the module @STBase@
141 exports the type @ST@ including its representation, whereas the module
142 @ST@ exports @ST@ abstractly.
144 None of these modules are involved in any mutual recursion, with the
145 sole exception that many modules import @IOBase.error@.
147 \subsection{The module @GHC@: really primitive stuff}
150 This section defines all the types which are primitive in Glasgow
151 Haskell, and the operations provided for them.
153 A primitive type is one which cannot be defined in Haskell, and which
154 is therefore built into the language and compiler. Primitive types
155 are always unboxed; that is, a value of primitive type cannot be
158 Primitive values are often represented by a simple bit-pattern, such as @Int#@,
159 @Float#@, @Double#@. But this is not necessarily the case: a primitive value
160 might be represented by a pointer to a heap-allocated object. Examples include
161 @Array#@, the type of primitive arrays. You might think this odd: doesn't being
162 heap-allocated mean that it has a box? No, it does not. A primitive array is
163 heap-allocated because it is too big a value to fit in a register, and would be
164 too expensive to copy around; in a sense, it is accidental that it is represented
165 by a pointer. If a pointer represents a primitive value, then it really does
166 point to that value: no unevaluated thunks, no indirections...nothing can be at
167 the other end of the pointer than the primitive value.
169 This section also describes a few non-primitive types, which are needed
170 to express the result types of some primitive operations.
172 \subsubsection{Character and numeric types}
174 There are the following obvious primitive types:
177 type Int# -- see also Word# and Addr#, later
181 If you really want to know their exact equivalents in C, see
182 @ghc/includes/StgTypes.lh@ in the GHC source tree.
184 Literals for these types may be written as follows:
189 'a'# a Char#; for weird characters, use '\o<octal>'#
190 "a"# an Addr# (a `char *')
193 \subsubsubsection{Comparison operations}
195 {gt,ge,eq,ne,lt,le}Char# :: Char# -> Char# -> Bool
196 -- ditto for Int#, Word#, Float#, Double#, and Addr#
199 \subsubsubsection{Unboxed-character operations}
201 ord# :: Char# -> Int#
202 chr# :: Int# -> Char#
206 \subsubsubsection{Unboxed-@Int@ operations}
208 {plus,minus,times,quot,div,rem}Int# :: Int# -> Int# -> Int#
209 negateInt# :: Int# -> Int#
212 \bf{Note:} No error/overflow checking!
214 \subsubsubsection{Unboxed-@Double@ and @Float@ operations}
216 {plus,minus,times,divide}Double# :: Double# -> Double# -> Double#
217 negateDouble# :: Double# -> Double#
219 float2Int# :: Double# -> Int# -- just a cast, no checking!
220 int2Double# :: Int# -> Double#
222 expDouble# :: Double# -> Double#
223 logDouble# :: Double# -> Double#
224 sqrtDouble# :: Double# -> Double#
225 sinDouble# :: Double# -> Double#
226 cosDouble# :: Double# -> Double#
227 tanDouble# :: Double# -> Double#
228 asinDouble# :: Double# -> Double#
229 acosDouble# :: Double# -> Double#
230 atanDouble# :: Double# -> Double#
231 sinhDouble# :: Double# -> Double#
232 coshDouble# :: Double# -> Double#
233 tanhDouble# :: Double# -> Double#
234 powerDouble# :: Double# -> Double# -> Double#
237 There's an exactly-matching set of unboxed-@Float@ ops; replace
238 @Double#@ with @Float#@ in the list above. There are two
239 coercion functions for @Float#@/@Double#@:
241 float2Double# :: Float# -> Double#
242 double2Float# :: Double# -> Float#
245 The primitive versions of @encodeDouble@/@decodeDouble@:
247 encodeDouble# :: Int# -> Int# -> ByteArray# -- Integer mantissa
248 -> Int# -- Int exponent
251 decodeDouble# :: Double# -> PrelNum.ReturnIntAndGMP
254 (And the same for @Float#@s.)
256 \subsubsection{Operations on/for @Integers@ (interface to GMP)}
257 \label{sect:horrid-Integer-pairing-types}
259 We implement @Integers@ (arbitrary-precision integers) using the GNU
260 multiple-precision (GMP) package (version 1.3.2).
262 \bf{Note:} some of this might change when we upgrade to using GMP~2.x.
264 The data type for @Integer@ must mirror that for @MP_INT@ in @gmp.h@
265 (see @gmp.info@ in \tr{ghc/includes/runtime/gmp}). It comes out as:
267 data Integer = J# Int# Int# ByteArray#
270 So, @Integer@ is really just a ``pairing'' type for a particular
271 collection of primitive types.
273 The operations in the GMP return other combinations of
274 GMP-plus-something, so we need ``pairing'' types for those, too:
276 data Return2GMPs = Return2GMPs Int# Int# ByteArray# Int# Int# ByteArray#
277 data ReturnIntAndGMP = ReturnIntAndGMP Int# Int# Int# ByteArray#
279 -- ????? something to return a string of bytes (in the heap?)
282 The primitive ops to support @Integers@ use the ``pieces'' of the
283 representation, and are as follows:
285 negateInteger# :: Int# -> Int# -> ByteArray# -> Integer
287 {plus,minus,times}Integer# :: Int# -> Int# -> ByteArray#
288 -> Int# -> Int# -> ByteArray#
291 cmpInteger# :: Int# -> Int# -> ByteArray#
292 -> Int# -> Int# -> ByteArray#
293 -> Int# -- -1 for <; 0 for ==; +1 for >
295 divModInteger#, quotRemInteger#
296 :: Int# -> Int# -> ByteArray#
297 -> Int# -> Int# -> ByteArray#
298 -> PrelNum.Return2GMPs
300 integer2Int# :: Int# -> Int# -> ByteArray# -> Int#
302 int2Integer# :: Int# -> Integer -- NB: no error-checking on these two!
303 word2Integer# :: Word# -> Integer
305 addr2Integer# :: Addr# -> Integer
306 -- the Addr# is taken to be a `char *' string
307 -- to be converted into an Integer.
311 \subsubsection{Words and addresses}
313 A @Word#@ is used for bit-twiddling operations. It is the same size as
314 an @Int#@, but has no sign nor any arithmetic operations.
316 type Word# -- Same size/etc as Int# but *unsigned*
317 type Addr# -- A pointer from outside the "Haskell world" (from C, probably);
318 -- described under "arrays"
321 @Word#@s and @Addr#@s have the usual comparison operations.
322 Other unboxed-@Word@ ops (bit-twiddling and coercions):
324 and#, or# :: Word# -> Word# -> Word#
326 not# :: Word# -> Word#
328 shiftL#, shiftRA#, shiftRL# :: Word# -> Int# -> Word#
329 -- shift left, right arithmetic, right logical
331 iShiftL#, iShiftRA#, iShiftRL# :: Int# -> Int# -> Int#
332 -- same shift ops, but on Int#s
334 int2Word# :: Int# -> Word# -- just a cast, really
335 word2Int# :: Word# -> Int#
339 Unboxed-@Addr@ ops (C casts, really):
341 int2Addr# :: Int# -> Addr#
342 addr2Int# :: Addr# -> Int#
345 Operations for indexing off of C pointers (@Addr#@s) to snatch values
346 are listed under ``arrays''.
348 \subsubsection{Arrays}
350 The type @Array# elt@ is the type of primitive,
351 unboxed arrays of values of type @elt@.
356 @Array#@ is more primitive than a Haskell array --- indeed, the
357 Haskell @Array@ interface is implemented using @Array#@ --- in that an
358 @Array#@ is indexed only by @Int#@s, starting at zero. It is also
359 more primitive by virtue of being unboxed. That doesn't mean that it
360 isn't a heap-allocated object --- of course, it is. Rather, being
361 unboxed means that it is represented by a pointer to the array itself,
362 and not to a thunk which will evaluate to the array (or to bottom).
363 The components of an @Array#@ are themselves boxed.
365 The type @ByteArray#@ is similar to @Array#@, except that it contains
366 just a string of (non-pointer) bytes.
371 Arrays of these types are useful when a Haskell program wishes to
372 construct a value to pass to a C procedure. It is also possible to
373 use them to build (say) arrays of unboxed characters for internal use
374 in a Haskell program. Given these uses, @ByteArray#@ is deliberately
375 a bit vague about the type of its components. Operations are provided
376 to extract values of type @Char#@, @Int#@, @Float#@, @Double#@, and
377 @Addr#@ from arbitrary offsets within a @ByteArray#@. (For type
378 @Foo#@, the $i$th offset gets you the $i$th @Foo#@, not the @Foo#@ at
379 byte-position $i$. Mumble.) (If you want a @Word#@, grab an @Int#@,
382 Lastly, we have static byte-arrays, of type @Addr#@ [mentioned
383 previously]. (Remember the duality between arrays and pointers in C.)
384 Arrays of this types are represented by a pointer to an array in the
385 world outside Haskell, so this pointer is not followed by the garbage
386 collector. In other respects they are just like @ByteArray#@. They
387 are only needed in order to pass values from C to Haskell.
389 \subsubsubsection{Reading and writing.}
391 Primitive arrays are linear, and indexed starting at zero.
393 The size and indices of a @ByteArray#@, @Addr#@, and
394 @MutableByteArray#@ are all in bytes. It's up to the program to
395 calculate the correct byte offset from the start of the array. This
396 allows a @ByteArray#@ to contain a mixture of values of different
397 type, which is often needed when preparing data for and unpicking
398 results from C. (Umm... not true of indices... WDP 95/09)
400 {\em Should we provide some @sizeOfDouble#@ constants?}
402 Out-of-range errors on indexing should be caught by the code which
403 uses the primitive operation; the primitive operations themselves do
404 {\em not} check for out-of-range indexes. The intention is that the
405 primitive ops compile to one machine instruction or thereabouts.
407 We use the terms ``reading'' and ``writing'' to refer to accessing
408 {\em mutable} arrays (see Section~\ref{sect:mutable}), and
409 ``indexing'' to refer to reading a value from an {\em immutable}
412 If you want to read/write a @Word#@, read an @Int#@ and coerce.
414 Immutable byte arrays are straightforward to index (all indices in bytes):
416 indexCharArray# :: ByteArray# -> Int# -> Char#
417 indexIntArray# :: ByteArray# -> Int# -> Int#
418 indexAddrArray# :: ByteArray# -> Int# -> Addr#
419 indexFloatArray# :: ByteArray# -> Int# -> Float#
420 indexDoubleArray# :: ByteArray# -> Int# -> Double#
422 indexCharOffAddr# :: Addr# -> Int# -> Char#
423 indexIntOffAddr# :: Addr# -> Int# -> Int#
424 indexFloatOffAddr# :: Addr# -> Int# -> Float#
425 indexDoubleOffAddr# :: Addr# -> Int# -> Double#
426 indexAddrOffAddr# :: Addr# -> Int# -> Addr#
427 -- Get an Addr# from an Addr# offset
430 The last of these, @indexAddrOffAddr#@, extracts an @Addr#@ using an offset
431 from another @Addr#@, thereby providing the ability to follow a chain of
434 Something a bit more interesting goes on when indexing arrays of boxed
435 objects, because the result is simply the boxed object. So presumably
436 it should be entered --- we never usually return an unevaluated
437 object! This is a pain: primitive ops aren't supposed to do
438 complicated things like enter objects. The current solution is to
439 return a lifted value, but I don't like it!
441 indexArray# :: Array# elt -> Int# -> PrelBase.Lift elt -- Yuk!
445 \subsubsection{The state type}
447 The primitive type @State#@ represents the state of a state transformer.
448 It is parameterised on the desired type of state, which serves to keep
449 states from distinct threads distinct from one another. But the {\em only}
450 effect of this parameterisation is in the type system: all values of type
451 @State#@ are represented in the same way. Indeed, they are all
452 represented by nothing at all! The code generator ``knows'' to generate no
453 code, and allocate no registers etc, for primitive states.
459 The type @GHC.RealWorld@ is truly opaque: there are no values defined
460 of this type, and no operations over it. It is ``primitive'' in that
461 sense---but it is {\em not unboxed!} Its only role in life is to be the type
462 which distinguishes the @PrimIO@ state transformer (see
463 Section~\ref{sect:io-spec}).
468 \subsubsubsection{States}
470 A single, primitive, value of type @State# RealWorld@ is provided.
472 realWorld# :: State# GHC.RealWorld
475 (Note: in the compiler, not a @PrimOp@; just a mucho magic
476 @Id@. Exported from @GHC@, though).
478 \subsubsection{State pairing types}
479 \label{sect:horrid-pairing-types}
481 This subsection defines some types which, while they aren't quite
482 primitive because we can define them in Haskell, are very nearly so.
483 They define constructors which pair a primitive state with a value of
484 each primitive type. They are required to express the result type of
485 the primitive operations in the state monad.
487 data StateAndPtr# s elt = StateAndPtr# (State# s) elt
489 data StateAndChar# s = StateAndChar# (State# s) Char#
490 data StateAndInt# s = StateAndInt# (State# s) Int#
491 data StateAndWord# s = StateAndWord# (State# s) Word#
492 data StateAndFloat# s = StateAndFloat# (State# s) Float#
493 data StateAndDouble# s = StateAndDouble# (State# s) Double#
494 data StateAndAddr# s = StateAndAddr# (State# s) Addr#
496 data StateAndStablePtr# s a = StateAndStablePtr# (State# s) (StablePtr# a)
497 data StateAndForeignObj# s = StateAndForeignObj# (State# s) ForeignObj#
498 data StateAndSynchVar# s a = StateAndSynchVar# (State# s) (SynchVar# a)
500 data StateAndArray# s elt = StateAndArray# (State# s) (Array# elt)
501 data StateAndMutableArray# s elt = StateAndMutableArray# (State# s) (MutableArray# s elt)
502 data StateAndByteArray# s = StateAndByteArray# (State# s) ByteArray#
503 data StateAndMutableByteArray# s = StateAndMutableByteArray# (State# s) (MutableByteArray# s)
508 \subsubsection{Mutable arrays}
511 Corresponding to @Array#@ and @ByteArray#@, we have the types of
512 mutable versions of each. In each case, the representation is a
513 pointer to a suitable block of (mutable) heap-allocated storage.
515 type MutableArray# s elt
516 type MutableByteArray# s
519 \subsubsubsection{Allocation.}
521 Mutable arrays can be allocated. Only pointer-arrays are initialised;
522 arrays of non-pointers are filled in by ``user code'' rather than by
523 the array-allocation primitive. Reason: only the pointer case has to
524 worry about GC striking with a partly-initialised array.
527 newArray# :: Int# -> elt -> State# s -> StateAndMutableArray# s elt
529 newCharArray# :: Int# -> State# s -> StateAndMutableByteArray# s
530 newIntArray# :: Int# -> State# s -> StateAndMutableByteArray# s
531 newAddrArray# :: Int# -> State# s -> StateAndMutableByteArray# s
532 newFloatArray# :: Int# -> State# s -> StateAndMutableByteArray# s
533 newDoubleArray# :: Int# -> State# s -> StateAndMutableByteArray# s
536 The size of a @ByteArray#@ is given in bytes.
538 \subsubsubsection{Reading and writing}
540 %OLD: Remember, offsets in a @MutableByteArray#@ are in bytes.
542 readArray# :: MutableArray# s elt -> Int# -> State# s -> StateAndPtr# s elt
543 readCharArray# :: MutableByteArray# s -> Int# -> State# s -> StateAndChar# s
544 readIntArray# :: MutableByteArray# s -> Int# -> State# s -> StateAndInt# s
545 readAddrArray# :: MutableByteArray# s -> Int# -> State# s -> StateAndAddr# s
546 readFloatArray# :: MutableByteArray# s -> Int# -> State# s -> StateAndFloat# s
547 readDoubleArray# :: MutableByteArray# s -> Int# -> State# s -> StateAndDouble# s
549 writeArray# :: MutableArray# s elt -> Int# -> elt -> State# s -> State# s
550 writeCharArray# :: MutableByteArray# s -> Int# -> Char# -> State# s -> State# s
551 writeIntArray# :: MutableByteArray# s -> Int# -> Int# -> State# s -> State# s
552 writeAddrArray# :: MutableByteArray# s -> Int# -> Addr# -> State# s -> State# s
553 writeFloatArray# :: MutableByteArray# s -> Int# -> Float# -> State# s -> State# s
554 writeDoubleArray# :: MutableByteArray# s -> Int# -> Double# -> State# s -> State# s
558 \subsubsubsection{Equality.}
560 One can take ``equality'' of mutable arrays. What is compared is the
561 {\em name} or reference to the mutable array, not its contents.
563 sameMutableArray# :: MutableArray# s elt -> MutableArray# s elt -> Bool
564 sameMutableByteArray# :: MutableByteArray# s -> MutableByteArray# s -> Bool
568 \subsubsubsection{Freezing mutable arrays}
570 Only unsafe-freeze has a primitive. (Safe freeze is done directly in Haskell
571 by copying the array and then using @unsafeFreeze@.)
573 unsafeFreezeArray# :: MutableArray# s elt -> State# s -> StateAndArray# s elt
574 unsafeFreezeByteArray# :: MutableByteArray# s -> State# s -> StateAndByteArray# s
578 \subsubsubsection{Stable pointers}
580 A stable pointer is a name for a Haskell object which can be passed to
581 the external world. It is ``stable'' in the sense that the name does
582 not change when the Haskell garbage collector runs --- in contrast to
583 the address of the object which may well change.
585 The stable pointer type is parameterised by the type of the thing
591 A stable pointer is represented by an index into the (static)
592 @StablePointerTable@. The Haskell garbage collector treats the
593 @StablePointerTable@ as a source of roots for GC.
595 The @makeStablePointer@ function converts a value into a stable
596 pointer. It is part of the @PrimIO@ monad, because we want to be sure
597 we don't allocate one twice by accident, and then only free one of the
600 makeStablePointer# :: a -> State# RealWorld -> StateAndStablePtr# RealWorld a
601 freeStablePointer# :: StablePtr# a -> State# RealWorld -> State# RealWorld
602 deRefStablePointer# :: StablePtr# a -> State# RealWorld -> StateAndPtr RealWorld a
605 There is also a C procedure @FreeStablePtr@ which frees a stable pointer.
607 %{\em Andy's comment.} \bf{Errors:} The following is not strictly true: the current
608 %implementation is not as polymorphic as claimed. The reason for this
609 %is that the C programmer will have to use a different entry-routine
610 %for each type of stable pointer. At present, we only supply a very
611 %limited number (3) of these routines. It might be possible to
612 %increase the range of these routines by providing general purpose
613 %entry points to apply stable pointers to (stable pointers to)
614 %arguments and to enter (stable pointers to) boxed primitive values.
615 %{\em End of Andy's comment.}
619 % Rewritten and updated for MallocPtr++ -- 4/96 SOF
621 \subsubsubsection{Foreign objects}
623 A @ForeignObj@ is a reference to an object outside the Haskell world
624 (i.e., from the C world, or a reference to an object on another
625 machine completely.), where the Haskell world has been told ``Let me
626 know when you're finished with this ...''.
628 %OLD:The @ForeignObj@ type is just a special @Addr#@ ({\em not} parameterised).
633 A typical use of @ForeignObj#@ is in constructing Haskell bindings
634 to external libraries. A good example is that of writing a binding to
635 an image-processing library (which was actually the main motivation
636 for implementing @ForeignObj#@'s precursor, @MallocPtr#@). The
637 images manipulated are not stored in the Haskell heap, either because
638 the library insist on allocating them internally or we (sensibly)
639 decide to spare the GC from having to heave heavy images around.
642 data Image = Image ForeignObj#
644 instance CCallable Image
647 The @ForeignObj#@ type is then used to refer to the externally
648 allocated image, and to acheive some type safety, the Haskell binding
649 defines the @Image@ data type. So, a value of type @ForeignObj#@ is
650 used to ``box'' up an external reference into a Haskell heap object
651 that we can then indirectly reference:
654 createImage :: (Int,Int) -> PrimIO Image
658 So far, this looks just like an @Addr#@ type, but @ForeignObj#@
659 offers a bit more, namely that we can specify a {\em finalisation
660 routine} to invoke when the @ForeignObj#@ is discarded by the
661 GC. The garbage collector invokes the finalisation routine associated
662 with the @ForeignObj#@, saying `` Thanks, I'm through with this
663 now..'' For the image-processing library, the finalisation routine could for
664 the images free up memory allocated for them. The finalisation routine has
665 currently to be written in C (the finalisation routine can in turn call on
666 @FreeStablePtr@ to deallocate a stable pointer).
668 Associating a finalisation routine with an external object is done by
672 makeForeignObj# :: Addr# -- foreign reference
673 -> Addr# -- pointer to finalisation routine
674 -> StateAndForeignObj# RealWorld ForeignObj#
677 \bf{Note:} the foreign object value and its finaliser are contained
678 in the primitive value @ForeignObj#@, so there's no danger of an
679 aggressive optimiser somehow separating the two. (with the result
680 that the foreign reference would not be freed).
682 (Implementation: a linked list of all @ForeignObj#@s is maintained to allow the
683 garbage collector to detect when a @ForeignObj#@ becomes garbage.)
685 Like @Array@, @ForeignObj#@s are represented by heap objects.
687 Upon controlled termination of the Haskell program, all @ForeignObjs@
688 are freed, invoking their respective finalisers before terminating.
690 %\bf{ToDo:} Decide whether @FreeCHeapPointer@ is allowed to call on a
691 %stable pointer. (I sincerely hope not since we will still be in the
694 \subsubsubsection{Synchronizing variables (M-vars)}
696 Synchronising variables are the primitive type used to implement
697 Concurrent Haskell's MVars (see the Concurrent Haskell paper for
698 the operational behaviour of these operations).
701 type SynchVar# s elt -- primitive
703 newSynchVar#:: State# s -> StateAndSynchVar# s elt
704 takeMVar# :: SynchVar# s elt -> State# s -> StateAndPtr# s elt
705 putMVar# :: SynchVar# s elt -> State# s -> State# s
708 %\subsubsubsection{Controlling the garbage collector}
710 %The C function {\tt PerformGC\/}, allows the C world to force Haskell
711 %to do a garbage collection. It can only be called while Haskell is
712 %performing a C Call.
714 %Note that this function can be used to define a Haskell IO operation
715 %with the same effect:
717 %> performGCIO :: PrimIO ()
718 %> performGCIO = _ccall_gc_ StgPerformGarbageCollection
721 %\bf{ToDo:} Is there any need for abnormal/normal termination to force
722 %a GC too? Is there any need for a function that provides finer
723 %control over GC: argument = amount of space required; result = amount
726 \subsection{@spark#@ primitive operation (for parallel execution)}
728 {\em ToDo: say something} It's used in the unfolding for @par@.
730 \subsection{The @errorIO#@ primitive operation}
732 The @errorIO#@ primitive takes an argument much like @PrimIO@. It
733 aborts execution of the current program, and continues instead by
734 performing the given @PrimIO@-like value on the current state of the
737 errorIO# :: (State RealWorld -> ((), State RealWorld)) -> a
743 \bf{ToDo:} current implementation has state variable as second
744 argument not last argument.
746 The @ccall#@ primitive can't be given an ordinary type, because it has
747 a variable number of arguments. The nearest we can get is:
749 ccall# :: CRoutine -> a1# -> ... -> an# -> State# RealWorld -> StateAndR# RealWorld
752 where the type variables @a1#@\ldots@an#@ and @r#@ can be instantiated by any
753 primitive type, and @StateAndR#@ is the appropriate pairing type from
754 Section~\ref{sect:horrid-pairing-types}. The @CRoutine@
755 isn't a proper Haskell type at all; it just reminds us that @ccall#@ needs to
756 know what C routine to call.
758 This notation is really short for a massive family of @ccall#@ primitives, one
759 for each combination of types. (Of course, the compiler simply remembers the
760 types involved, and generates appropriate code when it finally spits out the C.)
762 Unlike all the other primitive operators, @ccall#@ is not bound to an in-scope
763 identifier. The only way it is possible to generate a @ccall#@ is via the
766 All this applies equally to @casm#@:
768 casm# :: CAsmString -> a1# -> ... -> an# -> State# RealWorld -> StateAndR# RealWorld
771 %------------------------------------------------------------
772 \subsection{Library stuff built with the Really Primitive Stuff}
774 \subsubsection{The state transformer monad}
776 \subsubsubsection{Types}
778 A state transformer is a function from a state to a pair of a result
781 newtype ST s a = ST (State s -> (a, State s))
784 The @ST@ type is {\em abstract}, so that the programmer cannot see its
785 representation. If he could, he could write bad things like:
788 bad = ST $ \ s -> ...(f s)...(g s)...
791 Here, @s@ is duplicated, which would be bad news.
793 A state is represented by a primitive state value, of type @State# s@,
794 wrapped up in a @State@ constructor. The reason for boxing it in this
795 way is so that we can be strict or lazy in the state. (Remember, all
796 primitive types are unboxed, and hence can't be bottom; but types built
797 with @data@ are all boxed.)
799 data State s = S# (State# s)
802 \subsubsubsection{The state transformer combinators}
804 Now for the combinators, all of which live inside the @ST@
805 abstraction. Notice that @returnST@ and @thenST@ are now strict
806 in the state. @ST@ is an instance of the @Monad@ type class.
808 returnST :: a -> ST s a
809 returnST a = ST (\ s@(S# _) -> (a, s)) -- strict in state.
811 thenST :: ST s a -> (a -> ST s b) -> ST s b
814 case (m s) of {(r, new_s) ->
815 case (k r) of { ST k2 ->
818 instance Monad ST where
822 fixST :: (a -> ST s a) -> ST s a
823 fixST k s = ST $ \ s ->
830 unsafeInterleaveST :: ST s a -> ST s a
831 unsafeInterleaveST (ST m) = ST $ \ s ->
838 The interesting one is, of course, @runST@. We can't infer its type!
839 (It has a funny name because it must be wired into the compiler.)
841 -- runST :: forall a. (forall s. ST s a) -> a
842 runST m = case m (S# realWorld#) of
847 \subsubsubsection{Other useful combinators}
849 There are various other standard combinators, all defined in terms the
850 fundamental combinators above. The @seqST@ combinator is like
851 @thenST@, except that it discards the result of the first state
854 seqST :: ST s a -> ST s b -> ST s b
855 seqST m1 m2 = m1 `thenST` (\_ -> m2)
858 We also have {\em lazy} (... in the state...) variants of the
859 then/return combinators (same types as their pals):
861 returnLazyST a = ST (\ s -> (a, s))
876 The combinator @listST@ is provided for backwards compatibility, its
877 behavior is captured in Haskell 1.3 (and later) by @Monad.accumulate@:
879 listST :: [ST s a] -> ST s [a]
880 listST ls = accumulate ls
883 Another function provided for backwards compatibility is @mapST@, it
884 is just an instance of the more general monad combinator @Monad.mapM@:
886 mapST :: (a -> ST s b) -> [a] -> ST s [b]
887 mapST f ms = mapM f ms
890 The @mapAndUnzipST@ combinator is similar to @mapST@, except that here the
891 function returns a pair:
893 mapAndUnzipST :: (a -> ST s (b,c)) -> [a] -> ST s ([b],[c])
894 mapAndUnzipST f ls = mapAndUnzipM f ls
898 \bf{Note:} all the derived operators over @ST@ are implemented using
899 the {\em strict} @ST@ instance of @Monad@.
901 \subsubsection{The @PrimIO@ monad}
904 The @PrimIO@ type is defined in as a state transformer which manipulates the
907 type PrimIO a = ST RealWorld a -- Transparent
910 The @PrimIO@ type is an ordinary type synonym, transparent to the programmer.
912 The type @RealWorld@ and value @realWorld#@ do not need to be hidden (although
913 there is no particular point in exposing them). Even having a value of type
914 @realWorld#@ does not compromise safety, since the type @ST@ is hidden.
916 It is type-correct to use @returnST@ in an @PrimIO@ context, they're
917 in effect the same (ditto for the bind combinator):
920 returnPrimIO :: a -> PrimIO a
921 returnPrimIO v = returnST v
923 thenPrimIO :: PrimIO a -> (a -> PrimIO b) -> PrimIO b
924 thenPrimIO m k = thenST m k
926 seqPrimIO :: PrimIO a -> PrimIO b -> PrimIO b
927 seqPrimIO m k = seqST m k
930 Why is it safe for @returnPrimIO@ to be strict in the state? Because
931 every context in which an I/O state transformer is used will certainly
932 evaluate the resulting state; it is the state of the real world!
934 @fixPrimIO@ has to be lazy, though!
939 \subsubsubsection{@PrimIO@ combinators}
944 unsafePerformPrimIO :: PrimIO a -> a
945 unsafeInterleavePrimIO :: PrimIO a -> PrimIO a
947 unsafePerformPrimIO = runST
948 unsafeInterleavePrimIO = unsafeInterleaveST
950 listPrimIO :: [PrimIO a] -> PrimIO [a]
951 mapPrimIO :: (a -> PrimIO b) -> [a] -> PrimIO [b]
952 mapAndUnzipPrimIO :: (a -> PrimIO (b,c)) -> [a] -> PrimIO ([b],[c])
955 The function @unsafePerformPrimIO@ is as the name suggests, {\em
956 unsafe}, placing a burden of proof on the programmer to ensure that
957 performing the I/O action does not break referential transparency.
959 \subsubsection{Arrays}
961 \subsubsubsection{Types}
964 data Array ix elt = Array (ix,ix) (Array# elt)
965 data ByteArray ix = ByteArray (ix,ix) ByteArray#
967 data MutableArray s ix elt = MutableArray (ix,ix) (MutableArray# s elt)
968 data MutableByteArray s ix = MutableByteArray (ix,ix) (MutableByteArray# s)
972 \subsubsubsection{Operations on immutable arrays}
974 Ordinary array indexing is straightforward.
976 (!) :: Ix ix => Array ix elt -> ix -> elt
979 QUESTIONs: should @ByteArray@s be indexed by Ints or ix? With byte offsets
980 or sized ones? (sized ones [WDP])
982 indexCharArray :: Ix ix => ByteArray ix -> ix -> Char
983 indexIntArray :: Ix ix => ByteArray ix -> ix -> Int
984 indexAddrArray :: Ix ix => ByteArray ix -> ix -> Addr
985 indexFloatArray :: Ix ix => ByteArray ix -> ix -> Float
986 indexDoubleArray :: Ix ix => ByteArray ix -> ix -> Double
989 @Addr@s are indexed straightforwardly by @Int@s. Unlike the primitive
990 operations, though, the offsets assume that the array consists entirely of the
991 type of value being indexed, and so there's an implicit multiplication by
992 the size of that value. To access @Addr@s with mixed values requires
993 you to do a DIY job using the primitives.
995 indexAddrChar :: Addr -> Int -> Char
997 indexStaticCharArray :: Addr -> Int -> Char
998 indexStaticIntArray :: Addr -> Int -> Int
999 indexStaticFloatArray :: Addr -> Int -> Float
1000 indexStaticDoubleArray :: Addr -> Int -> Double
1001 indexStaticArray :: Addr -> Int -> Addr
1005 \subsubsubsection{Operations on mutable arrays}
1007 newArray :: Ix ix => (ix,ix) -> elt -> ST s (MutableArray s ix elt)
1008 newCharArray :: Ix ix => (ix,ix) -> ST s (MutableByteArray s ix)
1014 readArray :: Ix ix => MutableArray s ix elt -> ix -> ST s elt
1015 readCharArray :: Ix ix => MutableByteArray s ix -> ix -> ST s Char
1020 writeArray :: Ix ix => MutableArray s ix elt -> ix -> elt -> ST s ()
1021 writeCharArray :: Ix ix => MutableByteArray s ix -> ix -> Char -> ST s ()
1027 freezeArray :: Ix ix => MutableArray s ix elt -> ST s (Array ix elt)
1028 freezeCharArray :: Ix ix => MutableByteArray s ix -> ST s (ByteArray ix)
1033 We have no need on one-function-per-type for unsafe freezing:
1035 unsafeFreezeArray :: Ix ix => MutableArray s ix elt -> ST s (Array ix elt)
1036 unsafeFreezeByteArray :: Ix ix => MutableByteArray s ix -> ST s (ByteArray ix)
1040 Sometimes we want to snaffle the bounds of one of these beasts:
1042 boundsOfArray :: Ix ix => MutableArray s ix elt -> (ix, ix)
1043 boundsOfByteArray :: Ix ix => MutableByteArray s ix -> (ix, ix)
1047 Lastly, ``equality'':
1049 sameMutableArray :: MutableArray s ix elt -> MutableArray s ix elt -> Bool
1050 sameMutableByteArray :: MutableByteArray s ix -> MutableByteArray s ix -> Bool
1054 \subsubsection{Mutable Variables}
1056 \subsubsubsection{Types}
1058 Mutable variables are (for now anyway) implemented as arrays. The
1059 @MutableVar@ type is opaque, so we can change the implementation later
1063 type MutableVar s a = MutableArray s Int a
1067 \subsubsubsection{Operations}
1069 newVar :: a -> ST s (MutableVar s a)
1070 readVar :: MutableVar s a -> ST s a
1071 writeVar :: MutableVar s a -> a -> ST s ()
1072 sameVar :: MutableVar s a -> MutableVar s a -> Bool
1076 \subsubsection{Stable pointers}
1078 Nothing exciting here, just simple boxing up.
1080 data StablePtr a = StablePtr (StablePtr# a)
1082 makeStablePointer :: a -> StablePtr a
1083 freeStablePointer :: StablePtr a -> PrimIO ()
1086 \subsubsection{Foreign objects}
1088 Again, just boxing up.
1090 data ForeignObj = ForeignObj ForeignObj#
1092 makeForeignObj :: Addr -- object to be boxed up as a ForeignObj
1093 -> Addr -- finaliser
1094 -> PrimIO ForeignObj
1097 \subsubsection{C calls}
1099 Everything in this section goes for @_casm_@ too.
1101 \bf{ToDo:} {\em mention @_ccall_gc_@ and @_casm_gc_@...}
1103 The @_ccall_@ construct has the following form:
1104 $$@_ccall_@~croutine~a_1~\ldots~a_n$$
1105 This whole construct has type @PrimIO@~$res$.
1106 The rules are these:
1109 The first ``argument'', $croutine$, must be the literal name of a C procedure.
1110 It cannot be a Haskell expression which evaluates to a string, etc; it must be
1111 simply the name of the procedure.
1113 The arguments $a_1, \ldots,a_n$ must be of {\em C-callable} type.
1115 The whole construct has type @PrimIO@~$ty$, where $ty$ is a {\em C-returnable} type.
1117 A {\em boxed-primitive} type is both C-callable and C-returnable.
1118 A boxed primitive type is anything declared by:
1123 where @t@ is a primitive type. Note that
1124 programmer-defined boxed-primitive types are perfectly OK:
1126 data Widget = W# Int#
1127 data Screen = S# CHeapPtr#
1131 There are other types that can be passed to C (C-callable). This
1132 table summarises (including the standard boxed-primitive types):
1134 Boxed Type of transferd Corresp. Which is
1135 Type Prim. component C type *probably*...
1136 ------ --------------- ------ -------------
1137 Char Char# StgChar unsigned char
1138 Int Int# StgInt long int
1139 Word Word# StgWord unsigned long int
1140 Addr Addr# StgAddr char *
1141 Float Float# StgFloat float
1142 Double Double# StgDouble double
1144 Array Array# StgArray StgPtr
1145 ByteArray ByteArray# StgByteArray StgPtr
1146 MutableArray MutableArray# StgArray StgPtr
1147 MutableByteArray MutableByteArray# StgByteArray StgPtr
1149 State State# nothing!
1151 StablePtr StablePtr# StgStablePtr StgPtr
1152 ForeignObj ForeignObj# StgForeignObj StgPtr
1156 All of the above are {\em C-returnable} except:
1158 Array, ByteArray, MutableArray, MutableByteArray, ForeignObj
1161 \bf{ToDo:} I'm pretty wary of @Array@ and @MutableArray@ being in
1162 this list, and not too happy about @State@ [WDP].
1164 \bf{ToDo:} Can code generator pass all the primitive types? Should this be
1165 extended to include {\tt Bool\/} (or any enumeration type?)
1167 The type checker must be able to figure out just which of the C-callable/returnable
1168 types is being used. If it can't, you have to add type signatures. For example,
1173 is not good enough, because the compiler can't work out what type @x@ is, nor
1174 what type the @_ccall_@ returns. You have to write, say:
1176 f :: Int -> PrimIO Float
1181 \subsubsubsection{Implementation}
1183 The desugarer unwraps the @_ccall_@ construct by inserting the
1184 necessary evaluations etc to unbox the arguments. For example, the
1185 body of the definition of @f@ above would become:
1187 (\ s -> case x of { I# x# ->
1188 case s of { S# s# ->
1189 case ccall# [Int#,Float#] x# s# of { StateAndFloat# f# new_s# ->
1194 Notice that the state, too, is unboxed.
1196 %The code generator must deal specially with primitive objects which
1197 %are stored on the heap.
1200 %... details omitted ...
1204 %More importantly, it must construct a C Heap Pointer heap-object after
1205 %a @_ccall_@ which returns a @MallocPtr#@.
1208 %--------------------------------------------------------
1209 \subsection{Non-primitive stuff that must be wired into GHC}
1212 data Char = C# Char#
1214 data Word = W# Word#
1215 data Addr = A# Addr#
1217 data Float = F# Float#
1218 data Double = D# Double#
1219 data Integer = J# Int# Int# ByteArray#
1221 -- and the other boxed-primitive types:
1222 Array, ByteArray, MutableArray, MutableByteArray,
1223 StablePtr, ForeignObj
1225 data Bool = False | True
1226 data Ordering = LT | EQ | GT -- used in derived comparisons
1228 data List a = [] | a : (List a)
1231 data Lift a = Lift a -- used Yukkily as described elsewhere
1233 type String = [Char] -- convenience, only
1237 %------------------------------------------------------------
1238 \subsection{Programmer interface(s)}
1240 \subsubsection{The bog-standard interface}
1242 If you rely on the implicit @import Prelude@ that GHC normally does
1243 for you, and if you don't use any weird flags (notably
1244 @-fglasgow-exts@), and if you don't import the Glasgow extensions
1245 interface, @GlaExts@, then GHC should work {\em exactly} as the
1246 Haskell report says, and the full user namespaces should be available
1249 \subsubsubsection{If you mess about with @import Prelude@...}
1251 Innocent hiding, e.g.,
1253 import Prelude hiding ( fromIntegral )
1256 should work just fine.
1258 There are some things you can do that will make GHC crash, e.g.,
1259 hiding a standard class:
1261 import Prelude hiding ( Eq(..) )
1266 \subsubsection{Turning on Glasgow extensions with @-fglasgow-exts@}
1268 % Updated to tell the 2.02+ story -- SOF
1270 If you turn on @-fglasgow-exts@, the compiler will recognise and parse
1271 unboxed values properly. To get at the primitive operations described
1272 herein, import the interface @GlaExts@.
1274 % 1.3+ module system makes this a non-issue.
1275 %%It is possible that some name conflicts between your code and the
1276 %%wired-in things might spring to life (though we doubt it...).
1277 %%Change your names :-)
1279 %************************************************************************
1281 \subsubsection{The @GlaExts@ interface}
1282 \index{GlaExts interface (GHC extensions)}
1284 %************************************************************************
1286 The @GlaExts@ interface is the programmer gateway to most of the
1287 programmer extensions GHC implement. Currently on tap:
1290 -- PrimIO monad (state transformer, no exceptions).
1291 type PrimIO a = ST RealWorld a
1292 -- instances of: Monad
1293 data RealWorld -- abstract State value
1295 thenPrimIO :: PrimIO a -> (a -> PrimIO b) -> PrimIO b
1296 returnPrimIO :: a -> PrimIO a
1297 seqPrimIO :: PrimIO a -> PrimIO b -> PrimIO b
1299 fixPrimIO :: (a -> PrimIO a) -> PrimIO a
1300 unsafePerformPrimIO :: PrimIO a -> a
1301 unsafeInterleavePrimIO :: PrimIO a -> PrimIO a
1303 -- backwards compatibility
1304 listPrimIO :: [PrimIO a] -> PrimIO [a]
1305 mapPrimIO :: (a -> PrimIO b) -> [a] -> PrimIO [b]
1306 mapAndUnzipPrimIO :: (a -> PrimIO (b,c)) -> [a] -> PrimIO ([b],[c])
1308 -- Combining ST and PrimIO monads with IO
1309 stToIO, -- :: ST RealWorld a -> IO a
1310 primIOToIO, -- :: PrimIO a -> IO a
1311 ioToST, -- :: IO a -> ST RealWorld a
1312 ioToPrimIO, -- :: IO a -> PrimIO a
1313 thenIO_Prim, -- :: PrimIO a -> (a -> IO b) -> IO b
1314 seqIO_Prim, -- :: PrimIO a -> IO b -> IO b
1316 -- the representation of some basic types:
1317 data Char = C# Char#
1319 data Addr = A# Addr#
1320 data Word = W# Word#
1321 data Float = F# Float#
1322 data Double = D# Double#
1323 data Integer = J# Int# Int# ByteArray#
1326 trace :: String -> a -> a
1328 -- re-exported interfaces:
1331 module GHC -- all primops and primitive types.
1335 %************************************************************************
1337 \subsubsection{The @MutVar@ interface}
1338 \index{MutVar interface (GHC extensions)}
1340 %************************************************************************
1342 @MutVar@ defines an interface to mutable variables, defining type and
1346 data MutVar -- abstract
1348 newVar :: a -> IO (MutVar a)
1349 readVar :: MutVar a -> IO a
1350 writeVar :: MutVar a -> a -> IO ()
1351 sameVar :: MutVar a -> MutVar a -> Bool
1355 %************************************************************************
1357 \subsubsection{The @MutableArray@ interface}
1358 \index{MutableArray interface (GHC extensions)}
1360 %************************************************************************
1362 The @MutableArray@ interface defines a general set of operations over
1363 mutable arrays (@MutableArray@) and mutable chunks of memory
1364 (@MutableByteArray@):
1367 data MutableArray s ix elt -- abstract
1368 data MutableByteArray s ix -- abstract
1369 -- instance of : CCallable
1371 newArray :: Ix ix => (ix,ix) -> elt -> ST s (MutableArray s ix elt)
1372 newCharArray :: Ix ix => (ix,ix) -> ST s (MutableByteArray s ix)
1373 newAddrArray :: Ix ix => (ix,ix) -> ST s (MutableByteArray s ix)
1374 newIntArray :: Ix ix => (ix,ix) -> ST s (MutableByteArray s ix)
1375 newFloatArray :: Ix ix => (ix,ix) -> ST s (MutableByteArray s ix)
1376 newDoubleArray :: Ix ix => (ix,ix) -> ST s (MutableByteArray s ix)
1378 boundsOfArray :: Ix ix => MutableArray s ix elt -> (ix, ix)
1379 boundsOfByteArray :: Ix ix => MutableByteArray s ix -> (ix, ix)
1382 readArray :: Ix ix => MutableArray s ix elt -> ix -> ST s elt
1384 readCharArray :: Ix ix => MutableByteArray s ix -> ix -> ST s Char
1385 readIntArray :: Ix ix => MutableByteArray s ix -> ix -> ST s Int
1386 readAddrArray :: Ix ix => MutableByteArray s ix -> ix -> ST s Addr
1387 readFloatArray :: Ix ix => MutableByteArray s ix -> ix -> ST s Float
1388 readDoubleArray :: Ix ix => MutableByteArray s ix -> ix -> ST s Double
1390 writeArray :: Ix ix => MutableArray s ix elt -> ix -> elt -> ST s ()
1391 writeCharArray :: Ix ix => MutableByteArray s ix -> ix -> Char -> ST s ()
1392 writeIntArray :: Ix ix => MutableByteArray s ix -> ix -> Int -> ST s ()
1393 writeAddrArray :: Ix ix => MutableByteArray s ix -> ix -> Addr -> ST s ()
1394 writeFloatArray :: Ix ix => MutableByteArray s ix -> ix -> Float -> ST s ()
1395 writeDoubleArray :: Ix ix => MutableByteArray s ix -> ix -> Double -> ST s ()
1397 freezeArray :: Ix ix => MutableArray s ix elt -> ST s (Array ix elt)
1398 freezeCharArray :: Ix ix => MutableByteArray s ix -> ST s (ByteArray ix)
1399 freezeIntArray :: Ix ix => MutableByteArray s ix -> ST s (ByteArray ix)
1400 freezeAddrArray :: Ix ix => MutableByteArray s ix -> ST s (ByteArray ix)
1401 freezeFloatArray :: Ix ix => MutableByteArray s ix -> ST s (ByteArray ix)
1402 freezeDoubleArray :: Ix ix => MutableByteArray s ix -> ST s (ByteArray ix)
1404 unsafeFreezeArray :: Ix ix => MutableArray s ix elt -> ST s (Array ix elt)
1405 unsafeFreezeByteArray :: Ix ix => MutableByteArray s ix -> ST s (ByteArray ix)
1406 thawArray :: Ix ix => Array ix elt -> ST s (MutableArray s ix elt)
1410 %************************************************************************
1412 \subsubsection{The @ByteArray@ interface}
1413 \index{ByteArray interface (GHC extensions)}
1415 %************************************************************************
1417 @ByteArray@s are chunks of immutable Haskell heap:
1420 data ByteArray ix -- abstract
1421 -- instance of: CCallable
1423 indexCharArray :: Ix ix => ByteArray ix -> ix -> Char
1424 indexIntArray :: Ix ix => ByteArray ix -> ix -> Int
1425 indexAddrArray :: Ix ix => ByteArray ix -> ix -> Addr
1426 indexFloatArray :: Ix ix => ByteArray ix -> ix -> Float
1427 indexDoubleArray :: Ix ix => ByteArray ix -> ix -> Double
1429 indexCharOffAddr :: Addr -> Int -> Char
1430 indexIntOffAddr :: Addr -> Int -> Int
1431 indexAddrOffAddr :: Addr -> Int -> Addr
1432 indexFloatOffAddr :: Addr -> Int -> Float
1433 indexDoubleOffAddr :: Addr -> Int -> Double
1437 %************************************************************************
1439 \subsubsection{The @Foreign@ interface}
1440 \index{Foreign interface (GHC extensions)}
1442 %************************************************************************
1444 The @Foreign@ interface define and export operations over @ForeignObj@
1448 -- semi-magic classes for pack/unpacking ccall arguments.
1450 {- Instances defined for :
1451 Char Char# Int Int# Float Float#
1452 Double Double# Addr Addr# Word Word#
1453 (MutableByteArray s ix) (MutableByteArray# s)
1454 (ByteArray ix) ByteArray#
1455 ForeignObj ForeignObj#
1461 {- Instances defined for :
1462 Char Int Float Double Addr Word
1466 data ForeignObj = ForeignObj ForeignObj#
1467 -- instances of : CCallable Eq
1469 eqForeignObj :: ForeignObj -> ForeignObj -> Bool
1470 makeForeignObj :: Addr -> Addr -> PrimIO ForeignObj
1471 writeForeignObj :: ForeignObj -> Addr -> PrimIO ()
1473 {- derived op - attaching a free() finaliser to a malloc() allocated reference. -}
1474 makeMallocPtr :: Addr -> PrimIO ForeignObj
1476 data StablePtr a = StablePtr (StablePtr# a)
1477 -- instances of : CCallable
1479 makeStablePtr :: a -> PrimIO (StablePtr a)
1480 deRefStablePtr :: StablePtr a -> PrimIO a
1481 freeStablePtr :: StablePtr a -> PrimIO ()
1482 performGC :: PrimIO ()
1485 \begin{onlystandalone}
1487 \end{onlystandalone}