2 % $Id: libraries.vsgml,v 1.4 1999/02/02 14:14:12 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 Integral
51 GHC also internally uses a number of modules that begin with the
52 string @Prel@<nidx>Prel module prefix</nidx>: for this reason, we
53 don't recommend that you use any module names beginning with @Prel@ in
54 your own programs. The @Prel@ modules are always available: in fact,
55 you can get access to several extensions this way (for some you might
56 need to give the @-fglasgow-exts@<nidx>-fglasgow-exts option</nidx>
60 <sect1>GHC/Hugs Extension Libraries
63 The extension libraries provided by both GHC and Hugs are described in
65 <htmlurl name="GHC/Hugs Extension Library Document" url="http://www.dcs.gla.ac.uk/fp/software/ghc/hg-libs/hg-libs.html">
67 <sect1>GHC-only Extension Libraries
69 <nidx>libraries, ghc-only</nidx>
70 <nidx>extension libraries, ghc-only</nidx>
72 If you rely on the implicit @import Prelude@ that GHC normally does
73 for you, and if you don't use any weird flags (notably
74 @-fglasgow-exts@), and if you don't import the Glasgow extensions
75 interface, @GlaExts@, then GHC should work <em>exactly</em> as the
76 Haskell report says (modulo a few minor issues, see Section <ref
77 id="vs-Haskell-defn" name="Language Non-compliance">).
79 If you turn on @-fglasgow-exts@, a new world opesn up to you and the compiler
80 will recognise and parse unboxed values properly, and provide access to the
81 various interfaces libraries described here (and piles of other goodies.)
86 <sect2>The @CCall@ module
89 The @CCall@ module defines the classes @CCallable@ and @CReturnable@,
90 along with instances for the primitive types (@Int@, @Int#@, @Float@,
91 @Float#@ etc.) GHC knows to import this module if you use @_ccall_@,
92 but if you need to define your own instances of these classes, you
93 will need to import @CCall@ explicitly.
95 More information on how to use @_ccall_@ can be found in Section
96 <ref name="Calling~C directly from Haskell" id="glasgow-ccalls">.
98 <sect2>The @GlaExts@ interface
100 <nidx>GlaExts interface (GHC extensions)</nidx>
102 The @GlaExts@ interface provides access to extensions that only GHC
103 implements. These currently are: unboxed types, including the
104 representations of the primitive types (Int, Float, etc.), and the
105 GHC primitive operations (@+#@, @==#@, etc.).
107 This module used to provide access to all the Glasgow extensions, but
108 these have since been moved into separate libraries for compatibility
109 with Hugs (version 2.09: in fact, you can still get at this stuff via
110 @GlaExts@ for compatibility, but this facility will likely be removed
114 -- the representation of some basic types:
119 data Float = F# Float#
120 data Double = D# Double#
121 data Integer = J# Int# Int# ByteArray#
123 module GHC -- all primops and primitive types.
126 <sect1>The module @PrelGHC@: really primitive stuff
127 <label id="ghc-libs-ghc">
129 <nidx>PrelGHC module</nidx>
131 This module defines all the types which are primitive in Glasgow
132 Haskell, and the operations provided for them.
134 A primitive type is one which cannot be defined in Haskell, and which
135 is therefore built into the language and compiler. Primitive types
136 are always unlifted; that is, a value of primitive type cannot be
137 bottom. We use the convention that primitive types, values, and
138 operations have a @#@ suffix.
140 Primitive values are often represented by a simple bit-pattern, such
141 as @Int#@, @Float#@, @Double#@. But this is not necessarily the case:
142 a primitive value might be represented by a pointer to a
143 heap-allocated object. Examples include @Array#@, the type of
144 primitive arrays. A primitive array is heap-allocated because it is
145 too big a value to fit in a register, and would be too expensive to
146 copy around; in a sense, it is accidental that it is represented by a
147 pointer. If a pointer represents a primitive value, then it really
148 does point to that value: no unevaluated thunks, no
149 indirections...nothing can be at the other end of the pointer than the
152 <sect2>Unboxed Tuples
153 <label id="unboxed-tuples">
156 Unboxed tuples aren't really exported by @PrelGHC@, they're available
157 by default with @-fglasgow-exts@. An unboxed tuple looks like this:
163 where @e_1..e_n@ are expressions of any type (primitive or
164 non-primitive). The type of an unboxed tuple looks the same.
166 Unboxed tuples are used for functions that need to return multiple
167 values, but they avoid the heap allocation normally associated with
168 using fully-fledged tuples. When an unboxed tuple is returned, the
169 components are put directly into registers or on the stack; the
170 unboxed tuple itself does not have a composite representation. Many
171 of the primitive operations listed in this section return unboxed
174 There are some pretty stringent restrictions on the use of unboxed tuples:
178 <item> Unboxed tuple types are subject to the same restrictions as
179 other unboxed types; i.e. they may not be stored in polymorphic data
180 structures or passed to polymorphic functions.
182 <item> Unboxed tuples may only be constructed as the direct result of
183 a function, and may only be deconstructed with a @case@ expression.
184 eg. the following are valid:
187 f x y = (# x+1, y-1 #)
188 g x = case f x x of { (# a, b #) -> a + b }
191 but the following are invalid:
198 <item> No variable can have an unboxed tuple type. This is illegal:
201 f :: (# Int, Int #) -> (# Int, Int #)
205 because @x@ has an unboxed tuple type.
209 Note: we may relax some of these restrictions in the future.
211 The @IO@ and @ST@ monads use unboxed tuples to avoid unnecessary
212 allocation during sequences of operations.
214 <sect2>Character and numeric types
216 <nidx>character types, primitive</nidx>
217 <nidx>numeric types, primitive</nidx>
218 <nidx>integer types, primitive</nidx>
219 <nidx>floating point types, primitive</nidx>
221 There are the following obvious primitive types:
225 type Int# -- see also Word# and Addr#, later
234 If you really want to know their exact equivalents in C, see
235 @ghc/includes/StgTypes.h@ in the GHC source tree.
237 Literals for these types may be written as follows:
243 'a'# a Char#; for weird characters, use '\o<octal>'#
244 "a"# an Addr# (a `char *')
246 <nidx>literals, primitive</nidx>
247 <nidx>constants, primitive</nidx>
248 <nidx>numbers, primitive</nidx>
250 <sect2> Comparison operations
252 <nidx>comparisons, primitive</nidx>
253 <nidx>operators, comparison</nidx>
256 {>,>=,==,/=,<,<=}# :: Int# -> Int# -> Bool
258 {gt,ge,eq,ne,lt,le}Char# :: Char# -> Char# -> Bool
259 -- ditto for Word# and Addr#
267 <ncdx>gt{Char,Word,Addr}#</ncdx>
268 <ncdx>ge{Char,Word,Addr}#</ncdx>
269 <ncdx>eq{Char,Word,Addr}#</ncdx>
270 <ncdx>ne{Char,Word,Addr}#</ncdx>
271 <ncdx>lt{Char,Word,Addr}#</ncdx>
272 <ncdx>le{Char,Word,Addr}#</ncdx>
274 <sect2> Primitive-character operations
276 <nidx>characters, primitive operations</nidx>
277 <nidx>operators, primitive character</nidx>
280 ord# :: Char# -> Int#
281 chr# :: Int# -> Char#
287 <sect2> Primitive-@Int@ operations
289 <nidx>integers, primitive operations</nidx>
290 <nidx>operators, primitive integer</nidx>
293 {+,-,*,quotInt,remInt}# :: Int# -> Int# -> Int#
294 negateInt# :: Int# -> Int#
296 iShiftL#, iShiftRA#, iShiftRL# :: Int# -> Int# -> Int#
297 -- shift left, right arithmetic, right logical
302 <ncdx>quotInt#</ncdx>
304 <ncdx>iShiftL#</ncdx>
305 <ncdx>iShiftRA#</ncdx>
306 <ncdx>iShiftRL#</ncdx>
307 <nidx>shift operations, integer</nidx>
309 <bf>Note:</bf> No error/overflow checking!
311 <sect2> Primitive-@Double@ and @Float@ operations
313 <nidx>floating point numbers, primitive</nidx>
314 <nidx>operators, primitive floating point</nidx>
317 {+,-,*,/}## :: Double# -> Double# -> Double#
318 {<,<=,==,/=,>=,>}## :: Double# -> Double# -> Bool
319 negateDouble# :: Double# -> Double#
320 double2Int# :: Double# -> Int#
321 int2Double# :: Int# -> Double#
323 {plus,minux,times,divide}Float# :: Float# -> Float# -> Float#
324 {gt,ge,eq,ne,lt,le}Float# :: Float# -> Float# -> Bool
325 negateFloat# :: Float# -> Float#
326 float2Int# :: Float# -> Int#
327 int2Float# :: Int# -> Float#
340 <ncdx>negateDouble#</ncdx>
341 <ncdx>double2Int#</ncdx>
342 <ncdx>int2Double#</ncdx>
344 <ncdx>plusFloat#</ncdx>
345 <ncdx>minusFloat#</ncdx>
346 <ncdx>timesFloat#</ncdx>
347 <ncdx>divideFloat#</ncdx>
348 <ncdx>gtFloat#</ncdx>
349 <ncdx>geFloat#</ncdx>
350 <ncdx>eqFloat#</ncdx>
351 <ncdx>neFloat#</ncdx>
352 <ncdx>ltFloat#</ncdx>
353 <ncdx>leFloat#</ncdx>
354 <ncdx>negateFloat#</ncdx>
355 <ncdx>float2Int#</ncdx>
356 <ncdx>int2Float#</ncdx>
358 And a full complement of trigonometric functions:
361 expDouble# :: Double# -> Double#
362 logDouble# :: Double# -> Double#
363 sqrtDouble# :: Double# -> Double#
364 sinDouble# :: Double# -> Double#
365 cosDouble# :: Double# -> Double#
366 tanDouble# :: Double# -> Double#
367 asinDouble# :: Double# -> Double#
368 acosDouble# :: Double# -> Double#
369 atanDouble# :: Double# -> Double#
370 sinhDouble# :: Double# -> Double#
371 coshDouble# :: Double# -> Double#
372 tanhDouble# :: Double# -> Double#
373 powerDouble# :: Double# -> Double# -> Double#
375 <nidx>trigonometric functions, primitive</nidx>
377 similarly for @Float#@.
379 There are two coercion functions for @Float#@/@Double#@:
382 float2Double# :: Float# -> Double#
383 double2Float# :: Double# -> Float#
385 <ncdx>float2Double#</ncdx>
386 <ncdx>double2Float#</ncdx>
388 The primitive versions of @encodeDouble@/@decodeDouble@:
391 encodeDouble# :: Int# -> Int# -> ByteArray# -- Integer mantissa
392 -> Int# -- Int exponent
395 decodeDouble# :: Double# -> PrelNum.ReturnIntAndGMP
397 <ncdx>encodeDouble#</ncdx>
398 <ncdx>decodeDouble#</ncdx>
400 (And the same for @Float#@s.)
402 <sect2>Operations on/for @Integers@ (interface to GMP)
403 <label id="integer-operations">
405 <nidx>arbitrary precision integers</nidx>
406 <nidx>Integer, operations on</nidx>
408 We implement @Integers@ (arbitrary-precision integers) using the GNU
409 multiple-precision (GMP) package (version 2.0.2).
411 The data type for @Integer@ must mirror that for @MP_INT@ in @gmp.h@
412 (see @gmp.info@ in @ghc/includes/runtime/gmp@). It comes out as:
415 data Integer = J# Int# Int# ByteArray#
417 <nidx>Integer type</nidx>
419 So, @Integer@ is really just a ``pairing'' type for a particular
420 collection of primitive types.
422 The primitive ops to support @Integers@ use the ``pieces'' of the
423 representation, and are as follows:
426 negateInteger# :: Int# -> Int# -> ByteArray# -> Integer
428 {plus,minus,times}Integer# :: Int# -> Int# -> ByteArray#
429 -> Int# -> Int# -> ByteArray#
432 cmpInteger# :: Int# -> Int# -> ByteArray#
433 -> Int# -> Int# -> ByteArray#
434 -> Int# -- -1 for <; 0 for ==; +1 for >
436 divModInteger#, quotRemInteger#
437 :: Int# -> Int# -> ByteArray#
438 -> Int# -> Int# -> ByteArray#
439 -> PrelNum.Return2GMPs
441 integer2Int# :: Int# -> Int# -> ByteArray# -> Int#
443 int2Integer# :: Int# -> Integer -- NB: no error-checking on these two!
444 word2Integer# :: Word# -> Integer
446 addr2Integer# :: Addr# -> Integer
447 -- the Addr# is taken to be a `char *' string
448 -- to be converted into an Integer.
450 <ncdx>negateInteger#</ncdx>
451 <ncdx>plusInteger#</ncdx>
452 <ncdx>minusInteger#</ncdx>
453 <ncdx>timesInteger#</ncdx>
454 <ncdx>cmpInteger#</ncdx>
455 <ncdx>divModInteger#</ncdx>
456 <ncdx>quotRemInteger#</ncdx>
457 <ncdx>integer2Int#</ncdx>
458 <ncdx>int2Integer#</ncdx>
459 <ncdx>word2Integer#</ncdx>
460 <ncdx>addr2Integer#</ncdx>
462 <sect2>Words and addresses
464 <nidx>word, primitive type</nidx>
465 <nidx>address, primitive type</nidx>
466 <nidx>unsigned integer, primitive type</nidx>
467 <nidx>pointer, primitive type</nidx>
469 A @Word#@ is used for bit-twiddling operations. It is the same size as
470 an @Int#@, but has no sign nor any arithmetic operations.
472 type Word# -- Same size/etc as Int# but *unsigned*
473 type Addr# -- A pointer from outside the "Haskell world" (from C, probably);
474 -- described under "arrays"
480 @Word#@s and @Addr#@s have the usual comparison operations.
481 Other unboxed-@Word@ ops (bit-twiddling and coercions):
484 and#, or#, xor# :: Word# -> Word# -> Word#
487 quotWord#, remWord# :: Word# -> Word# -> Word#
488 -- word (i.e. unsigned) versions are different from int
489 -- versions, so we have to provide these explicitly.
491 not# :: Word# -> Word#
493 shiftL#, shiftRA#, shiftRL# :: Word# -> Int# -> Word#
494 -- shift left, right arithmetic, right logical
496 int2Word# :: Int# -> Word# -- just a cast, really
497 word2Int# :: Word# -> Int#
499 <nidx>bit operations, Word and Addr</nidx>
504 <ncdx>quotWord#</ncdx>
505 <ncdx>remWord#</ncdx>
507 <ncdx>shiftRA#</ncdx>
508 <ncdx>shiftRL#</ncdx>
509 <ncdx>int2Word#</ncdx>
510 <ncdx>word2Int#</ncdx>
512 Unboxed-@Addr@ ops (C casts, really):
514 int2Addr# :: Int# -> Addr#
515 addr2Int# :: Addr# -> Int#
517 <ncdx>int2Addr#</ncdx>
518 <ncdx>addr2Int#</ncdx>
520 The casts between @Int#@, @Word#@ and @Addr#@ correspond to null
521 operations at the machine level, but are required to keep the Haskell
524 Operations for indexing off of C pointers (@Addr#@s) to snatch values
525 are listed under ``arrays''.
529 <nidx>arrays, primitive</nidx>
531 The type @Array# elt@ is the type of primitive, unpointed arrays of
532 values of type @elt@.
539 @Array#@ is more primitive than a Haskell array --- indeed, the
540 Haskell @Array@ interface is implemented using @Array#@ --- in that an
541 @Array#@ is indexed only by @Int#@s, starting at zero. It is also
542 more primitive by virtue of being unboxed. That doesn't mean that it
543 isn't a heap-allocated object - of course, it is. Rather, being
544 unboxed means that it is represented by a pointer to the array itself,
545 and not to a thunk which will evaluate to the array (or to bottom).
546 The components of an @Array#@ are themselves boxed.
548 The type @ByteArray#@ is similar to @Array#@, except that it contains
549 just a string of (non-pointer) bytes.
554 <ncdx>ByteArray#</ncdx>
556 Arrays of these types are useful when a Haskell program wishes to
557 construct a value to pass to a C procedure. It is also possible to
558 use them to build (say) arrays of unboxed characters for internal use
559 in a Haskell program. Given these uses, @ByteArray#@ is deliberately
560 a bit vague about the type of its components. Operations are provided
561 to extract values of type @Char#@, @Int#@, @Float#@, @Double#@, and
562 @Addr#@ from arbitrary offsets within a @ByteArray#@. (For type
563 @Foo#@, the $i$th offset gets you the $i$th @Foo#@, not the @Foo#@ at
564 byte-position $i$. Mumble.) (If you want a @Word#@, grab an @Int#@,
567 Lastly, we have static byte-arrays, of type @Addr#@ [mentioned
568 previously]. (Remember the duality between arrays and pointers in C.)
569 Arrays of this types are represented by a pointer to an array in the
570 world outside Haskell, so this pointer is not followed by the garbage
571 collector. In other respects they are just like @ByteArray#@. They
572 are only needed in order to pass values from C to Haskell.
574 <sect2>Reading and writing
577 Primitive arrays are linear, and indexed starting at zero.
579 The size and indices of a @ByteArray#@, @Addr#@, and
580 @MutableByteArray#@ are all in bytes. It's up to the program to
581 calculate the correct byte offset from the start of the array. This
582 allows a @ByteArray#@ to contain a mixture of values of different
583 type, which is often needed when preparing data for and unpicking
584 results from C. (Umm... not true of indices... WDP 95/09)
586 <em>Should we provide some @sizeOfDouble#@ constants?</em>
588 Out-of-range errors on indexing should be caught by the code which
589 uses the primitive operation; the primitive operations themselves do
590 <em>not</em> check for out-of-range indexes. The intention is that the
591 primitive ops compile to one machine instruction or thereabouts.
593 We use the terms ``reading'' and ``writing'' to refer to accessing
594 <em>mutable</em> arrays (see Section~<ref name="Mutable arrays" id="sect:mutable">), and
595 ``indexing'' to refer to reading a value from an <em>immutable</em>
598 Immutable byte arrays are straightforward to index (all indices in bytes):
600 indexCharArray# :: ByteArray# -> Int# -> Char#
601 indexIntArray# :: ByteArray# -> Int# -> Int#
602 indexAddrArray# :: ByteArray# -> Int# -> Addr#
603 indexFloatArray# :: ByteArray# -> Int# -> Float#
604 indexDoubleArray# :: ByteArray# -> Int# -> Double#
606 indexCharOffAddr# :: Addr# -> Int# -> Char#
607 indexIntOffAddr# :: Addr# -> Int# -> Int#
608 indexFloatOffAddr# :: Addr# -> Int# -> Float#
609 indexDoubleOffAddr# :: Addr# -> Int# -> Double#
610 indexAddrOffAddr# :: Addr# -> Int# -> Addr#
611 -- Get an Addr# from an Addr# offset
613 <ncdx>indexCharArray#</ncdx>
614 <ncdx>indexIntArray#</ncdx>
615 <ncdx>indexAddrArray#</ncdx>
616 <ncdx>indexFloatArray#</ncdx>
617 <ncdx>indexDoubleArray#</ncdx>
618 <ncdx>indexCharOffAddr#</ncdx>
619 <ncdx>indexIntOffAddr#</ncdx>
620 <ncdx>indexFloatOffAddr#</ncdx>
621 <ncdx>indexDoubleOffAddr#</ncdx>
622 <ncdx>indexAddrOffAddr#</ncdx>
624 The last of these, @indexAddrOffAddr#@, extracts an @Addr#@ using an offset
625 from another @Addr#@, thereby providing the ability to follow a chain of
628 Something a bit more interesting goes on when indexing arrays of boxed
629 objects, because the result is simply the boxed object. So presumably
630 it should be entered --- we never usually return an unevaluated
631 object! This is a pain: primitive ops aren't supposed to do
632 complicated things like enter objects. The current solution is to
633 return a single element unboxed tuple (see Section <ref name="Unboxed
634 Tuples" id="unboxed-tuples">).
637 indexArray# :: Array# elt -> Int# -> (# elt #)
639 <ncdx>indexArray#</ncdx>
642 <sect2>The state type
644 <ncdx>state, primitive type</ncdx>
647 The primitive type @State#@ represents the state of a state
648 transformer. It is parameterised on the desired type of state, which
649 serves to keep states from distinct threads distinct from one another.
650 But the <em>only</em> effect of this parameterisation is in the type
651 system: all values of type @State#@ are represented in the same way.
652 Indeed, they are all represented by nothing at all! The code
653 generator ``knows'' to generate no code, and allocate no registers
654 etc, for primitive states.
660 The type @GHC.RealWorld@ is truly opaque: there are no values defined
661 of this type, and no operations over it. It is ``primitive'' in that
662 sense - but it is <em>not unlifted!</em> Its only role in life is to be
663 the type which distinguishes the @IO@ state transformer.
669 <sect2>State of the world
672 A single, primitive, value of type @State# RealWorld@ is provided.
675 realWorld# :: State# RealWorld
677 <nidx>realWorld# state object</nidx>
679 (Note: in the compiler, not a @PrimOp@; just a mucho magic
680 @Id@. Exported from @GHC@, though).
682 <sect2>Mutable arrays
684 <label id="sect:mutable">
685 <nidx>mutable arrays</nidx>
686 <nidx>arrays, mutable</nidx>
688 Corresponding to @Array#@ and @ByteArray#@, we have the types of
689 mutable versions of each. In each case, the representation is a
690 pointer to a suitable block of (mutable) heap-allocated storage.
693 type MutableArray# s elt
694 type MutableByteArray# s
696 <ncdx>MutableArray#</ncdx>
697 <ncdx>MutableByteArray#</ncdx>
701 <nidx>mutable arrays, allocation</nidx>
702 <nidx>arrays, allocation</nidx>
703 <nidx>allocation, of mutable arrays</nidx>
705 Mutable arrays can be allocated. Only pointer-arrays are initialised;
706 arrays of non-pointers are filled in by ``user code'' rather than by
707 the array-allocation primitive. Reason: only the pointer case has to
708 worry about GC striking with a partly-initialised array.
711 newArray# :: Int# -> elt -> State# s -> (# State# s, MutableArray# s elt #)
713 newCharArray# :: Int# -> State# s -> (# State# s, MutableByteArray# s elt #)
714 newIntArray# :: Int# -> State# s -> (# State# s, MutableByteArray# s elt #)
715 newAddrArray# :: Int# -> State# s -> (# State# s, MutableByteArray# s elt #)
716 newFloatArray# :: Int# -> State# s -> (# State# s, MutableByteArray# s elt #)
717 newDoubleArray# :: Int# -> State# s -> (# State# s, MutableByteArray# s elt #)
719 <ncdx>newArray#</ncdx>
720 <ncdx>newCharArray#</ncdx>
721 <ncdx>newIntArray#</ncdx>
722 <ncdx>newAddrArray#</ncdx>
723 <ncdx>newFloatArray#</ncdx>
724 <ncdx>newDoubleArray#</ncdx>
726 The size of a @ByteArray#@ is given in bytes.
728 <sect3>Reading and writing
730 <nidx>arrays, reading and writing</nidx>
733 readArray# :: MutableArray# s elt -> Int# -> State# s -> (# State# s, elt #)
734 readCharArray# :: MutableByteArray# s -> Int# -> State# s -> (# State# s, Char# #)
735 readIntArray# :: MutableByteArray# s -> Int# -> State# s -> (# State# s, Int# #)
736 readAddrArray# :: MutableByteArray# s -> Int# -> State# s -> (# State# s, Addr# #)
737 readFloatArray# :: MutableByteArray# s -> Int# -> State# s -> (# State# s, Float# #)
738 readDoubleArray# :: MutableByteArray# s -> Int# -> State# s -> (# State# s, Double# #)
740 writeArray# :: MutableArray# s elt -> Int# -> elt -> State# s -> State# s
741 writeCharArray# :: MutableByteArray# s -> Int# -> Char# -> State# s -> State# s
742 writeIntArray# :: MutableByteArray# s -> Int# -> Int# -> State# s -> State# s
743 writeAddrArray# :: MutableByteArray# s -> Int# -> Addr# -> State# s -> State# s
744 writeFloatArray# :: MutableByteArray# s -> Int# -> Float# -> State# s -> State# s
745 writeDoubleArray# :: MutableByteArray# s -> Int# -> Double# -> State# s -> State# s
747 <ncdx>readArray#</ncdx>
748 <ncdx>readCharArray#</ncdx>
749 <ncdx>readIntArray#</ncdx>
750 <ncdx>readAddrArray#</ncdx>
751 <ncdx>readFloatArray#</ncdx>
752 <ncdx>readDoubleArray#</ncdx>
753 <ncdx>writeArray#</ncdx>
754 <ncdx>writeCharArray#</ncdx>
755 <ncdx>writeIntArray#</ncdx>
756 <ncdx>writeAddrArray#</ncdx>
757 <ncdx>writeFloatArray#</ncdx>
758 <ncdx>writeDoubleArray#</ncdx>
763 <nidx>arrays, testing for equality</nidx>
765 One can take ``equality'' of mutable arrays. What is compared is the
766 <em>name</em> or reference to the mutable array, not its contents.
769 sameMutableArray# :: MutableArray# s elt -> MutableArray# s elt -> Bool
770 sameMutableByteArray# :: MutableByteArray# s -> MutableByteArray# s -> Bool
772 <ncdx>sameMutableArray#</ncdx>
773 <ncdx>sameMutableByteArray#</ncdx>
775 <sect3>Freezing mutable arrays
777 <nidx>arrays, freezing mutable</nidx>
778 <nidx>freezing mutable arrays</nidx>
779 <nidx>mutable arrays, freezing</nidx>
781 Only unsafe-freeze has a primitive. (Safe freeze is done directly in Haskell
782 by copying the array and then using @unsafeFreeze@.)
785 unsafeFreezeArray# :: MutableArray# s elt -> State# s -> (# State# s, Array# s elt #)
786 unsafeFreezeByteArray# :: MutableByteArray# s -> State# s -> (# State# s, ByteArray# #)
788 <ncdx>unsafeFreezeArray#</ncdx>
789 <ncdx>unsafeFreezeByteArray#</ncdx>
791 <sect2>Stable pointers
793 <nidx>stable pointers</nidx>
794 <nidx>pointers, stable</nidx>
796 A stable pointer is a name for a Haskell object which can be passed to
797 the external world. It is ``stable'' in the sense that the name does
798 not change when the Haskell garbage collector runs --- in contrast to
799 the address of the object which may well change.
801 The stable pointer type is parameterised by the type of the thing
807 <ncdx>StablePtr#</ncdx>
809 A stable pointer is represented by an index into the (static)
810 @StablePointerTable@. The Haskell garbage collector treats the
811 @StablePointerTable@ as a source of roots for GC.
813 The @makeStablePointer@ function converts a value into a stable
814 pointer. It is part of the @IO@ monad, because we want to be sure
815 we don't allocate one twice by accident, and then only free one of the
819 makeStablePointer# :: a -> State# RealWorld -> (# State# RealWord, StablePtr# a #)
820 freeStablePointer# :: StablePtr# a -> State# RealWorld -> State# RealWorld
821 deRefStablePointer# :: StablePtr# a -> State# RealWorld -> (# State# RealWorld, a #)
823 <ncdx>makeStablePointer#</ncdx>
824 <ncdx>freeStablePointer#</ncdx>
825 <ncdx>deRefStablePointer#</ncdx>
827 There is also a C procedure @FreeStablePtr@ which frees a stable pointer.
829 %<em>Andy's comment.</em> {\bf Errors:} The following is not strictly true: the current
830 %implementation is not as polymorphic as claimed. The reason for this
831 %is that the C programmer will have to use a different entry-routine
832 %for each type of stable pointer. At present, we only supply a very
833 %limited number (3) of these routines. It might be possible to
834 %increase the range of these routines by providing general purpose
835 %entry points to apply stable pointers to (stable pointers to)
836 %arguments and to enter (stable pointers to) boxed primitive values.
837 %<em>End of Andy's comment.</em>
839 <sect2>Foreign objects
841 <nidx>Foreign objects</nidx>
843 A @ForeignObj#@ is a reference to an object outside the Haskell world
844 (i.e., from the C world, or a reference to an object on another
845 machine completely.), where the Haskell world has been told ``Let me
846 know when you're finished with this ...''.
851 <ncdx>ForeignObj#</ncdx>
853 GHC provides two primitives on @ForeignObj#@:
857 :: Addr# -- foreign reference
858 -> Addr# -- pointer to finalisation routine
859 -> (# State# RealWorld, ForeignObj# )
861 :: ForeignObj# -- foreign object
866 <ncdx>makeForeignObj#</ncdx>
867 <ncdx>writeForeignObj#</ncdx>
869 The module @Foreign@ (Section <ref name="Foreign objects"
870 id="sec:foreign-obj">) provides a more programmer-friendly interface
873 <sect2>Synchronizing variables (M-vars)
875 <nidx>synchronising variables (M-vars)</nidx>
878 Synchronising variables are the primitive type used to implement
879 Concurrent Haskell's MVars (see the Concurrent Haskell paper for
880 the operational behaviour of these operations).
883 type MVar# s elt -- primitive
885 newMVar# :: State# s -> (# State# s, MVar# s elt #)
886 takeMVar# :: SynchVar# s elt -> State# s -> (# State# s, elt #)
887 putMVar# :: SynchVar# s elt -> State# s -> State# s
889 <ncdx>SynchVar#</ncdx>
890 <ncdx>newSynchVar#</ncdx>
891 <ncdx>takeMVar</ncdx>