2 % $Id: libraries.vsgml,v 1.1 1998/01/30 17:02:32 simonm Exp $
4 % GHC Prelude and Libraries.
7 <sect>The GHC prelude and libraries
8 <label id="ghc-prelude">
11 This document describes GHC's prelude and libraries. The basic story is that of
12 the Haskell 1.4 Report and Libraries document (which we do not reproduce here),
13 but this document describes in addition:
17 <item> GHC's additional non-standard libraries and types, such as
18 state transformers, packed strings, foreign objects, stable
21 <item> GHC's primitive types and operations. The standard Haskell
22 functions are implemented on top of these, and it is sometimes
23 useful to use them directly.
25 <item> The organisation of these libraries into directories.
27 <item> Short description of programmer interface to the non-standard
28 libraries provided in addition to the standard prelude.
31 A number of the libraries that provide access to GHC's language
32 extensions are shared by Hugs, and are described in the <htmlurl
33 name="GHC/Hugs Extension Libraries" url="libs.html"> document.
35 <sect1>Prelude extensions
36 <label id="ghc-prelude-exts">
39 GHC's prelude contains the following non-standard extensions:
43 <tag>@fromInt@ method in class @Num@:</tag> It's there. Converts from
46 <tag>@toInt@ method in class @Integral@:</tag> Converts from type type
51 GHC also internally uses a number of modules that begin with the
52 string @Prel@: for this reason, we don't recommend that you use any
53 module names beginning with @Prel@ in your own programs. The @Prel@
54 modules are always available: in fact, you can get access to several
55 extensions this way (for some you might need to give the
56 @-fglasgow-exts@<nidx>-fglasgow-exts option</nidx> flag).
58 <sect1>The module @PrelGHC@: really primitive stuff
59 <label id="ghc-libs-ghc">
62 This section defines all the types which are primitive in Glasgow
63 Haskell, and the operations provided for them.
65 A primitive type is one which cannot be defined in Haskell, and which
66 is therefore built into the language and compiler. Primitive types
67 are always unboxed; that is, a value of primitive type cannot be
70 Primitive values are often represented by a simple bit-pattern, such
71 as @Int#@, @Float#@, @Double#@. But this is not necessarily the case:
72 a primitive value might be represented by a pointer to a
73 heap-allocated object. Examples include @Array#@, the type of
74 primitive arrays. You might think this odd: doesn't being
75 heap-allocated mean that it has a box? No, it does not. A primitive
76 array is heap-allocated because it is too big a value to fit in a
77 register, and would be too expensive to copy around; in a sense, it is
78 accidental that it is represented by a pointer. If a pointer
79 represents a primitive value, then it really does point to that value:
80 no unevaluated thunks, no indirections...nothing can be at the other
81 end of the pointer than the primitive value.
83 This section also describes a few non-primitive types, which are needed
84 to express the result types of some primitive operations.
86 <sect2>Character and numeric types
88 <nidx>character types, primitive</nidx>
89 <nidx>numeric types, primitive</nidx>
90 <nidx>integer types, primitive</nidx>
91 <nidx>floating point types, primitive</nidx>
93 There are the following obvious primitive types:
97 type Int# -- see also Word# and Addr#, later
106 If you really want to know their exact equivalents in C, see
107 @ghc/includes/StgTypes.lh@ in the GHC source tree.
109 Literals for these types may be written as follows:
115 'a'# a Char#; for weird characters, use '\o<octal>'#
116 "a"# an Addr# (a `char *')
118 <nidx>literals, primitive</nidx>
119 <nidx>constants, primitive</nidx>
120 <nidx>numbers, primitive</nidx>
122 <sect2> Comparison operations
124 <nidx>comparisons, primitive</nidx>
125 <nidx>operators, comparison</nidx>
128 {>,>=,==,/=,<,<=}# :: Int# -> Int# -> Bool
130 {gt,ge,eq,ne,lt,le}Char# :: Char# -> Char# -> Bool
131 -- ditto for Word# and Addr#
139 <ncdx>gt{Char,Word,Addr}#</ncdx>
140 <ncdx>ge{Char,Word,Addr}#</ncdx>
141 <ncdx>eq{Char,Word,Addr}#</ncdx>
142 <ncdx>ne{Char,Word,Addr}#</ncdx>
143 <ncdx>lt{Char,Word,Addr}#</ncdx>
144 <ncdx>le{Char,Word,Addr}#</ncdx>
146 <sect2> Primitive-character operations
148 <nidx>characters, primitive</nidx>
149 <nidx>operators, primitive character</nidx>
152 ord# :: Char# -> Int#
153 chr# :: Int# -> Char#
159 <sect2> Primitive-@Int@ operations
161 <nidx>integers, primitive</nidx>
162 <nidx>operators, primitive integer</nidx>
165 {+,-,*,quotInt,remInt}# :: Int# -> Int# -> Int#
166 negateInt# :: Int# -> Int#
168 iShiftL#, iShiftRA#, iShiftRL# :: Int# -> Int# -> Int#
169 -- shift left, right arithmetic, right logical
174 <ncdx>quotInt#</ncdx>
176 <ncdx>iShiftL#</ncdx>
177 <ncdx>iShiftRA#</ncdx>
178 <ncdx>iShiftRL#</ncdx>
179 <nidx>shift operations, integer</nidx>
181 <bf>Note:</bf> No error/overflow checking!
183 <sect2> Primitive-@Double@ and @Float@ operations
185 <nidx>floating point numbers, primitive</nidx>
186 <nidx>operators, primitive floating point</nidx>
189 {+,-,*,/}## :: Double# -> Double# -> Double#
190 {<,<=,==,/=,>=,>}## :: Double# -> Double# -> Bool
191 negateDouble# :: Double# -> Double#
192 double2Int# :: Double# -> Int#
193 int2Double# :: Int# -> Double#
195 {plus,minux,times,divide}Float# :: Float# -> Float# -> Float#
196 {gt,ge,eq,ne,lt,le}Float# :: Float# -> Float# -> Bool
197 negateFloat# :: Float# -> Float#
198 float2Int# :: Float# -> Int#
199 int2Float# :: Int# -> Float#
212 <ncdx>negateDouble#</ncdx>
213 <ncdx>double2Int#</ncdx>
214 <ncdx>int2Double#</ncdx>
216 <ncdx>plusFloat#</ncdx>
217 <ncdx>minusFloat#</ncdx>
218 <ncdx>timesFloat#</ncdx>
219 <ncdx>divideFloat#</ncdx>
220 <ncdx>gtFloat#</ncdx>
221 <ncdx>geFloat#</ncdx>
222 <ncdx>eqFloat#</ncdx>
223 <ncdx>neFloat#</ncdx>
224 <ncdx>ltFloat#</ncdx>
225 <ncdx>leFloat#</ncdx>
226 <ncdx>negateFloat#</ncdx>
227 <ncdx>float2Int#</ncdx>
228 <ncdx>int2Float#</ncdx>
230 And a full complement of trigonometric functions:
233 expDouble# :: Double# -> Double#
234 logDouble# :: Double# -> Double#
235 sqrtDouble# :: Double# -> Double#
236 sinDouble# :: Double# -> Double#
237 cosDouble# :: Double# -> Double#
238 tanDouble# :: Double# -> Double#
239 asinDouble# :: Double# -> Double#
240 acosDouble# :: Double# -> Double#
241 atanDouble# :: Double# -> Double#
242 sinhDouble# :: Double# -> Double#
243 coshDouble# :: Double# -> Double#
244 tanhDouble# :: Double# -> Double#
245 powerDouble# :: Double# -> Double# -> Double#
247 <nidx>trigonometric functions, primitive</nidx>
249 similarly for @Float#@.
251 There are two coercion functions for @Float#@/@Double#@:
254 float2Double# :: Float# -> Double#
255 double2Float# :: Double# -> Float#
257 <ncdx>float2Double#</ncdx>
258 <ncdx>double2Float#</ncdx>
260 The primitive versions of @encodeDouble@/@decodeDouble@:
263 encodeDouble# :: Int# -> Int# -> ByteArray# -- Integer mantissa
264 -> Int# -- Int exponent
267 decodeDouble# :: Double# -> PrelNum.ReturnIntAndGMP
269 <ncdx>encodeDouble#</ncdx>
270 <ncdx>decodeDouble#</ncdx>
272 (And the same for @Float#@s.)
274 <sect2>Operations on/for @Integers@ (interface to GMP)
275 <label id="horrid-Integer-pairing-types">
277 <nidx>arbitrary precision integers</nidx>
278 <nidx>Integer, operations on</nidx>
280 We implement @Integers@ (arbitrary-precision integers) using the GNU
281 multiple-precision (GMP) package (version 1.3.2).
283 <bf>Note:</bf> some of this might change when we upgrade to using
286 The data type for @Integer@ must mirror that for @MP_INT@ in @gmp.h@
287 (see @gmp.info@ in @ghc/includes/runtime/gmp@). It comes out as:
290 data Integer = J# Int# Int# ByteArray#
292 <nidx>Integer type</nidx>
294 So, @Integer@ is really just a ``pairing'' type for a particular
295 collection of primitive types.
297 The operations in the GMP return other combinations of
298 GMP-plus-something, so we need ``pairing'' types for those, too:
301 data Return2GMPs = Return2GMPs Int# Int# ByteArray# Int# Int# ByteArray#
302 data ReturnIntAndGMP = ReturnIntAndGMP Int# Int# Int# ByteArray#
304 -- ????? something to return a string of bytes (in the heap?)
306 <ncdx>Return2GMPs</ncdx>
307 <ncdx>ReturnIntAndGMP</ncdx>
309 The primitive ops to support @Integers@ use the ``pieces'' of the
310 representation, and are as follows:
313 negateInteger# :: Int# -> Int# -> ByteArray# -> Integer
315 {plus,minus,times}Integer# :: Int# -> Int# -> ByteArray#
316 -> Int# -> Int# -> ByteArray#
319 cmpInteger# :: Int# -> Int# -> ByteArray#
320 -> Int# -> Int# -> ByteArray#
321 -> Int# -- -1 for <; 0 for ==; +1 for >
323 divModInteger#, quotRemInteger#
324 :: Int# -> Int# -> ByteArray#
325 -> Int# -> Int# -> ByteArray#
326 -> PrelNum.Return2GMPs
328 integer2Int# :: Int# -> Int# -> ByteArray# -> Int#
330 int2Integer# :: Int# -> Integer -- NB: no error-checking on these two!
331 word2Integer# :: Word# -> Integer
333 addr2Integer# :: Addr# -> Integer
334 -- the Addr# is taken to be a `char *' string
335 -- to be converted into an Integer.
337 <ncdx>negateInteger#</ncdx>
338 <ncdx>plusInteger#</ncdx>
339 <ncdx>minusInteger#</ncdx>
340 <ncdx>timesInteger#</ncdx>
341 <ncdx>cmpInteger#</ncdx>
342 <ncdx>divModInteger#</ncdx>
343 <ncdx>quotRemInteger#</ncdx>
344 <ncdx>integer2Int#</ncdx>
345 <ncdx>int2Integer#</ncdx>
346 <ncdx>word2Integer#</ncdx>
347 <ncdx>addr2Integer#</ncdx>
349 <sect2>Words and addresses
351 <nidx>word, primitive type</nidx>
352 <nidx>address, primitive type</nidx>
353 <nidx>unsigned integer, primitive type</nidx>
354 <nidx>pointer, primitive type</nidx>
356 A @Word#@ is used for bit-twiddling operations. It is the same size as
357 an @Int#@, but has no sign nor any arithmetic operations.
359 type Word# -- Same size/etc as Int# but *unsigned*
360 type Addr# -- A pointer from outside the "Haskell world" (from C, probably);
361 -- described under "arrays"
367 @Word#@s and @Addr#@s have the usual comparison operations.
368 Other unboxed-@Word@ ops (bit-twiddling and coercions):
371 and#, or#, xor# :: Word# -> Word# -> Word#
374 quotWord#, remWord# :: Word# -> Word# -> Word#
375 -- word (i.e. unsigned) versions are different from int
376 -- versions, so we have to provide these explicitly.
378 not# :: Word# -> Word#
380 shiftL#, shiftRA#, shiftRL# :: Word# -> Int# -> Word#
381 -- shift left, right arithmetic, right logical
383 int2Word# :: Int# -> Word# -- just a cast, really
384 word2Int# :: Word# -> Int#
386 <nidx>bit operations, Word and Addr</nidx>
391 <ncdx>quotWord#</ncdx>
392 <ncdx>remWord#</ncdx>
394 <ncdx>shiftRA#</ncdx>
395 <ncdx>shiftRL#</ncdx>
396 <ncdx>int2Word#</ncdx>
397 <ncdx>word2Int#</ncdx>
399 Unboxed-@Addr@ ops (C casts, really):
401 int2Addr# :: Int# -> Addr#
402 addr2Int# :: Addr# -> Int#
404 <ncdx>int2Addr#</ncdx>
405 <ncdx>addr2Int#</ncdx>
407 The casts between @Int#@, @Word#@ and @Addr#@ correspond to null
408 operations at the machine level, but are required to keep the Haskell
411 Operations for indexing off of C pointers (@Addr#@s) to snatch values
412 are listed under ``arrays''.
416 <nidx>arrays, primitive</nidx>
418 The type @Array# elt@ is the type of primitive, unpointed arrays of
419 values of type @elt@.
426 @Array#@ is more primitive than a Haskell array --- indeed, the
427 Haskell @Array@ interface is implemented using @Array#@ --- in that an
428 @Array#@ is indexed only by @Int#@s, starting at zero. It is also
429 more primitive by virtue of being unboxed. That doesn't mean that it
430 isn't a heap-allocated object - of course, it is. Rather, being
431 unboxed means that it is represented by a pointer to the array itself,
432 and not to a thunk which will evaluate to the array (or to bottom).
433 The components of an @Array#@ are themselves boxed.
435 The type @ByteArray#@ is similar to @Array#@, except that it contains
436 just a string of (non-pointer) bytes.
441 <ncdx>ByteArray#</ncdx>
443 Arrays of these types are useful when a Haskell program wishes to
444 construct a value to pass to a C procedure. It is also possible to
445 use them to build (say) arrays of unboxed characters for internal use
446 in a Haskell program. Given these uses, @ByteArray#@ is deliberately
447 a bit vague about the type of its components. Operations are provided
448 to extract values of type @Char#@, @Int#@, @Float#@, @Double#@, and
449 @Addr#@ from arbitrary offsets within a @ByteArray#@. (For type
450 @Foo#@, the $i$th offset gets you the $i$th @Foo#@, not the @Foo#@ at
451 byte-position $i$. Mumble.) (If you want a @Word#@, grab an @Int#@,
454 Lastly, we have static byte-arrays, of type @Addr#@ [mentioned
455 previously]. (Remember the duality between arrays and pointers in C.)
456 Arrays of this types are represented by a pointer to an array in the
457 world outside Haskell, so this pointer is not followed by the garbage
458 collector. In other respects they are just like @ByteArray#@. They
459 are only needed in order to pass values from C to Haskell.
461 <sect2>Reading and writing
464 Primitive arrays are linear, and indexed starting at zero.
466 The size and indices of a @ByteArray#@, @Addr#@, and
467 @MutableByteArray#@ are all in bytes. It's up to the program to
468 calculate the correct byte offset from the start of the array. This
469 allows a @ByteArray#@ to contain a mixture of values of different
470 type, which is often needed when preparing data for and unpicking
471 results from C. (Umm... not true of indices... WDP 95/09)
473 <em>Should we provide some @sizeOfDouble#@ constants?</em>
475 Out-of-range errors on indexing should be caught by the code which
476 uses the primitive operation; the primitive operations themselves do
477 <em>not</em> check for out-of-range indexes. The intention is that the
478 primitive ops compile to one machine instruction or thereabouts.
480 We use the terms ``reading'' and ``writing'' to refer to accessing
481 <em>mutable</em> arrays (see Section~<ref name="Mutable arrays" id="sect:mutable">), and
482 ``indexing'' to refer to reading a value from an <em>immutable</em>
485 Immutable byte arrays are straightforward to index (all indices in bytes):
487 indexCharArray# :: ByteArray# -> Int# -> Char#
488 indexIntArray# :: ByteArray# -> Int# -> Int#
489 indexAddrArray# :: ByteArray# -> Int# -> Addr#
490 indexFloatArray# :: ByteArray# -> Int# -> Float#
491 indexDoubleArray# :: ByteArray# -> Int# -> Double#
493 indexCharOffAddr# :: Addr# -> Int# -> Char#
494 indexIntOffAddr# :: Addr# -> Int# -> Int#
495 indexFloatOffAddr# :: Addr# -> Int# -> Float#
496 indexDoubleOffAddr# :: Addr# -> Int# -> Double#
497 indexAddrOffAddr# :: Addr# -> Int# -> Addr#
498 -- Get an Addr# from an Addr# offset
500 <ncdx>indexCharArray#</ncdx>
501 <ncdx>indexIntArray#</ncdx>
502 <ncdx>indexAddrArray#</ncdx>
503 <ncdx>indexFloatArray#</ncdx>
504 <ncdx>indexDoubleArray#</ncdx>
505 <ncdx>indexCharOffAddr#</ncdx>
506 <ncdx>indexIntOffAddr#</ncdx>
507 <ncdx>indexFloatOffAddr#</ncdx>
508 <ncdx>indexDoubleOffAddr#</ncdx>
509 <ncdx>indexAddrOffAddr#</ncdx>
511 The last of these, @indexAddrOffAddr#@, extracts an @Addr#@ using an offset
512 from another @Addr#@, thereby providing the ability to follow a chain of
515 Something a bit more interesting goes on when indexing arrays of boxed
516 objects, because the result is simply the boxed object. So presumably
517 it should be entered --- we never usually return an unevaluated
518 object! This is a pain: primitive ops aren't supposed to do
519 complicated things like enter objects. The current solution is to
520 return a lifted value, but I don't like it!
523 indexArray# :: Array# elt -> Int# -> PrelBase.Lift elt -- Yuk!
525 <ncdx>indexArray#</ncdx>
528 <sect2>The state type
530 <ncdx>state, primitive type</ncdx>
533 The primitive type @State#@ represents the state of a state
534 transformer. It is parameterised on the desired type of state, which
535 serves to keep states from distinct threads distinct from one another.
536 But the <em>only</em> effect of this parameterisation is in the type
537 system: all values of type @State#@ are represented in the same way.
538 Indeed, they are all represented by nothing at all! The code
539 generator ``knows'' to generate no code, and allocate no registers
540 etc, for primitive states.
546 The type @GHC.RealWorld@ is truly opaque: there are no values defined
547 of this type, and no operations over it. It is ``primitive'' in that
548 sense - but it is <em>not unboxed!</em> Its only role in life is to be
549 the type which distinguishes the @IO@ state transformer.
555 <sect2>State of the world
558 A single, primitive, value of type @State# RealWorld@ is provided.
561 realWorld# :: State# GHC.RealWorld
563 <nidx>realWorld# state object</nidx>
565 (Note: in the compiler, not a @PrimOp@; just a mucho magic
566 @Id@. Exported from @GHC@, though).
568 <sect2>State pairing types
570 <label id="horrid-pairing-types">
572 This subsection defines some types which, while they aren't quite
573 primitive because we can define them in Haskell, are very nearly so.
574 They define constructors which pair a primitive state with a value of
575 each primitive type. They are required to express the result type of
576 the primitive operations in the state monad.
578 data StateAndPtr# s elt = StateAndPtr# (State# s) elt
580 data StateAndChar# s = StateAndChar# (State# s) Char#
581 data StateAndInt# s = StateAndInt# (State# s) Int#
582 data StateAndWord# s = StateAndWord# (State# s) Word#
583 data StateAndFloat# s = StateAndFloat# (State# s) Float#
584 data StateAndDouble# s = StateAndDouble# (State# s) Double#
585 data StateAndAddr# s = StateAndAddr# (State# s) Addr#
587 data StateAndStablePtr# s a = StateAndStablePtr# (State# s) (StablePtr# a)
588 data StateAndForeignObj# s = StateAndForeignObj# (State# s) ForeignObj#
589 data StateAndSynchVar# s a = StateAndSynchVar# (State# s) (SynchVar# a)
591 data StateAndArray# s elt = StateAndArray# (State# s) (Array# elt)
592 data StateAndMutableArray# s elt = StateAndMutableArray# (State# s) (MutableArray# s elt)
593 data StateAndByteArray# s = StateAndByteArray# (State# s) ByteArray#
594 data StateAndMutableByteArray# s = StateAndMutableByteArray# (State# s) (MutableByteArray# s)
599 <sect2>Mutable arrays
601 <label id="sect:mutable">
602 <nidx>mutable arrays</nidx>
603 <nidx>arrays, mutable</nidx>
605 Corresponding to @Array#@ and @ByteArray#@, we have the types of
606 mutable versions of each. In each case, the representation is a
607 pointer to a suitable block of (mutable) heap-allocated storage.
610 type MutableArray# s elt
611 type MutableByteArray# s
613 <ncdx>MutableArray#</ncdx>
614 <ncdx>MutableByteArray#</ncdx>
618 <nidx>mutable arrays, allocation</nidx>
619 <nidx>arrays, allocation</nidx>
620 <nidx>allocation, of mutable arrays</nidx>
622 Mutable arrays can be allocated. Only pointer-arrays are initialised;
623 arrays of non-pointers are filled in by ``user code'' rather than by
624 the array-allocation primitive. Reason: only the pointer case has to
625 worry about GC striking with a partly-initialised array.
628 newArray# :: Int# -> elt -> State# s -> StateAndMutableArray# s elt
630 newCharArray# :: Int# -> State# s -> StateAndMutableByteArray# s
631 newIntArray# :: Int# -> State# s -> StateAndMutableByteArray# s
632 newAddrArray# :: Int# -> State# s -> StateAndMutableByteArray# s
633 newFloatArray# :: Int# -> State# s -> StateAndMutableByteArray# s
634 newDoubleArray# :: Int# -> State# s -> StateAndMutableByteArray# s
636 <ncdx>newArray#</ncdx>
637 <ncdx>newCharArray#</ncdx>
638 <ncdx>newIntArray#</ncdx>
639 <ncdx>newAddrArray#</ncdx>
640 <ncdx>newFloatArray#</ncdx>
641 <ncdx>newDoubleArray#</ncdx>
643 The size of a @ByteArray#@ is given in bytes.
645 <sect3>Reading and writing
647 <nidx>arrays, reading and writing</nidx>
650 readArray# :: MutableArray# s elt -> Int# -> State# s -> StateAndPtr# s elt
651 readCharArray# :: MutableByteArray# s -> Int# -> State# s -> StateAndChar# s
652 readIntArray# :: MutableByteArray# s -> Int# -> State# s -> StateAndInt# s
653 readAddrArray# :: MutableByteArray# s -> Int# -> State# s -> StateAndAddr# s
654 readFloatArray# :: MutableByteArray# s -> Int# -> State# s -> StateAndFloat# s
655 readDoubleArray# :: MutableByteArray# s -> Int# -> State# s -> StateAndDouble# s
657 writeArray# :: MutableArray# s elt -> Int# -> elt -> State# s -> State# s
658 writeCharArray# :: MutableByteArray# s -> Int# -> Char# -> State# s -> State# s
659 writeIntArray# :: MutableByteArray# s -> Int# -> Int# -> State# s -> State# s
660 writeAddrArray# :: MutableByteArray# s -> Int# -> Addr# -> State# s -> State# s
661 writeFloatArray# :: MutableByteArray# s -> Int# -> Float# -> State# s -> State# s
662 writeDoubleArray# :: MutableByteArray# s -> Int# -> Double# -> State# s -> State# s
664 <ncdx>readArray#</ncdx>
665 <ncdx>readCharArray#</ncdx>
666 <ncdx>readIntArray#</ncdx>
667 <ncdx>readAddrArray#</ncdx>
668 <ncdx>readFloatArray#</ncdx>
669 <ncdx>readDoubleArray#</ncdx>
670 <ncdx>writeArray#</ncdx>
671 <ncdx>writeCharArray#</ncdx>
672 <ncdx>writeIntArray#</ncdx>
673 <ncdx>writeAddrArray#</ncdx>
674 <ncdx>writeFloatArray#</ncdx>
675 <ncdx>writeDoubleArray#</ncdx>
680 <nidx>arrays, testing for equality</nidx>
682 One can take ``equality'' of mutable arrays. What is compared is the
683 <em>name</em> or reference to the mutable array, not its contents.
686 sameMutableArray# :: MutableArray# s elt -> MutableArray# s elt -> Bool
687 sameMutableByteArray# :: MutableByteArray# s -> MutableByteArray# s -> Bool
689 <ncdx>sameMutableArray#</ncdx>
690 <ncdx>sameMutableByteArray#</ncdx>
692 <sect3>Freezing mutable arrays
694 <nidx>arrays, freezing mutable</nidx>
695 <nidx>freezing mutable arrays</nidx>
696 <nidx>mutable arrays, freezing</nidx>
698 Only unsafe-freeze has a primitive. (Safe freeze is done directly in Haskell
699 by copying the array and then using @unsafeFreeze@.)
702 unsafeFreezeArray# :: MutableArray# s elt -> State# s -> StateAndArray# s elt
703 unsafeFreezeByteArray# :: MutableByteArray# s -> State# s -> StateAndByteArray# s
705 <ncdx>unsafeFreezeArray#</ncdx>
706 <ncdx>unsafeFreezeByteArray#</ncdx>
708 <sect2>Stable pointers
710 <nidx>stable pointers</nidx>
711 <nidx>pointers, stable</nidx>
713 A stable pointer is a name for a Haskell object which can be passed to
714 the external world. It is ``stable'' in the sense that the name does
715 not change when the Haskell garbage collector runs --- in contrast to
716 the address of the object which may well change.
718 The stable pointer type is parameterised by the type of the thing
724 <ncdx>StablePtr#</ncdx>
726 A stable pointer is represented by an index into the (static)
727 @StablePointerTable@. The Haskell garbage collector treats the
728 @StablePointerTable@ as a source of roots for GC.
730 The @makeStablePointer@ function converts a value into a stable
731 pointer. It is part of the @IO@ monad, because we want to be sure
732 we don't allocate one twice by accident, and then only free one of the
736 makeStablePointer# :: a -> State# RealWorld -> StateAndStablePtr# RealWorld a
737 freeStablePointer# :: StablePtr# a -> State# RealWorld -> State# RealWorld
738 deRefStablePointer# :: StablePtr# a -> State# RealWorld -> StateAndPtr RealWorld a
740 <ncdx>makeStablePointer#</ncdx>
741 <ncdx>freeStablePointer#</ncdx>
742 <ncdx>deRefStablePointer#</ncdx>
744 There is also a C procedure @FreeStablePtr@ which frees a stable pointer.
746 %<em>Andy's comment.</em> {\bf Errors:} The following is not strictly true: the current
747 %implementation is not as polymorphic as claimed. The reason for this
748 %is that the C programmer will have to use a different entry-routine
749 %for each type of stable pointer. At present, we only supply a very
750 %limited number (3) of these routines. It might be possible to
751 %increase the range of these routines by providing general purpose
752 %entry points to apply stable pointers to (stable pointers to)
753 %arguments and to enter (stable pointers to) boxed primitive values.
754 %<em>End of Andy's comment.</em>
756 <sect2>Foreign objects
758 <nidx>Foreign objects</nidx>
760 A @ForeignObj#@ is a reference to an object outside the Haskell world
761 (i.e., from the C world, or a reference to an object on another
762 machine completely.), where the Haskell world has been told ``Let me
763 know when you're finished with this ...''.
768 <ncdx>ForeignObj#</ncdx>
770 GHC provides two primitives on @ForeignObj#@:
774 :: Addr# -- foreign reference
775 -> Addr# -- pointer to finalisation routine
776 -> StateAndForeignObj# RealWorld ForeignObj#
778 :: ForeignObj# -- foreign object
783 <ncdx>makeForeignObj#</ncdx>
784 <ncdx>writeForeignObj#</ncdx>
786 The module @Foreign@ (Section <ref name="Foreign objects"
787 id="sec:foreign-obj">) provides a more programmer-friendly interface
790 <sect2>Synchronizing variables (M-vars)
792 <nidx>synchronising variables (M-vars)</nidx>
795 Synchronising variables are the primitive type used to implement
796 Concurrent Haskell's MVars (see the Concurrent Haskell paper for
797 the operational behaviour of these operations).
800 type SynchVar# s elt -- primitive
802 newSynchVar#:: State# s -> StateAndSynchVar# s elt
803 takeMVar# :: SynchVar# s elt -> State# s -> StateAndPtr# s elt
804 putMVar# :: SynchVar# s elt -> State# s -> State# s
806 <ncdx>SynchVar#</ncdx>
807 <ncdx>newSynchVar#</ncdx>
808 <ncdx>takeMVar</ncdx>
811 <sect2>@spark#@ primitive operation (for parallel execution)
813 <nidx>spark primitive operation</nidx>
815 <em>ToDo: say something</em> It's used in the unfolding for @par@.
817 <sect2>The @errorIO#@ primitive operation
819 <nidx>errors, primitive</nidx>
821 The @errorIO#@ primitive takes an argument much like @IO@. It aborts
822 execution of the current program, and continues instead by performing
823 the given @IO@-like value on the current state of the world.
826 errorIO# :: (State# RealWorld# -> a) -> a
828 <ncdx>errorIO#</ncdx>
830 <sect1>GHC/Hugs Extension Libraries
833 The extension libraries provided by both GHC and Hugs are described in
834 the <htmlurl name="GHC/Hugs Extension Libraries" url="libs.html">
837 <sect1>GHC-only Extension Libraries
839 <nidx>libraries, ghc-only</nidx>
840 <nidx>extension libraries, ghc-only</nidx>
842 If you rely on the implicit @import Prelude@ that GHC normally does
843 for you, and if you don't use any weird flags (notably
844 @-fglasgow-exts@), and if you don't import the Glasgow extensions
845 interface, @GlaExts@, then GHC should work <em>exactly</em> as the
846 Haskell report says (modulo a few minor issues, see Section <ref
847 id="vs-Haskell-defn" name="Language Non-compliance">).
849 If you turn on @-fglasgow-exts@, the compiler will recognise and parse
850 unboxed values properly, and provide access to the various interfaces
851 libraries described here.
853 <sect2>The @GlaExts@ interface
855 <nidx>GlaExts interface (GHC extensions)</nidx>
857 The @GlaExts@ interface provides access to extensions that only GHC
858 implements. These currently are: unboxed types, including the
859 representations of the primitive types (Int, Float, etc.), and the
860 GHC primitive operations (@+#@, @==#@, etc.).
862 This module used to provide access to all the Glasgow extensions, but
863 these have since been moved into separate libraries for compatibility
864 with Hugs (version 2.09: in fact, you can still get at this stuff via
865 @GlaExts@ for compatibility, but this facility will likely be removed
869 -- the representation of some basic types:
874 data Float = F# Float#
875 data Double = D# Double#
876 data Integer = J# Int# Int# ByteArray#
878 module GHC -- all primops and primitive types.
881 <sect2>The @MutableArray@ interface
882 <label id="sec:mutable-array">
884 <nidx>MutableArray interface (GHC extensions)</nidx>
886 The @MutableArray@ interface defines a general set of operations over
887 mutable arrays (@MutableArray@) and mutable chunks of memory
888 (@MutableByteArray@):
891 data MutableArray s ix elt -- abstract
892 data MutableByteArray s ix -- abstract
893 -- instance of : CCallable
895 newArray :: Ix ix => (ix,ix) -> elt -> ST s (MutableArray s ix elt)
896 newCharArray :: Ix ix => (ix,ix) -> ST s (MutableByteArray s ix)
897 newAddrArray :: Ix ix => (ix,ix) -> ST s (MutableByteArray s ix)
898 newIntArray :: Ix ix => (ix,ix) -> ST s (MutableByteArray s ix)
899 newFloatArray :: Ix ix => (ix,ix) -> ST s (MutableByteArray s ix)
900 newDoubleArray :: Ix ix => (ix,ix) -> ST s (MutableByteArray s ix)
902 boundsOfArray :: Ix ix => MutableArray s ix elt -> (ix, ix)
903 boundsOfByteArray :: Ix ix => MutableByteArray s ix -> (ix, ix)
906 readArray :: Ix ix => MutableArray s ix elt -> ix -> ST s elt
908 readCharArray :: Ix ix => MutableByteArray s ix -> ix -> ST s Char
909 readIntArray :: Ix ix => MutableByteArray s ix -> ix -> ST s Int
910 readAddrArray :: Ix ix => MutableByteArray s ix -> ix -> ST s Addr
911 readFloatArray :: Ix ix => MutableByteArray s ix -> ix -> ST s Float
912 readDoubleArray :: Ix ix => MutableByteArray s ix -> ix -> ST s Double
914 writeArray :: Ix ix => MutableArray s ix elt -> ix -> elt -> ST s ()
915 writeCharArray :: Ix ix => MutableByteArray s ix -> ix -> Char -> ST s ()
916 writeIntArray :: Ix ix => MutableByteArray s ix -> ix -> Int -> ST s ()
917 writeAddrArray :: Ix ix => MutableByteArray s ix -> ix -> Addr -> ST s ()
918 writeFloatArray :: Ix ix => MutableByteArray s ix -> ix -> Float -> ST s ()
919 writeDoubleArray :: Ix ix => MutableByteArray s ix -> ix -> Double -> ST s ()
921 freezeArray :: Ix ix => MutableArray s ix elt -> ST s (Array ix elt)
922 freezeCharArray :: Ix ix => MutableByteArray s ix -> ST s (ByteArray ix)
923 freezeIntArray :: Ix ix => MutableByteArray s ix -> ST s (ByteArray ix)
924 freezeAddrArray :: Ix ix => MutableByteArray s ix -> ST s (ByteArray ix)
925 freezeFloatArray :: Ix ix => MutableByteArray s ix -> ST s (ByteArray ix)
926 freezeDoubleArray :: Ix ix => MutableByteArray s ix -> ST s (ByteArray ix)
928 unsafeFreezeArray :: Ix ix => MutableArray s ix elt -> ST s (Array ix elt)
929 unsafeFreezeByteArray :: Ix ix => MutableByteArray s ix -> ST s (ByteArray ix)
930 thawArray :: Ix ix => Array ix elt -> ST s (MutableArray s ix elt)
935 <sect2>The @ByteArray@ interface
936 <label id="sec:byte-array">
938 <nidx>ByteArray interface (GHC extensions)</nidx>
940 @ByteArray@s are chunks of immutable Haskell heap:
943 data ByteArray ix -- abstract
944 -- instance of: CCallable
946 indexCharArray :: Ix ix => ByteArray ix -> ix -> Char
947 indexIntArray :: Ix ix => ByteArray ix -> ix -> Int
948 indexAddrArray :: Ix ix => ByteArray ix -> ix -> Addr
949 indexFloatArray :: Ix ix => ByteArray ix -> ix -> Float
950 indexDoubleArray :: Ix ix => ByteArray ix -> ix -> Double
952 indexCharOffAddr :: Addr -> Int -> Char
953 indexIntOffAddr :: Addr -> Int -> Int
954 indexAddrOffAddr :: Addr -> Int -> Addr
955 indexFloatOffAddr :: Addr -> Int -> Float
956 indexDoubleOffAddr :: Addr -> Int -> Double
959 <sect2>Stable pointers
962 Nothing exciting here, just simple boxing up.
964 data StablePtr a = StablePtr (StablePtr# a)
966 makeStablePointer :: a -> StablePtr a
967 freeStablePointer :: StablePtr a -> IO ()
970 <sect2>Foreign objects
971 <label id="sec:foreign-obj">
973 <nidx>Foreign objects</nidx>
975 This module provides the @ForeignObj@ type and wrappers around the
976 primitive operations on foreign objects.
979 data ForeignObj = ForeignObj ForeignObj#
982 :: Addr -- object to be boxed up as a ForeignObj
987 :: ForeignObj -- previously created foreign object
992 <ncdx>ForeignObj</ncdx>
993 <ncdx>makeForeignObj</ncdx>
994 <ncdx>writeForeignObj</ncdx>
996 A typical use of @ForeignObj@ is in constructing Haskell bindings
997 to external libraries. A good example is that of writing a binding to
998 an image-processing library (which was actually the main motivation
999 for implementing @ForeignObj@'s precursor, @MallocPtr#@). The
1000 images manipulated are not stored in the Haskell heap, either because
1001 the library insist on allocating them internally or we (sensibly)
1002 decide to spare the GC from having to heave heavy images around.
1005 data Image = Image ForeignObj
1008 The @ForeignObj@ type is then used to refer to the externally
1009 allocated image, and to acheive some type safety, the Haskell binding
1010 defines the @Image@ data type. So, a value of type @ForeignObj@ is
1011 used to ``box'' up an external reference into a Haskell heap object
1012 that we can then indirectly reference:
1015 createImage :: (Int,Int) -> IO Image
1018 So far, this looks just like an @Addr@ type, but @ForeignObj@ offers a
1019 bit more, namely that we can specify a <em>finalisation routine</em> to
1020 invoke when the @ForeignObj@ is discarded by the GC. The garbage
1021 collector invokes the finalisation routine associated with the
1022 @ForeignObj@, saying `` Thanks, I'm through with this now..'' For the
1023 image-processing library, the finalisation routine could for the
1024 images free up memory allocated for them. The finalisation routine has
1025 currently to be written in C (the finalisation routine can in turn
1026 call on @FreeStablePtr@ to deallocate a stable pointer).
1028 Associating a finalisation routine with an external object is done by
1029 calling @makeForeignObj@. {\bf Note:} the foreign object value and
1030 its finaliser are contained in the @ForeignObj@, so there's no danger
1031 of an aggressive optimiser somehow separating the two (with the result
1032 that the foreign reference would not be freed).
1034 (Implementation: a linked list of all @ForeignObj#@s is maintained to
1035 allow the garbage collector to detect when a @ForeignObj#@ becomes
1038 Like @Array@, @ForeignObj#@s are represented by heap objects.
1040 Upon controlled termination of the Haskell program, all @ForeignObjs@
1041 are freed, invoking their respective finalisers before terminating.
1043 <sect2>The @CCall@ module
1046 The @CCall@ module defines the classes @CCallable@ and @CReturnable@,
1047 along with instances for the primitive types (@Int@, @Int#@, @Float@,
1048 @Float#@ etc.) GHC knows to import this module if you use @_ccall_@,
1049 but if you need to define your own instances of these classes, you
1050 will need to import @CCall@ explicitly.
1052 More information on how to use @_ccall_@ can be found in Section
1053 <ref name="Calling~C directly from Haskell" id="glasgow-ccalls">.