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[ghc-libs-ghc]{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.}
618 % Rewritten and updated for MallocPtr++ -- 4/96 SOF
620 \subsubsubsection{Foreign objects}
622 A @ForeignObj@ is a reference to an object outside the Haskell world
623 (i.e., from the C world, or a reference to an object on another
624 machine completely.), where the Haskell world has been told ``Let me
625 know when you're finished with this ...''.
627 %OLD:The @ForeignObj@ type is just a special @Addr#@ ({\em not} parameterised).
632 A typical use of @ForeignObj#@ is in constructing Haskell bindings
633 to external libraries. A good example is that of writing a binding to
634 an image-processing library (which was actually the main motivation
635 for implementing @ForeignObj#@'s precursor, @MallocPtr#@). The
636 images manipulated are not stored in the Haskell heap, either because
637 the library insist on allocating them internally or we (sensibly)
638 decide to spare the GC from having to heave heavy images around.
641 data Image = Image ForeignObj#
643 instance CCallable Image
646 The @ForeignObj#@ type is then used to refer to the externally
647 allocated image, and to acheive some type safety, the Haskell binding
648 defines the @Image@ data type. So, a value of type @ForeignObj#@ is
649 used to ``box'' up an external reference into a Haskell heap object
650 that we can then indirectly reference:
653 createImage :: (Int,Int) -> PrimIO Image
657 So far, this looks just like an @Addr#@ type, but @ForeignObj#@
658 offers a bit more, namely that we can specify a {\em finalisation
659 routine} to invoke when the @ForeignObj#@ is discarded by the
660 GC. The garbage collector invokes the finalisation routine associated
661 with the @ForeignObj#@, saying `` Thanks, I'm through with this
662 now..'' For the image-processing library, the finalisation routine could for
663 the images free up memory allocated for them. The finalisation routine has
664 currently to be written in C (the finalisation routine can in turn call on
665 @FreeStablePtr@ to deallocate a stable pointer).
667 Associating a finalisation routine with an external object is done by
671 makeForeignObj# :: Addr# -- foreign reference
672 -> Addr# -- pointer to finalisation routine
673 -> StateAndForeignObj# RealWorld ForeignObj#
676 {\bf Note:} the foreign object value and its finaliser are contained
677 in the primitive value @ForeignObj#@, so there's no danger of an
678 aggressive optimiser somehow separating the two. (with the result
679 that the foreign reference would not be freed).
681 (Implementation: a linked list of all @ForeignObj#@s is maintained to allow the
682 garbage collector to detect when a @ForeignObj#@ becomes garbage.)
684 Like @Array@, @ForeignObj#@s are represented by heap objects.
686 Upon controlled termination of the Haskell program, all @ForeignObjs@
687 are freed, invoking their respective finalisers before terminating.
689 %\bf{ToDo:} Decide whether @FreeCHeapPointer@ is allowed to call on a
690 %stable pointer. (I sincerely hope not since we will still be in the
693 \subsubsubsection{Synchronizing variables (M-vars)}
695 Synchronising variables are the primitive type used to implement
696 Concurrent Haskell's MVars (see the Concurrent Haskell paper for
697 the operational behaviour of these operations).
700 type SynchVar# s elt -- primitive
702 newSynchVar#:: State# s -> StateAndSynchVar# s elt
703 takeMVar# :: SynchVar# s elt -> State# s -> StateAndPtr# s elt
704 putMVar# :: SynchVar# s elt -> State# s -> State# s
707 %\subsubsubsection{Controlling the garbage collector}
709 %The C function {\tt PerformGC\/}, allows the C world to force Haskell
710 %to do a garbage collection. It can only be called while Haskell is
711 %performing a C Call.
713 %Note that this function can be used to define a Haskell IO operation
714 %with the same effect:
716 %> performGCIO :: PrimIO ()
717 %> performGCIO = _ccall_gc_ StgPerformGarbageCollection
720 %\bf{ToDo:} Is there any need for abnormal/normal termination to force
721 %a GC too? Is there any need for a function that provides finer
722 %control over GC: argument = amount of space required; result = amount
725 The C function {\tt PerformGC\/}, allows the C world to force Haskell
726 to do a garbage collection. It can only be called while Haskell is
729 Note that this function can be used to define a Haskell IO operation
730 with the same effect:
732 > performGCIO :: PrimIO ()
733 > performGCIO = _ccall_gc_ PerformGC
736 {\bf ToDo:} Is there any need for abnormal/normal termination to force
737 a GC too? Is there any need for a function that provides finer
738 control over GC: argument = amount of space required; result = amount
741 \subsection{@spark#@ primitive operation (for parallel execution)}
743 {\em ToDo: say something} It's used in the unfolding for @par@.
745 \subsection{The @errorIO#@ primitive operation}
747 The @errorIO#@ primitive takes an argument much like @PrimIO@. It
748 aborts execution of the current program, and continues instead by
749 performing the given @PrimIO@-like value on the current state of the
752 errorIO# :: (State RealWorld -> ((), State RealWorld)) -> a
758 {\bf ToDo:} current implementation has state variable as second
759 argument not last argument.
761 The @ccall#@ primitive can't be given an ordinary type, because it has
762 a variable number of arguments. The nearest we can get is:
764 ccall# :: CRoutine -> a1# -> ... -> an# -> State# RealWorld -> StateAndR# RealWorld
767 where the type variables @a1#@\ldots@an#@ and @r#@ can be instantiated by any
768 primitive type, and @StateAndR#@ is the appropriate pairing type from
769 Section~\ref{sect:horrid-pairing-types}. The @CRoutine@
770 isn't a proper Haskell type at all; it just reminds us that @ccall#@ needs to
771 know what C routine to call.
773 This notation is really short for a massive family of @ccall#@ primitives, one
774 for each combination of types. (Of course, the compiler simply remembers the
775 types involved, and generates appropriate code when it finally spits out the C.)
777 Unlike all the other primitive operators, @ccall#@ is not bound to an in-scope
778 identifier. The only way it is possible to generate a @ccall#@ is via the
781 All this applies equally to @casm#@:
783 casm# :: CAsmString -> a1# -> ... -> an# -> State# RealWorld -> StateAndR# RealWorld
786 %------------------------------------------------------------
787 \subsection{Library stuff built with the Really Primitive Stuff}
789 \subsubsection{The state transformer monad}
791 \subsubsubsection{Types}
793 A state transformer is a function from a state to a pair of a result
796 newtype ST s a = ST (State s -> (a, State s))
799 The @ST@ type is {\em abstract}, so that the programmer cannot see its
800 representation. If he could, he could write bad things like:
803 bad = ST $ \ s -> ...(f s)...(g s)...
806 Here, @s@ is duplicated, which would be bad news.
808 A state is represented by a primitive state value, of type @State# s@,
809 wrapped up in a @State@ constructor. The reason for boxing it in this
810 way is so that we can be strict or lazy in the state. (Remember, all
811 primitive types are unboxed, and hence can't be bottom; but types built
812 with @data@ are all boxed.)
814 data State s = S# (State# s)
817 \subsubsubsection{The state transformer combinators}
819 Now for the combinators, all of which live inside the @ST@
820 abstraction. Notice that @returnST@ and @thenST@ are now strict
821 in the state. @ST@ is an instance of the @Monad@ type class.
823 returnST :: a -> ST s a
824 returnST a = ST (\ s@(S# _) -> (a, s)) -- strict in state.
826 thenST :: ST s a -> (a -> ST s b) -> ST s b
829 case (m s) of {(r, new_s) ->
830 case (k r) of { ST k2 ->
833 instance Monad ST where
837 fixST :: (a -> ST s a) -> ST s a
838 fixST k s = ST $ \ s ->
845 unsafeInterleaveST :: ST s a -> ST s a
846 unsafeInterleaveST (ST m) = ST $ \ s ->
853 The interesting one is, of course, @runST@. We can't infer its type!
854 (It has a funny name because it must be wired into the compiler.)
856 -- runST :: forall a. (forall s. ST s a) -> a
857 runST m = case m (S# realWorld#) of
862 \subsubsubsection{Other useful combinators}
864 There are various other standard combinators, all defined in terms the
865 fundamental combinators above. The @seqST@ combinator is like
866 @thenST@, except that it discards the result of the first state
869 seqST :: ST s a -> ST s b -> ST s b
870 seqST m1 m2 = m1 `thenST` (\_ -> m2)
873 We also have {\em lazy} (... in the state...) variants of the
874 then/return combinators (same types as their pals):
876 returnLazyST a = ST (\ s -> (a, s))
891 The combinator @listST@ is provided for backwards compatibility, its
892 behavior is captured in Haskell 1.3 (and later) by @Monad.accumulate@:
894 listST :: [ST s a] -> ST s [a]
895 listST ls = accumulate ls
898 Another function provided for backwards compatibility is @mapST@, it
899 is just an instance of the more general monad combinator @Monad.mapM@:
901 mapST :: (a -> ST s b) -> [a] -> ST s [b]
902 mapST f ms = mapM f ms
905 The @mapAndUnzipST@ combinator is similar to @mapST@, except that here the
906 function returns a pair:
908 mapAndUnzipST :: (a -> ST s (b,c)) -> [a] -> ST s ([b],[c])
909 mapAndUnzipST f ls = mapAndUnzipM f ls
913 {\bf Note:} all the derived operators over @ST@ are implemented using
914 the {\em strict} @ST@ instance of @Monad@.
916 \subsubsection{The @PrimIO@ monad}
919 The @PrimIO@ type is defined in as a state transformer which manipulates the
922 type PrimIO a = ST RealWorld a -- Transparent
925 The @PrimIO@ type is an ordinary type synonym, transparent to the programmer.
927 The type @RealWorld@ and value @realWorld#@ do not need to be hidden (although
928 there is no particular point in exposing them). Even having a value of type
929 @realWorld#@ does not compromise safety, since the type @ST@ is hidden.
931 It is type-correct to use @returnST@ in an @PrimIO@ context, they're
932 in effect the same (ditto for the bind combinator):
935 returnPrimIO :: a -> PrimIO a
936 returnPrimIO v = returnST v
938 thenPrimIO :: PrimIO a -> (a -> PrimIO b) -> PrimIO b
939 thenPrimIO m k = thenST m k
941 seqPrimIO :: PrimIO a -> PrimIO b -> PrimIO b
942 seqPrimIO m k = seqST m k
945 Why is it safe for @returnPrimIO@ to be strict in the state? Because
946 every context in which an I/O state transformer is used will certainly
947 evaluate the resulting state; it is the state of the real world!
949 @fixPrimIO@ has to be lazy, though!
954 \subsubsubsection{@PrimIO@ combinators}
959 unsafePerformPrimIO :: PrimIO a -> a
960 unsafeInterleavePrimIO :: PrimIO a -> PrimIO a
962 unsafePerformPrimIO = runST
963 unsafeInterleavePrimIO = unsafeInterleaveST
965 listPrimIO :: [PrimIO a] -> PrimIO [a]
966 mapPrimIO :: (a -> PrimIO b) -> [a] -> PrimIO [b]
967 mapAndUnzipPrimIO :: (a -> PrimIO (b,c)) -> [a] -> PrimIO ([b],[c])
970 The function @unsafePerformPrimIO@ is as the name suggests, {\em
971 unsafe}, placing a burden of proof on the programmer to ensure that
972 performing the I/O action does not break referential transparency.
974 \subsubsection{Arrays}
976 \subsubsubsection{Types}
979 data Array ix elt = Array (ix,ix) (Array# elt)
980 data ByteArray ix = ByteArray (ix,ix) ByteArray#
982 data MutableArray s ix elt = MutableArray (ix,ix) (MutableArray# s elt)
983 data MutableByteArray s ix = MutableByteArray (ix,ix) (MutableByteArray# s)
987 \subsubsubsection{Operations on immutable arrays}
989 Ordinary array indexing is straightforward.
991 (!) :: Ix ix => Array ix elt -> ix -> elt
994 QUESTIONs: should @ByteArray@s be indexed by Ints or ix? With byte offsets
995 or sized ones? (sized ones [WDP])
997 indexCharArray :: Ix ix => ByteArray ix -> ix -> Char
998 indexIntArray :: Ix ix => ByteArray ix -> ix -> Int
999 indexAddrArray :: Ix ix => ByteArray ix -> ix -> Addr
1000 indexFloatArray :: Ix ix => ByteArray ix -> ix -> Float
1001 indexDoubleArray :: Ix ix => ByteArray ix -> ix -> Double
1004 @Addr@s are indexed straightforwardly by @Int@s. Unlike the primitive
1005 operations, though, the offsets assume that the array consists entirely of the
1006 type of value being indexed, and so there's an implicit multiplication by
1007 the size of that value. To access @Addr@s with mixed values requires
1008 you to do a DIY job using the primitives.
1010 indexAddrChar :: Addr -> Int -> Char
1012 indexStaticCharArray :: Addr -> Int -> Char
1013 indexStaticIntArray :: Addr -> Int -> Int
1014 indexStaticFloatArray :: Addr -> Int -> Float
1015 indexStaticDoubleArray :: Addr -> Int -> Double
1016 indexStaticArray :: Addr -> Int -> Addr
1020 \subsubsubsection{Operations on mutable arrays}
1022 newArray :: Ix ix => (ix,ix) -> elt -> ST s (MutableArray s ix elt)
1023 newCharArray :: Ix ix => (ix,ix) -> ST s (MutableByteArray s ix)
1029 readArray :: Ix ix => MutableArray s ix elt -> ix -> ST s elt
1030 readCharArray :: Ix ix => MutableByteArray s ix -> ix -> ST s Char
1035 writeArray :: Ix ix => MutableArray s ix elt -> ix -> elt -> ST s ()
1036 writeCharArray :: Ix ix => MutableByteArray s ix -> ix -> Char -> ST s ()
1042 freezeArray :: Ix ix => MutableArray s ix elt -> ST s (Array ix elt)
1043 freezeCharArray :: Ix ix => MutableByteArray s ix -> ST s (ByteArray ix)
1048 We have no need on one-function-per-type for unsafe freezing:
1050 unsafeFreezeArray :: Ix ix => MutableArray s ix elt -> ST s (Array ix elt)
1051 unsafeFreezeByteArray :: Ix ix => MutableByteArray s ix -> ST s (ByteArray ix)
1055 Sometimes we want to snaffle the bounds of one of these beasts:
1057 boundsOfArray :: Ix ix => MutableArray s ix elt -> (ix, ix)
1058 boundsOfByteArray :: Ix ix => MutableByteArray s ix -> (ix, ix)
1062 Lastly, ``equality'':
1064 sameMutableArray :: MutableArray s ix elt -> MutableArray s ix elt -> Bool
1065 sameMutableByteArray :: MutableByteArray s ix -> MutableByteArray s ix -> Bool
1069 \subsubsection{Mutable Variables}
1071 \subsubsubsection{Types}
1073 Mutable variables are (for now anyway) implemented as arrays. The
1074 @MutableVar@ type is opaque, so we can change the implementation later
1078 type MutableVar s a = MutableArray s Int a
1082 \subsubsubsection{Operations}
1084 newVar :: a -> ST s (MutableVar s a)
1085 readVar :: MutableVar s a -> ST s a
1086 writeVar :: MutableVar s a -> a -> ST s ()
1087 sameVar :: MutableVar s a -> MutableVar s a -> Bool
1091 \subsubsection{Stable pointers}
1093 Nothing exciting here, just simple boxing up.
1095 data StablePtr a = StablePtr (StablePtr# a)
1097 makeStablePointer :: a -> StablePtr a
1098 freeStablePointer :: StablePtr a -> PrimIO ()
1101 \subsubsection{Foreign objects}
1103 Again, just boxing up.
1105 data ForeignObj = ForeignObj ForeignObj#
1107 makeForeignObj :: Addr -- object to be boxed up as a ForeignObj
1108 -> Addr -- finaliser
1109 -> PrimIO ForeignObj
1112 \subsubsection{C calls}
1114 Everything in this section goes for @_casm_@ too.
1116 {\bf ToDo:} {\em mention @_ccall_gc_@ and @_casm_gc_@...}
1118 The @_ccall_@ construct has the following form:
1119 $$@_ccall_@~croutine~a_1~\ldots~a_n$$
1120 This whole construct has type @PrimIO@~$res$.
1121 The rules are these:
1124 The first ``argument'', $croutine$, must be the literal name of a C procedure.
1125 It cannot be a Haskell expression which evaluates to a string, etc; it must be
1126 simply the name of the procedure.
1128 The arguments $a_1, \ldots,a_n$ must be of {\em C-callable} type.
1130 The whole construct has type @PrimIO@~$ty$, where $ty$ is a {\em C-returnable} type.
1132 A {\em boxed-primitive} type is both C-callable and C-returnable.
1133 A boxed primitive type is anything declared by:
1138 where @t@ is a primitive type. Note that
1139 programmer-defined boxed-primitive types are perfectly OK:
1141 data Widget = W# Int#
1142 data Screen = S# CHeapPtr#
1146 There are other types that can be passed to C (C-callable). This
1147 table summarises (including the standard boxed-primitive types):
1149 Boxed Type of transferd Corresp. Which is
1150 Type Prim. component C type *probably*...
1151 ------ --------------- ------ -------------
1152 Char Char# StgChar unsigned char
1153 Int Int# StgInt long int
1154 Word Word# StgWord unsigned long int
1155 Addr Addr# StgAddr char *
1156 Float Float# StgFloat float
1157 Double Double# StgDouble double
1159 Array Array# StgArray StgPtr
1160 ByteArray ByteArray# StgByteArray StgPtr
1161 MutableArray MutableArray# StgArray StgPtr
1162 MutableByteArray MutableByteArray# StgByteArray StgPtr
1164 State State# nothing!
1166 StablePtr StablePtr# StgStablePtr StgPtr
1167 ForeignObj ForeignObj# StgForeignObj StgPtr
1171 All of the above are {\em C-returnable} except:
1173 Array, ByteArray, MutableArray, MutableByteArray, ForeignObj
1176 {\bf ToDo:} I'm pretty wary of @Array@ and @MutableArray@ being in
1177 this list, and not too happy about @State@ [WDP].
1179 {\bf ToDo:} Can code generator pass all the primitive types? Should this be
1180 extended to include {\tt Bool\/} (or any enumeration type?)
1182 The type checker must be able to figure out just which of the C-callable/returnable
1183 types is being used. If it can't, you have to add type signatures. For example,
1188 is not good enough, because the compiler can't work out what type @x@ is, nor
1189 what type the @_ccall_@ returns. You have to write, say:
1191 f :: Int -> PrimIO Float
1196 \subsubsubsection{Implementation}
1198 The desugarer unwraps the @_ccall_@ construct by inserting the
1199 necessary evaluations etc to unbox the arguments. For example, the
1200 body of the definition of @f@ above would become:
1202 (\ s -> case x of { I# x# ->
1203 case s of { S# s# ->
1204 case ccall# [Int#,Float#] x# s# of { StateAndFloat# f# new_s# ->
1209 Notice that the state, too, is unboxed.
1211 %The code generator must deal specially with primitive objects which
1212 %are stored on the heap.
1215 %... details omitted ...
1219 %More importantly, it must construct a C Heap Pointer heap-object after
1220 %a @_ccall_@ which returns a @MallocPtr#@.
1223 %--------------------------------------------------------
1224 \subsection{Non-primitive stuff that must be wired into GHC}
1227 data Char = C# Char#
1229 data Word = W# Word#
1230 data Addr = A# Addr#
1232 data Float = F# Float#
1233 data Double = D# Double#
1234 data Integer = J# Int# Int# ByteArray#
1236 -- and the other boxed-primitive types:
1237 Array, ByteArray, MutableArray, MutableByteArray,
1238 StablePtr, ForeignObj
1240 data Bool = False | True
1241 data Ordering = LT | EQ | GT -- used in derived comparisons
1243 data List a = [] | a : (List a)
1246 data Lift a = Lift a -- used Yukkily as described elsewhere
1248 type String = [Char] -- convenience, only
1252 %------------------------------------------------------------
1253 \subsection{Programmer interface(s)}
1255 \subsubsection{The bog-standard interface}
1257 If you rely on the implicit @import Prelude@ that GHC normally does
1258 for you, and if you don't use any weird flags (notably
1259 @-fglasgow-exts@), and if you don't import the Glasgow extensions
1260 interface, @GlaExts@, then GHC should work {\em exactly} as the
1261 Haskell report says, and the full user namespaces should be available
1264 \subsubsubsection{If you mess about with @import Prelude@...}
1266 Innocent hiding, e.g.,
1268 import Prelude hiding ( fromIntegral )
1271 should work just fine.
1273 There are some things you can do that will make GHC crash, e.g.,
1274 hiding a standard class:
1276 import Prelude hiding ( Eq(..) )
1281 \subsubsection{Turning on Glasgow extensions with @-fglasgow-exts@}
1283 % Updated to tell the 2.02+ story -- SOF
1285 If you turn on @-fglasgow-exts@, the compiler will recognise and parse
1286 unboxed values properly. To get at the primitive operations described
1287 herein, import the interface @GlaExts@.
1289 % 1.3+ module system makes this a non-issue.
1290 %%It is possible that some name conflicts between your code and the
1291 %%wired-in things might spring to life (though we doubt it...).
1292 %%Change your names :-)
1294 %************************************************************************
1296 \subsubsection{The @GlaExts@ interface}
1297 \index{GlaExts interface (GHC extensions)}
1299 %************************************************************************
1301 The @GlaExts@ interface is the programmer gateway to most of the
1302 programmer extensions GHC implement. Currently on tap:
1305 -- PrimIO monad (state transformer, no exceptions).
1306 type PrimIO a = ST RealWorld a
1307 -- instances of: Monad
1308 data RealWorld -- abstract State value
1310 thenPrimIO :: PrimIO a -> (a -> PrimIO b) -> PrimIO b
1311 returnPrimIO :: a -> PrimIO a
1312 seqPrimIO :: PrimIO a -> PrimIO b -> PrimIO b
1314 fixPrimIO :: (a -> PrimIO a) -> PrimIO a
1315 unsafePerformPrimIO :: PrimIO a -> a
1316 unsafeInterleavePrimIO :: PrimIO a -> PrimIO a
1318 -- backwards compatibility
1319 listPrimIO :: [PrimIO a] -> PrimIO [a]
1320 mapPrimIO :: (a -> PrimIO b) -> [a] -> PrimIO [b]
1321 mapAndUnzipPrimIO :: (a -> PrimIO (b,c)) -> [a] -> PrimIO ([b],[c])
1323 -- Combining ST and PrimIO monads with IO
1324 stToIO, -- :: ST RealWorld a -> IO a
1325 primIOToIO, -- :: PrimIO a -> IO a
1326 ioToST, -- :: IO a -> ST RealWorld a
1327 ioToPrimIO, -- :: IO a -> PrimIO a
1328 thenIO_Prim, -- :: PrimIO a -> (a -> IO b) -> IO b
1329 seqIO_Prim, -- :: PrimIO a -> IO b -> IO b
1331 -- the representation of some basic types:
1332 data Char = C# Char#
1334 data Addr = A# Addr#
1335 data Word = W# Word#
1336 data Float = F# Float#
1337 data Double = D# Double#
1338 data Integer = J# Int# Int# ByteArray#
1341 trace :: String -> a -> a
1342 data Lift a = Lift a
1344 -- re-exported interfaces:
1347 module GHC -- all primops and primitive types.
1351 %************************************************************************
1353 \subsubsection{The @MutVar@ interface}
1354 \index{MutVar interface (GHC extensions)}
1356 %************************************************************************
1358 @MutVar@ defines an interface to mutable variables, defining type and
1362 data MutVar -- abstract
1364 newVar :: a -> IO (MutVar a)
1365 readVar :: MutVar a -> IO a
1366 writeVar :: MutVar a -> a -> IO ()
1367 sameVar :: MutVar a -> MutVar a -> Bool
1371 %************************************************************************
1373 \subsubsection{The @MutableArray@ interface}
1374 \index{MutableArray interface (GHC extensions)}
1376 %************************************************************************
1378 The @MutableArray@ interface defines a general set of operations over
1379 mutable arrays (@MutableArray@) and mutable chunks of memory
1380 (@MutableByteArray@):
1383 data MutableArray s ix elt -- abstract
1384 data MutableByteArray s ix -- abstract
1385 -- instance of : CCallable
1387 newArray :: Ix ix => (ix,ix) -> elt -> ST s (MutableArray s ix elt)
1388 newCharArray :: Ix ix => (ix,ix) -> ST s (MutableByteArray s ix)
1389 newAddrArray :: Ix ix => (ix,ix) -> ST s (MutableByteArray s ix)
1390 newIntArray :: Ix ix => (ix,ix) -> ST s (MutableByteArray s ix)
1391 newFloatArray :: Ix ix => (ix,ix) -> ST s (MutableByteArray s ix)
1392 newDoubleArray :: Ix ix => (ix,ix) -> ST s (MutableByteArray s ix)
1394 boundsOfArray :: Ix ix => MutableArray s ix elt -> (ix, ix)
1395 boundsOfByteArray :: Ix ix => MutableByteArray s ix -> (ix, ix)
1398 readArray :: Ix ix => MutableArray s ix elt -> ix -> ST s elt
1400 readCharArray :: Ix ix => MutableByteArray s ix -> ix -> ST s Char
1401 readIntArray :: Ix ix => MutableByteArray s ix -> ix -> ST s Int
1402 readAddrArray :: Ix ix => MutableByteArray s ix -> ix -> ST s Addr
1403 readFloatArray :: Ix ix => MutableByteArray s ix -> ix -> ST s Float
1404 readDoubleArray :: Ix ix => MutableByteArray s ix -> ix -> ST s Double
1406 writeArray :: Ix ix => MutableArray s ix elt -> ix -> elt -> ST s ()
1407 writeCharArray :: Ix ix => MutableByteArray s ix -> ix -> Char -> ST s ()
1408 writeIntArray :: Ix ix => MutableByteArray s ix -> ix -> Int -> ST s ()
1409 writeAddrArray :: Ix ix => MutableByteArray s ix -> ix -> Addr -> ST s ()
1410 writeFloatArray :: Ix ix => MutableByteArray s ix -> ix -> Float -> ST s ()
1411 writeDoubleArray :: Ix ix => MutableByteArray s ix -> ix -> Double -> ST s ()
1413 freezeArray :: Ix ix => MutableArray s ix elt -> ST s (Array ix elt)
1414 freezeCharArray :: Ix ix => MutableByteArray s ix -> ST s (ByteArray ix)
1415 freezeIntArray :: Ix ix => MutableByteArray s ix -> ST s (ByteArray ix)
1416 freezeAddrArray :: Ix ix => MutableByteArray s ix -> ST s (ByteArray ix)
1417 freezeFloatArray :: Ix ix => MutableByteArray s ix -> ST s (ByteArray ix)
1418 freezeDoubleArray :: Ix ix => MutableByteArray s ix -> ST s (ByteArray ix)
1420 unsafeFreezeArray :: Ix ix => MutableArray s ix elt -> ST s (Array ix elt)
1421 unsafeFreezeByteArray :: Ix ix => MutableByteArray s ix -> ST s (ByteArray ix)
1422 thawArray :: Ix ix => Array ix elt -> ST s (MutableArray s ix elt)
1426 %************************************************************************
1428 \subsubsection{The @ByteArray@ interface}
1429 \index{ByteArray interface (GHC extensions)}
1431 %************************************************************************
1433 @ByteArray@s are chunks of immutable Haskell heap:
1436 data ByteArray ix -- abstract
1437 -- instance of: CCallable
1439 indexCharArray :: Ix ix => ByteArray ix -> ix -> Char
1440 indexIntArray :: Ix ix => ByteArray ix -> ix -> Int
1441 indexAddrArray :: Ix ix => ByteArray ix -> ix -> Addr
1442 indexFloatArray :: Ix ix => ByteArray ix -> ix -> Float
1443 indexDoubleArray :: Ix ix => ByteArray ix -> ix -> Double
1445 indexCharOffAddr :: Addr -> Int -> Char
1446 indexIntOffAddr :: Addr -> Int -> Int
1447 indexAddrOffAddr :: Addr -> Int -> Addr
1448 indexFloatOffAddr :: Addr -> Int -> Float
1449 indexDoubleOffAddr :: Addr -> Int -> Double
1453 %************************************************************************
1455 \subsubsection{The @Foreign@ interface}
1456 \index{Foreign interface (GHC extensions)}
1458 %************************************************************************
1460 The @Foreign@ interface define and export operations over @ForeignObj@
1464 -- semi-magic classes for pack/unpacking ccall arguments.
1466 {- Instances defined for :
1467 Char Char# Int Int# Float Float#
1468 Double Double# Addr Addr# Word Word#
1469 (MutableByteArray s ix) (MutableByteArray# s)
1470 (ByteArray ix) ByteArray#
1471 ForeignObj ForeignObj#
1477 {- Instances defined for :
1478 Char Int Float Double Addr Word
1482 data ForeignObj = ForeignObj ForeignObj#
1483 -- instances of : CCallable Eq
1485 eqForeignObj :: ForeignObj -> ForeignObj -> Bool
1486 makeForeignObj :: Addr -> Addr -> PrimIO ForeignObj
1487 writeForeignObj :: ForeignObj -> Addr -> PrimIO ()
1489 {- derived op - attaching a free() finaliser to a malloc() allocated reference. -}
1490 makeMallocPtr :: Addr -> PrimIO ForeignObj
1492 data StablePtr a = StablePtr (StablePtr# a)
1493 -- instances of : CCallable
1495 makeStablePtr :: a -> PrimIO (StablePtr a)
1496 deRefStablePtr :: StablePtr a -> PrimIO a
1497 freeStablePtr :: StablePtr a -> PrimIO ()
1498 performGC :: PrimIO ()
1501 \begin{onlystandalone}
1503 \end{onlystandalone}