2 % $Id: libraries.vsgml,v 1.2 1998/08/25 18:07:57 sof 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#, shiftRL# :: Word# -> Int# -> Word#
381 -- shift left, 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>shiftRL#</ncdx>
395 <ncdx>int2Word#</ncdx>
396 <ncdx>word2Int#</ncdx>
398 Unboxed-@Addr@ ops (C casts, really):
400 int2Addr# :: Int# -> Addr#
401 addr2Int# :: Addr# -> Int#
403 <ncdx>int2Addr#</ncdx>
404 <ncdx>addr2Int#</ncdx>
406 The casts between @Int#@, @Word#@ and @Addr#@ correspond to null
407 operations at the machine level, but are required to keep the Haskell
410 Operations for indexing off of C pointers (@Addr#@s) to snatch values
411 are listed under ``arrays''.
415 <nidx>arrays, primitive</nidx>
417 The type @Array# elt@ is the type of primitive, unpointed arrays of
418 values of type @elt@.
425 @Array#@ is more primitive than a Haskell array --- indeed, the
426 Haskell @Array@ interface is implemented using @Array#@ --- in that an
427 @Array#@ is indexed only by @Int#@s, starting at zero. It is also
428 more primitive by virtue of being unboxed. That doesn't mean that it
429 isn't a heap-allocated object - of course, it is. Rather, being
430 unboxed means that it is represented by a pointer to the array itself,
431 and not to a thunk which will evaluate to the array (or to bottom).
432 The components of an @Array#@ are themselves boxed.
434 The type @ByteArray#@ is similar to @Array#@, except that it contains
435 just a string of (non-pointer) bytes.
440 <ncdx>ByteArray#</ncdx>
442 Arrays of these types are useful when a Haskell program wishes to
443 construct a value to pass to a C procedure. It is also possible to
444 use them to build (say) arrays of unboxed characters for internal use
445 in a Haskell program. Given these uses, @ByteArray#@ is deliberately
446 a bit vague about the type of its components. Operations are provided
447 to extract values of type @Char#@, @Int#@, @Float#@, @Double#@, and
448 @Addr#@ from arbitrary offsets within a @ByteArray#@. (For type
449 @Foo#@, the $i$th offset gets you the $i$th @Foo#@, not the @Foo#@ at
450 byte-position $i$. Mumble.) (If you want a @Word#@, grab an @Int#@,
453 Lastly, we have static byte-arrays, of type @Addr#@ [mentioned
454 previously]. (Remember the duality between arrays and pointers in C.)
455 Arrays of this types are represented by a pointer to an array in the
456 world outside Haskell, so this pointer is not followed by the garbage
457 collector. In other respects they are just like @ByteArray#@. They
458 are only needed in order to pass values from C to Haskell.
460 <sect2>Reading and writing
463 Primitive arrays are linear, and indexed starting at zero.
465 The size and indices of a @ByteArray#@, @Addr#@, and
466 @MutableByteArray#@ are all in bytes. It's up to the program to
467 calculate the correct byte offset from the start of the array. This
468 allows a @ByteArray#@ to contain a mixture of values of different
469 type, which is often needed when preparing data for and unpicking
470 results from C. (Umm... not true of indices... WDP 95/09)
472 <em>Should we provide some @sizeOfDouble#@ constants?</em>
474 Out-of-range errors on indexing should be caught by the code which
475 uses the primitive operation; the primitive operations themselves do
476 <em>not</em> check for out-of-range indexes. The intention is that the
477 primitive ops compile to one machine instruction or thereabouts.
479 We use the terms ``reading'' and ``writing'' to refer to accessing
480 <em>mutable</em> arrays (see Section~<ref name="Mutable arrays" id="sect:mutable">), and
481 ``indexing'' to refer to reading a value from an <em>immutable</em>
484 Immutable byte arrays are straightforward to index (all indices in bytes):
486 indexCharArray# :: ByteArray# -> Int# -> Char#
487 indexIntArray# :: ByteArray# -> Int# -> Int#
488 indexAddrArray# :: ByteArray# -> Int# -> Addr#
489 indexFloatArray# :: ByteArray# -> Int# -> Float#
490 indexDoubleArray# :: ByteArray# -> Int# -> Double#
492 indexCharOffAddr# :: Addr# -> Int# -> Char#
493 indexIntOffAddr# :: Addr# -> Int# -> Int#
494 indexFloatOffAddr# :: Addr# -> Int# -> Float#
495 indexDoubleOffAddr# :: Addr# -> Int# -> Double#
496 indexAddrOffAddr# :: Addr# -> Int# -> Addr#
497 -- Get an Addr# from an Addr# offset
499 <ncdx>indexCharArray#</ncdx>
500 <ncdx>indexIntArray#</ncdx>
501 <ncdx>indexAddrArray#</ncdx>
502 <ncdx>indexFloatArray#</ncdx>
503 <ncdx>indexDoubleArray#</ncdx>
504 <ncdx>indexCharOffAddr#</ncdx>
505 <ncdx>indexIntOffAddr#</ncdx>
506 <ncdx>indexFloatOffAddr#</ncdx>
507 <ncdx>indexDoubleOffAddr#</ncdx>
508 <ncdx>indexAddrOffAddr#</ncdx>
510 The last of these, @indexAddrOffAddr#@, extracts an @Addr#@ using an offset
511 from another @Addr#@, thereby providing the ability to follow a chain of
514 Something a bit more interesting goes on when indexing arrays of boxed
515 objects, because the result is simply the boxed object. So presumably
516 it should be entered --- we never usually return an unevaluated
517 object! This is a pain: primitive ops aren't supposed to do
518 complicated things like enter objects. The current solution is to
519 return a lifted value, but I don't like it!
522 indexArray# :: Array# elt -> Int# -> PrelBase.Lift elt -- Yuk!
524 <ncdx>indexArray#</ncdx>
527 <sect2>The state type
529 <ncdx>state, primitive type</ncdx>
532 The primitive type @State#@ represents the state of a state
533 transformer. It is parameterised on the desired type of state, which
534 serves to keep states from distinct threads distinct from one another.
535 But the <em>only</em> effect of this parameterisation is in the type
536 system: all values of type @State#@ are represented in the same way.
537 Indeed, they are all represented by nothing at all! The code
538 generator ``knows'' to generate no code, and allocate no registers
539 etc, for primitive states.
545 The type @GHC.RealWorld@ is truly opaque: there are no values defined
546 of this type, and no operations over it. It is ``primitive'' in that
547 sense - but it is <em>not unboxed!</em> Its only role in life is to be
548 the type which distinguishes the @IO@ state transformer.
554 <sect2>State of the world
557 A single, primitive, value of type @State# RealWorld@ is provided.
560 realWorld# :: State# GHC.RealWorld
562 <nidx>realWorld# state object</nidx>
564 (Note: in the compiler, not a @PrimOp@; just a mucho magic
565 @Id@. Exported from @GHC@, though).
567 <sect2>State pairing types
569 <label id="horrid-pairing-types">
571 This subsection defines some types which, while they aren't quite
572 primitive because we can define them in Haskell, are very nearly so.
573 They define constructors which pair a primitive state with a value of
574 each primitive type. They are required to express the result type of
575 the primitive operations in the state monad.
577 data StateAndPtr# s elt = StateAndPtr# (State# s) elt
579 data StateAndChar# s = StateAndChar# (State# s) Char#
580 data StateAndInt# s = StateAndInt# (State# s) Int#
581 data StateAndWord# s = StateAndWord# (State# s) Word#
582 data StateAndFloat# s = StateAndFloat# (State# s) Float#
583 data StateAndDouble# s = StateAndDouble# (State# s) Double#
584 data StateAndAddr# s = StateAndAddr# (State# s) Addr#
586 data StateAndStablePtr# s a = StateAndStablePtr# (State# s) (StablePtr# a)
587 data StateAndForeignObj# s = StateAndForeignObj# (State# s) ForeignObj#
588 data StateAndSynchVar# s a = StateAndSynchVar# (State# s) (SynchVar# a)
590 data StateAndArray# s elt = StateAndArray# (State# s) (Array# elt)
591 data StateAndMutableArray# s elt = StateAndMutableArray# (State# s) (MutableArray# s elt)
592 data StateAndByteArray# s = StateAndByteArray# (State# s) ByteArray#
593 data StateAndMutableByteArray# s = StateAndMutableByteArray# (State# s) (MutableByteArray# s)
598 <sect2>Mutable arrays
600 <label id="sect:mutable">
601 <nidx>mutable arrays</nidx>
602 <nidx>arrays, mutable</nidx>
604 Corresponding to @Array#@ and @ByteArray#@, we have the types of
605 mutable versions of each. In each case, the representation is a
606 pointer to a suitable block of (mutable) heap-allocated storage.
609 type MutableArray# s elt
610 type MutableByteArray# s
612 <ncdx>MutableArray#</ncdx>
613 <ncdx>MutableByteArray#</ncdx>
617 <nidx>mutable arrays, allocation</nidx>
618 <nidx>arrays, allocation</nidx>
619 <nidx>allocation, of mutable arrays</nidx>
621 Mutable arrays can be allocated. Only pointer-arrays are initialised;
622 arrays of non-pointers are filled in by ``user code'' rather than by
623 the array-allocation primitive. Reason: only the pointer case has to
624 worry about GC striking with a partly-initialised array.
627 newArray# :: Int# -> elt -> State# s -> StateAndMutableArray# s elt
629 newCharArray# :: Int# -> State# s -> StateAndMutableByteArray# s
630 newIntArray# :: Int# -> State# s -> StateAndMutableByteArray# s
631 newAddrArray# :: Int# -> State# s -> StateAndMutableByteArray# s
632 newFloatArray# :: Int# -> State# s -> StateAndMutableByteArray# s
633 newDoubleArray# :: Int# -> State# s -> StateAndMutableByteArray# s
635 <ncdx>newArray#</ncdx>
636 <ncdx>newCharArray#</ncdx>
637 <ncdx>newIntArray#</ncdx>
638 <ncdx>newAddrArray#</ncdx>
639 <ncdx>newFloatArray#</ncdx>
640 <ncdx>newDoubleArray#</ncdx>
642 The size of a @ByteArray#@ is given in bytes.
644 <sect3>Reading and writing
646 <nidx>arrays, reading and writing</nidx>
649 readArray# :: MutableArray# s elt -> Int# -> State# s -> StateAndPtr# s elt
650 readCharArray# :: MutableByteArray# s -> Int# -> State# s -> StateAndChar# s
651 readIntArray# :: MutableByteArray# s -> Int# -> State# s -> StateAndInt# s
652 readAddrArray# :: MutableByteArray# s -> Int# -> State# s -> StateAndAddr# s
653 readFloatArray# :: MutableByteArray# s -> Int# -> State# s -> StateAndFloat# s
654 readDoubleArray# :: MutableByteArray# s -> Int# -> State# s -> StateAndDouble# s
656 writeArray# :: MutableArray# s elt -> Int# -> elt -> State# s -> State# s
657 writeCharArray# :: MutableByteArray# s -> Int# -> Char# -> State# s -> State# s
658 writeIntArray# :: MutableByteArray# s -> Int# -> Int# -> State# s -> State# s
659 writeAddrArray# :: MutableByteArray# s -> Int# -> Addr# -> State# s -> State# s
660 writeFloatArray# :: MutableByteArray# s -> Int# -> Float# -> State# s -> State# s
661 writeDoubleArray# :: MutableByteArray# s -> Int# -> Double# -> State# s -> State# s
663 <ncdx>readArray#</ncdx>
664 <ncdx>readCharArray#</ncdx>
665 <ncdx>readIntArray#</ncdx>
666 <ncdx>readAddrArray#</ncdx>
667 <ncdx>readFloatArray#</ncdx>
668 <ncdx>readDoubleArray#</ncdx>
669 <ncdx>writeArray#</ncdx>
670 <ncdx>writeCharArray#</ncdx>
671 <ncdx>writeIntArray#</ncdx>
672 <ncdx>writeAddrArray#</ncdx>
673 <ncdx>writeFloatArray#</ncdx>
674 <ncdx>writeDoubleArray#</ncdx>
679 <nidx>arrays, testing for equality</nidx>
681 One can take ``equality'' of mutable arrays. What is compared is the
682 <em>name</em> or reference to the mutable array, not its contents.
685 sameMutableArray# :: MutableArray# s elt -> MutableArray# s elt -> Bool
686 sameMutableByteArray# :: MutableByteArray# s -> MutableByteArray# s -> Bool
688 <ncdx>sameMutableArray#</ncdx>
689 <ncdx>sameMutableByteArray#</ncdx>
691 <sect3>Freezing mutable arrays
693 <nidx>arrays, freezing mutable</nidx>
694 <nidx>freezing mutable arrays</nidx>
695 <nidx>mutable arrays, freezing</nidx>
697 Only unsafe-freeze has a primitive. (Safe freeze is done directly in Haskell
698 by copying the array and then using @unsafeFreeze@.)
701 unsafeFreezeArray# :: MutableArray# s elt -> State# s -> StateAndArray# s elt
702 unsafeFreezeByteArray# :: MutableByteArray# s -> State# s -> StateAndByteArray# s
704 <ncdx>unsafeFreezeArray#</ncdx>
705 <ncdx>unsafeFreezeByteArray#</ncdx>
707 <sect2>Stable pointers
709 <nidx>stable pointers</nidx>
710 <nidx>pointers, stable</nidx>
712 A stable pointer is a name for a Haskell object which can be passed to
713 the external world. It is ``stable'' in the sense that the name does
714 not change when the Haskell garbage collector runs --- in contrast to
715 the address of the object which may well change.
717 The stable pointer type is parameterised by the type of the thing
723 <ncdx>StablePtr#</ncdx>
725 A stable pointer is represented by an index into the (static)
726 @StablePointerTable@. The Haskell garbage collector treats the
727 @StablePointerTable@ as a source of roots for GC.
729 The @makeStablePointer@ function converts a value into a stable
730 pointer. It is part of the @IO@ monad, because we want to be sure
731 we don't allocate one twice by accident, and then only free one of the
735 makeStablePointer# :: a -> State# RealWorld -> StateAndStablePtr# RealWorld a
736 freeStablePointer# :: StablePtr# a -> State# RealWorld -> State# RealWorld
737 deRefStablePointer# :: StablePtr# a -> State# RealWorld -> StateAndPtr RealWorld a
739 <ncdx>makeStablePointer#</ncdx>
740 <ncdx>freeStablePointer#</ncdx>
741 <ncdx>deRefStablePointer#</ncdx>
743 There is also a C procedure @FreeStablePtr@ which frees a stable pointer.
745 %<em>Andy's comment.</em> {\bf Errors:} The following is not strictly true: the current
746 %implementation is not as polymorphic as claimed. The reason for this
747 %is that the C programmer will have to use a different entry-routine
748 %for each type of stable pointer. At present, we only supply a very
749 %limited number (3) of these routines. It might be possible to
750 %increase the range of these routines by providing general purpose
751 %entry points to apply stable pointers to (stable pointers to)
752 %arguments and to enter (stable pointers to) boxed primitive values.
753 %<em>End of Andy's comment.</em>
755 <sect2>Foreign objects
757 <nidx>Foreign objects</nidx>
759 A @ForeignObj#@ is a reference to an object outside the Haskell world
760 (i.e., from the C world, or a reference to an object on another
761 machine completely.), where the Haskell world has been told ``Let me
762 know when you're finished with this ...''.
767 <ncdx>ForeignObj#</ncdx>
769 GHC provides two primitives on @ForeignObj#@:
773 :: Addr# -- foreign reference
774 -> Addr# -- pointer to finalisation routine
775 -> StateAndForeignObj# RealWorld ForeignObj#
777 :: ForeignObj# -- foreign object
782 <ncdx>makeForeignObj#</ncdx>
783 <ncdx>writeForeignObj#</ncdx>
785 The module @Foreign@ (Section <ref name="Foreign objects"
786 id="sec:foreign-obj">) provides a more programmer-friendly interface
789 <sect2>Synchronizing variables (M-vars)
791 <nidx>synchronising variables (M-vars)</nidx>
794 Synchronising variables are the primitive type used to implement
795 Concurrent Haskell's MVars (see the Concurrent Haskell paper for
796 the operational behaviour of these operations).
799 type SynchVar# s elt -- primitive
801 newSynchVar#:: State# s -> StateAndSynchVar# s elt
802 takeMVar# :: SynchVar# s elt -> State# s -> StateAndPtr# s elt
803 putMVar# :: SynchVar# s elt -> State# s -> State# s
805 <ncdx>SynchVar#</ncdx>
806 <ncdx>newSynchVar#</ncdx>
807 <ncdx>takeMVar</ncdx>
810 <sect2>@spark#@ primitive operation (for parallel execution)
812 <nidx>spark primitive operation</nidx>
814 <em>ToDo: say something</em> It's used in the unfolding for @par@.
816 <sect2>The @errorIO#@ primitive operation
818 <nidx>errors, primitive</nidx>
820 The @errorIO#@ primitive takes an argument much like @IO@. It aborts
821 execution of the current program, and continues instead by performing
822 the given @IO@-like value on the current state of the world.
825 errorIO# :: (State# RealWorld# -> a) -> a
827 <ncdx>errorIO#</ncdx>
829 <sect1>GHC/Hugs Extension Libraries
832 The extension libraries provided by both GHC and Hugs are described in
833 the <htmlurl name="GHC/Hugs Extension Libraries" url="libs.html">
836 <sect1>GHC-only Extension Libraries
838 <nidx>libraries, ghc-only</nidx>
839 <nidx>extension libraries, ghc-only</nidx>
841 If you rely on the implicit @import Prelude@ that GHC normally does
842 for you, and if you don't use any weird flags (notably
843 @-fglasgow-exts@), and if you don't import the Glasgow extensions
844 interface, @GlaExts@, then GHC should work <em>exactly</em> as the
845 Haskell report says (modulo a few minor issues, see Section <ref
846 id="vs-Haskell-defn" name="Language Non-compliance">).
848 If you turn on @-fglasgow-exts@, the compiler will recognise and parse
849 unboxed values properly, and provide access to the various interfaces
850 libraries described here.
852 <sect2>The @GlaExts@ interface
854 <nidx>GlaExts interface (GHC extensions)</nidx>
856 The @GlaExts@ interface provides access to extensions that only GHC
857 implements. These currently are: unboxed types, including the
858 representations of the primitive types (Int, Float, etc.), and the
859 GHC primitive operations (@+#@, @==#@, etc.).
861 This module used to provide access to all the Glasgow extensions, but
862 these have since been moved into separate libraries for compatibility
863 with Hugs (version 2.09: in fact, you can still get at this stuff via
864 @GlaExts@ for compatibility, but this facility will likely be removed
868 -- the representation of some basic types:
873 data Float = F# Float#
874 data Double = D# Double#
875 data Integer = J# Int# Int# ByteArray#
877 module GHC -- all primops and primitive types.
880 <sect2>The @MutableArray@ interface
881 <label id="sec:mutable-array">
883 <nidx>MutableArray interface (GHC extensions)</nidx>
885 The @MutableArray@ interface defines a general set of operations over
886 mutable arrays (@MutableArray@) and mutable chunks of memory
887 (@MutableByteArray@):
890 data MutableArray s ix elt -- abstract
891 data MutableByteArray s ix -- abstract
892 -- instance of : CCallable
894 newArray :: Ix ix => (ix,ix) -> elt -> ST s (MutableArray s ix elt)
895 newCharArray :: Ix ix => (ix,ix) -> ST s (MutableByteArray s ix)
896 newAddrArray :: Ix ix => (ix,ix) -> ST s (MutableByteArray s ix)
897 newIntArray :: Ix ix => (ix,ix) -> ST s (MutableByteArray s ix)
898 newFloatArray :: Ix ix => (ix,ix) -> ST s (MutableByteArray s ix)
899 newDoubleArray :: Ix ix => (ix,ix) -> ST s (MutableByteArray s ix)
901 boundsOfArray :: Ix ix => MutableArray s ix elt -> (ix, ix)
902 boundsOfByteArray :: Ix ix => MutableByteArray s ix -> (ix, ix)
905 readArray :: Ix ix => MutableArray s ix elt -> ix -> ST s elt
907 readCharArray :: Ix ix => MutableByteArray s ix -> ix -> ST s Char
908 readIntArray :: Ix ix => MutableByteArray s ix -> ix -> ST s Int
909 readAddrArray :: Ix ix => MutableByteArray s ix -> ix -> ST s Addr
910 readFloatArray :: Ix ix => MutableByteArray s ix -> ix -> ST s Float
911 readDoubleArray :: Ix ix => MutableByteArray s ix -> ix -> ST s Double
913 writeArray :: Ix ix => MutableArray s ix elt -> ix -> elt -> ST s ()
914 writeCharArray :: Ix ix => MutableByteArray s ix -> ix -> Char -> ST s ()
915 writeIntArray :: Ix ix => MutableByteArray s ix -> ix -> Int -> ST s ()
916 writeAddrArray :: Ix ix => MutableByteArray s ix -> ix -> Addr -> ST s ()
917 writeFloatArray :: Ix ix => MutableByteArray s ix -> ix -> Float -> ST s ()
918 writeDoubleArray :: Ix ix => MutableByteArray s ix -> ix -> Double -> ST s ()
920 freezeArray :: Ix ix => MutableArray s ix elt -> ST s (Array ix elt)
921 freezeCharArray :: Ix ix => MutableByteArray s ix -> ST s (ByteArray ix)
922 freezeIntArray :: Ix ix => MutableByteArray s ix -> ST s (ByteArray ix)
923 freezeAddrArray :: Ix ix => MutableByteArray s ix -> ST s (ByteArray ix)
924 freezeFloatArray :: Ix ix => MutableByteArray s ix -> ST s (ByteArray ix)
925 freezeDoubleArray :: Ix ix => MutableByteArray s ix -> ST s (ByteArray ix)
927 unsafeFreezeArray :: Ix ix => MutableArray s ix elt -> ST s (Array ix elt)
928 unsafeFreezeByteArray :: Ix ix => MutableByteArray s ix -> ST s (ByteArray ix)
929 thawArray :: Ix ix => Array ix elt -> ST s (MutableArray s ix elt)
934 <sect2>The @ByteArray@ interface
935 <label id="sec:byte-array">
937 <nidx>ByteArray interface (GHC extensions)</nidx>
939 @ByteArray@s are chunks of immutable Haskell heap:
942 data ByteArray ix -- abstract
943 -- instance of: CCallable
945 indexCharArray :: Ix ix => ByteArray ix -> ix -> Char
946 indexIntArray :: Ix ix => ByteArray ix -> ix -> Int
947 indexAddrArray :: Ix ix => ByteArray ix -> ix -> Addr
948 indexFloatArray :: Ix ix => ByteArray ix -> ix -> Float
949 indexDoubleArray :: Ix ix => ByteArray ix -> ix -> Double
951 indexCharOffAddr :: Addr -> Int -> Char
952 indexIntOffAddr :: Addr -> Int -> Int
953 indexAddrOffAddr :: Addr -> Int -> Addr
954 indexFloatOffAddr :: Addr -> Int -> Float
955 indexDoubleOffAddr :: Addr -> Int -> Double
958 <sect2>Stable pointers
961 Nothing exciting here, just simple boxing up.
963 data StablePtr a = StablePtr (StablePtr# a)
965 makeStablePointer :: a -> StablePtr a
966 freeStablePointer :: StablePtr a -> IO ()
969 <sect2>Foreign objects
970 <label id="sec:foreign-obj">
972 <nidx>Foreign objects</nidx>
974 This module provides the @ForeignObj@ type and wrappers around the
975 primitive operations on foreign objects.
978 data ForeignObj = ForeignObj ForeignObj#
981 :: Addr -- object to be boxed up as a ForeignObj
986 :: ForeignObj -- previously created foreign object
991 <ncdx>ForeignObj</ncdx>
992 <ncdx>makeForeignObj</ncdx>
993 <ncdx>writeForeignObj</ncdx>
995 A typical use of @ForeignObj@ is in constructing Haskell bindings
996 to external libraries. A good example is that of writing a binding to
997 an image-processing library (which was actually the main motivation
998 for implementing @ForeignObj@'s precursor, @MallocPtr#@). The
999 images manipulated are not stored in the Haskell heap, either because
1000 the library insist on allocating them internally or we (sensibly)
1001 decide to spare the GC from having to heave heavy images around.
1004 data Image = Image ForeignObj
1007 The @ForeignObj@ type is then used to refer to the externally
1008 allocated image, and to acheive some type safety, the Haskell binding
1009 defines the @Image@ data type. So, a value of type @ForeignObj@ is
1010 used to ``box'' up an external reference into a Haskell heap object
1011 that we can then indirectly reference:
1014 createImage :: (Int,Int) -> IO Image
1017 So far, this looks just like an @Addr@ type, but @ForeignObj@ offers a
1018 bit more, namely that we can specify a <em>finalisation routine</em> to
1019 invoke when the @ForeignObj@ is discarded by the GC. The garbage
1020 collector invokes the finalisation routine associated with the
1021 @ForeignObj@, saying `` Thanks, I'm through with this now..'' For the
1022 image-processing library, the finalisation routine could for the
1023 images free up memory allocated for them. The finalisation routine has
1024 currently to be written in C (the finalisation routine can in turn
1025 call on @FreeStablePtr@ to deallocate a stable pointer).
1027 Associating a finalisation routine with an external object is done by
1028 calling @makeForeignObj@. {\bf Note:} the foreign object value and
1029 its finaliser are contained in the @ForeignObj@, so there's no danger
1030 of an aggressive optimiser somehow separating the two (with the result
1031 that the foreign reference would not be freed).
1033 (Implementation: a linked list of all @ForeignObj#@s is maintained to
1034 allow the garbage collector to detect when a @ForeignObj#@ becomes
1037 Like @Array@, @ForeignObj#@s are represented by heap objects.
1039 Upon controlled termination of the Haskell program, all @ForeignObjs@
1040 are freed, invoking their respective finalisers before terminating.
1042 <sect2>The @CCall@ module
1045 The @CCall@ module defines the classes @CCallable@ and @CReturnable@,
1046 along with instances for the primitive types (@Int@, @Int#@, @Float@,
1047 @Float#@ etc.) GHC knows to import this module if you use @_ccall_@,
1048 but if you need to define your own instances of these classes, you
1049 will need to import @CCall@ explicitly.
1051 More information on how to use @_ccall_@ can be found in Section
1052 <ref name="Calling~C directly from Haskell" id="glasgow-ccalls">.