1 <Chapter id="ghc-prelude">
2 <Title>The GHC prelude and libraries
6 This document describes GHC's prelude and libraries. The basic story is that of the Haskell 1.4 Report and Libraries document (which we do not reproduce here), but this document describes in addition:
15 GHC's additional non-standard libraries and types, such as state
16 transformers, packed strings, foreign objects, stable pointers, and so on.
22 GHC's primitive types and operations. The standard Haskell functions are
23 implemented on top of these, and it is sometimes useful to use them
30 The organisation of these libraries into directories.
36 Short description of programmer interface to the non-standard
37 libraries provided in addition to the standard prelude.
45 A number of the libraries that provide access to GHC's language
46 extensions are shared by Hugs, and are described in the <ULink
47 URL="libs.html">GHC/Hugs Extension Libraries</ULink> document.
50 <Sect1 id="ghc-prelude-exts">
51 <Title>Prelude extensions
55 GHC's prelude contains the following non-standard extensions:
62 <Term><Function>fromInt</Function> method in class <Literal>Num</Literal>:</Term>
65 It's there. Converts from
66 an <Literal>Int</Literal> to the type.
71 <Term><Function>toInt</Function> method in class <Literal>Integral</Literal>:</Term>
74 Converts from Integral
75 type to an <Literal>Int</Literal>.
83 GHC also internally uses a number of modules that begin with the
84 string <Literal>Prel</Literal><IndexTerm><Primary>Prel module prefix</Primary></IndexTerm>: for this reason, we
85 don't recommend that you use any module names beginning with <Literal>Prel</Literal> in
86 your own programs. The <Literal>Prel</Literal> modules are always available: in fact,
87 you can get access to several extensions this way (for some you might
88 need to give the <Option>-fglasgow-exts</Option><IndexTerm><Primary>-fglasgow-exts option</Primary></IndexTerm>
96 <Title>GHC-only Extension Libraries</Title>
99 <IndexTerm><Primary>libraries, ghc-only</Primary></IndexTerm>
100 <IndexTerm><Primary>extension libraries, ghc-only</Primary></IndexTerm>
104 If you rely on the implicit <Literal>import Prelude</Literal> that GHC normally does
105 for you, and if you don't use any weird flags (notably
106 <Option>-fglasgow-exts</Option>), and if you don't import the Glasgow extensions
107 interface, <Literal>GlaExts</Literal>, then GHC should work <Emphasis>exactly</Emphasis> as the
108 Haskell report says (modulo a few minor issues, see <XRef LinkEnd="vs-Haskell-defn">).
112 If you turn on <Option>-fglasgow-exts</Option>, a new world opens up to you and the compiler
113 will recognise and parse unboxed values properly, and provide access to the
114 various interfaces libraries described here (and piles of other goodies.)
119 <Sect1 id="ghc-libs-ghc">
120 <Title>The module <Literal>PrelGHC</Literal>: really primitive stuff
124 <IndexTerm><Primary>PrelGHC module</Primary></IndexTerm>
128 This module defines all the types which are primitive in Glasgow
129 Haskell, and the operations provided for them.
133 A primitive type is one which cannot be defined in Haskell, and which
134 is therefore built into the language and compiler. Primitive types
135 are always unlifted; that is, a value of primitive type cannot be
136 bottom. We use the convention that primitive types, values, and
137 operations have a <Literal>#</Literal> suffix.
141 Primitive values are often represented by a simple bit-pattern, such
142 as <Literal>Int#</Literal>, <Literal>Float#</Literal>, <Literal>Double#</Literal>. But this is not necessarily the case:
143 a primitive value might be represented by a pointer to a
144 heap-allocated object. Examples include <Literal>Array#</Literal>, the type of
145 primitive arrays. A primitive array is heap-allocated because it is
146 too big a value to fit in a register, and would be too expensive to
147 copy around; in a sense, it is accidental that it is represented by a
148 pointer. If a pointer represents a primitive value, then it really
149 does point to that value: no unevaluated thunks, no
150 indirections…nothing can be at the other end of the pointer than the
154 <Sect2 id="unboxed-tuples">
155 <Title>Unboxed Tuples
159 Unboxed tuples aren't really exported by <Literal>PrelGHC</Literal>, they're available
160 by default with <Option>-fglasgow-exts</Option>. An unboxed tuple looks like this:
172 where <Literal>e_1..e_n</Literal> are expressions of any type (primitive or
173 non-primitive). The type of an unboxed tuple looks the same.
177 Unboxed tuples are used for functions that need to return multiple
178 values, but they avoid the heap allocation normally associated with
179 using fully-fledged tuples. When an unboxed tuple is returned, the
180 components are put directly into registers or on the stack; the
181 unboxed tuple itself does not have a composite representation. Many
182 of the primitive operations listed in this section return unboxed
187 There are some pretty stringent restrictions on the use of unboxed tuples:
196 Unboxed tuple types are subject to the same restrictions as
197 other unboxed types; i.e. they may not be stored in polymorphic data
198 structures or passed to polymorphic functions.
205 Unboxed tuples may only be constructed as the direct result of
206 a function, and may only be deconstructed with a <Literal>case</Literal> expression.
207 eg. the following are valid:
211 f x y = (# x+1, y-1 #)
212 g x = case f x x of { (# a, b #) -> a + b }
216 but the following are invalid:
230 No variable can have an unboxed tuple type. This is illegal:
234 f :: (# Int, Int #) -> (# Int, Int #)
239 because <VarName>x</VarName> has an unboxed tuple type.
249 Note: we may relax some of these restrictions in the future.
253 The <Literal>IO</Literal> and <Literal>ST</Literal> monads use unboxed tuples to avoid unnecessary
254 allocation during sequences of operations.
260 <Title>Character and numeric types</Title>
263 <IndexTerm><Primary>character types, primitive</Primary></IndexTerm>
264 <IndexTerm><Primary>numeric types, primitive</Primary></IndexTerm>
265 <IndexTerm><Primary>integer types, primitive</Primary></IndexTerm>
266 <IndexTerm><Primary>floating point types, primitive</Primary></IndexTerm>
267 There are the following obvious primitive types:
274 type Int# -- see also Word# and Addr#, later
279 <IndexTerm><Primary><literal>Char#</literal></Primary></IndexTerm>
280 <IndexTerm><Primary><literal>Int#</literal></Primary></IndexTerm>
281 <IndexTerm><Primary><literal>Float#</literal></Primary></IndexTerm>
282 <IndexTerm><Primary><literal>Double#</literal></Primary></IndexTerm>
286 If you really want to know their exact equivalents in C, see
287 <Filename>ghc/includes/StgTypes.h</Filename> in the GHC source tree.
291 Literals for these types may be written as follows:
300 'a'# a Char#; for weird characters, use '\o<octal>'#
301 "a"# an Addr# (a `char *')
304 <IndexTerm><Primary>literals, primitive</Primary></IndexTerm>
305 <IndexTerm><Primary>constants, primitive</Primary></IndexTerm>
306 <IndexTerm><Primary>numbers, primitive</Primary></IndexTerm>
312 <Title>Comparison operations</Title>
315 <IndexTerm><Primary>comparisons, primitive</Primary></IndexTerm>
316 <IndexTerm><Primary>operators, comparison</Primary></IndexTerm>
322 {>,>=,==,/=,<,<=}# :: Int# -> Int# -> Bool
324 {gt,ge,eq,ne,lt,le}Char# :: Char# -> Char# -> Bool
325 -- ditto for Word# and Addr#
328 <IndexTerm><Primary><literal>>#</literal></Primary></IndexTerm>
329 <IndexTerm><Primary><literal>>=#</literal></Primary></IndexTerm>
330 <IndexTerm><Primary><literal>==#</literal></Primary></IndexTerm>
331 <IndexTerm><Primary><literal>/=#</literal></Primary></IndexTerm>
332 <IndexTerm><Primary><literal><#</literal></Primary></IndexTerm>
333 <IndexTerm><Primary><literal><=#</literal></Primary></IndexTerm>
334 <IndexTerm><Primary><literal>gt{Char,Word,Addr}#</literal></Primary></IndexTerm>
335 <IndexTerm><Primary><literal>ge{Char,Word,Addr}#</literal></Primary></IndexTerm>
336 <IndexTerm><Primary><literal>eq{Char,Word,Addr}#</literal></Primary></IndexTerm>
337 <IndexTerm><Primary><literal>ne{Char,Word,Addr}#</literal></Primary></IndexTerm>
338 <IndexTerm><Primary><literal>lt{Char,Word,Addr}#</literal></Primary></IndexTerm>
339 <IndexTerm><Primary><literal>le{Char,Word,Addr}#</literal></Primary></IndexTerm>
345 <Title>Primitive-character operations</Title>
348 <IndexTerm><Primary>characters, primitive operations</Primary></IndexTerm>
349 <IndexTerm><Primary>operators, primitive character</Primary></IndexTerm>
355 ord# :: Char# -> Int#
356 chr# :: Int# -> Char#
359 <IndexTerm><Primary><literal>ord#</literal></Primary></IndexTerm>
360 <IndexTerm><Primary><literal>chr#</literal></Primary></IndexTerm>
366 <Title>Primitive-<Literal>Int</Literal> operations</Title>
369 <IndexTerm><Primary>integers, primitive operations</Primary></IndexTerm>
370 <IndexTerm><Primary>operators, primitive integer</Primary></IndexTerm>
376 {+,-,*,quotInt,remInt}# :: Int# -> Int# -> Int#
377 negateInt# :: Int# -> Int#
379 iShiftL#, iShiftRA#, iShiftRL# :: Int# -> Int# -> Int#
380 -- shift left, right arithmetic, right logical
383 <IndexTerm><Primary><literal>+#</literal></Primary></IndexTerm>
384 <IndexTerm><Primary><literal>-#</literal></Primary></IndexTerm>
385 <IndexTerm><Primary><literal>*#</literal></Primary></IndexTerm>
386 <IndexTerm><Primary><literal>quotInt#</literal></Primary></IndexTerm>
387 <IndexTerm><Primary><literal>remInt#</literal></Primary></IndexTerm>
388 <IndexTerm><Primary><literal>iShiftL#</literal></Primary></IndexTerm>
389 <IndexTerm><Primary><literal>iShiftRA#</literal></Primary></IndexTerm>
390 <IndexTerm><Primary><literal>iShiftRL#</literal></Primary></IndexTerm>
391 <IndexTerm><Primary>shift operations, integer</Primary></IndexTerm>
395 <Emphasis>Note:</Emphasis> No error/overflow checking!
401 <Title>Primitive-<Literal>Double</Literal> and <Literal>Float</Literal> operations</Title>
404 <IndexTerm><Primary>floating point numbers, primitive</Primary></IndexTerm>
405 <IndexTerm><Primary>operators, primitive floating point</Primary></IndexTerm>
411 {+,-,*,/}## :: Double# -> Double# -> Double#
412 {<,<=,==,/=,>=,>}## :: Double# -> Double# -> Bool
413 negateDouble# :: Double# -> Double#
414 double2Int# :: Double# -> Int#
415 int2Double# :: Int# -> Double#
417 {plus,minux,times,divide}Float# :: Float# -> Float# -> Float#
418 {gt,ge,eq,ne,lt,le}Float# :: Float# -> Float# -> Bool
419 negateFloat# :: Float# -> Float#
420 float2Int# :: Float# -> Int#
421 int2Float# :: Int# -> Float#
427 <IndexTerm><Primary><literal>+##</literal></Primary></IndexTerm>
428 <IndexTerm><Primary><literal>-##</literal></Primary></IndexTerm>
429 <IndexTerm><Primary><literal>*##</literal></Primary></IndexTerm>
430 <IndexTerm><Primary><literal>/##</literal></Primary></IndexTerm>
431 <IndexTerm><Primary><literal><##</literal></Primary></IndexTerm>
432 <IndexTerm><Primary><literal><=##</literal></Primary></IndexTerm>
433 <IndexTerm><Primary><literal>==##</literal></Primary></IndexTerm>
434 <IndexTerm><Primary><literal>=/##</literal></Primary></IndexTerm>
435 <IndexTerm><Primary><literal>>=##</literal></Primary></IndexTerm>
436 <IndexTerm><Primary><literal>>##</literal></Primary></IndexTerm>
437 <IndexTerm><Primary><literal>negateDouble#</literal></Primary></IndexTerm>
438 <IndexTerm><Primary><literal>double2Int#</literal></Primary></IndexTerm>
439 <IndexTerm><Primary><literal>int2Double#</literal></Primary></IndexTerm>
443 <IndexTerm><Primary><literal>plusFloat#</literal></Primary></IndexTerm>
444 <IndexTerm><Primary><literal>minusFloat#</literal></Primary></IndexTerm>
445 <IndexTerm><Primary><literal>timesFloat#</literal></Primary></IndexTerm>
446 <IndexTerm><Primary><literal>divideFloat#</literal></Primary></IndexTerm>
447 <IndexTerm><Primary><literal>gtFloat#</literal></Primary></IndexTerm>
448 <IndexTerm><Primary><literal>geFloat#</literal></Primary></IndexTerm>
449 <IndexTerm><Primary><literal>eqFloat#</literal></Primary></IndexTerm>
450 <IndexTerm><Primary><literal>neFloat#</literal></Primary></IndexTerm>
451 <IndexTerm><Primary><literal>ltFloat#</literal></Primary></IndexTerm>
452 <IndexTerm><Primary><literal>leFloat#</literal></Primary></IndexTerm>
453 <IndexTerm><Primary><literal>negateFloat#</literal></Primary></IndexTerm>
454 <IndexTerm><Primary><literal>float2Int#</literal></Primary></IndexTerm>
455 <IndexTerm><Primary><literal>int2Float#</literal></Primary></IndexTerm>
459 And a full complement of trigonometric functions:
465 expDouble# :: Double# -> Double#
466 logDouble# :: Double# -> Double#
467 sqrtDouble# :: Double# -> Double#
468 sinDouble# :: Double# -> Double#
469 cosDouble# :: Double# -> Double#
470 tanDouble# :: Double# -> Double#
471 asinDouble# :: Double# -> Double#
472 acosDouble# :: Double# -> Double#
473 atanDouble# :: Double# -> Double#
474 sinhDouble# :: Double# -> Double#
475 coshDouble# :: Double# -> Double#
476 tanhDouble# :: Double# -> Double#
477 powerDouble# :: Double# -> Double# -> Double#
480 <IndexTerm><Primary>trigonometric functions, primitive</Primary></IndexTerm>
484 similarly for <Literal>Float#</Literal>.
488 There are two coercion functions for <Literal>Float#</Literal>/<Literal>Double#</Literal>:
494 float2Double# :: Float# -> Double#
495 double2Float# :: Double# -> Float#
498 <IndexTerm><Primary><literal>float2Double#</literal></Primary></IndexTerm>
499 <IndexTerm><Primary><literal>double2Float#</literal></Primary></IndexTerm>
503 The primitive versions of <Function>encodeDouble</Function>/<Function>decodeDouble</Function>:
509 encodeDouble# :: Int# -> Int# -> ByteArray# -- Integer mantissa
510 -> Int# -- Int exponent
513 decodeDouble# :: Double# -> PrelNum.ReturnIntAndGMP
516 <IndexTerm><Primary><literal>encodeDouble#</literal></Primary></IndexTerm>
517 <IndexTerm><Primary><literal>decodeDouble#</literal></Primary></IndexTerm>
521 (And the same for <Literal>Float#</Literal>s.)
526 <Sect2 id="integer-operations">
527 <Title>Operations on/for <Literal>Integers</Literal> (interface to GMP)
531 <IndexTerm><Primary>arbitrary precision integers</Primary></IndexTerm>
532 <IndexTerm><Primary>Integer, operations on</Primary></IndexTerm>
536 We implement <Literal>Integers</Literal> (arbitrary-precision integers) using the GNU
537 multiple-precision (GMP) package (version 2.0.2).
541 The data type for <Literal>Integer</Literal> is either a small integer,
542 represented by an <Literal>Int</Literal>, or a large integer represented
543 using the pieces required by GMP's <Literal>MP_INT</Literal> in <Filename>gmp.h</Filename>
544 (see <Filename>gmp.info</Filename> in <Filename>ghc/includes/runtime/gmp</Filename>). It comes out as:
550 data Integer = S# Int# -- small integers
551 | J# Int# ByteArray# -- large integers
554 <IndexTerm><Primary>Integer type</Primary></IndexTerm>
555 The primitive ops to support large <Literal>Integers</Literal> use the “pieces” of the
556 representation, and are as follows:
562 negateInteger# :: Int# -> ByteArray# -> Integer
564 {plus,minus,times}Integer# :: Int# -> ByteArray#
565 -> Int# -> ByteArray#
568 cmpInteger# :: Int# -> ByteArray#
569 -> Int# -> ByteArray#
570 -> Int# -- -1 for <; 0 for ==; +1 for >
572 divModInteger#, quotRemInteger#
573 :: Int# -> ByteArray#
574 -> Int# -> ByteArray#
575 -> PrelNum.Return2GMPs
577 integer2Int# :: Int# -> ByteArray# -> Int#
579 int2Integer# :: Int# -> Integer -- NB: no error-checking on these two!
580 word2Integer# :: Word# -> Integer
582 addr2Integer# :: Addr# -> Integer
583 -- the Addr# is taken to be a `char *' string
584 -- to be converted into an Integer.
587 <IndexTerm><Primary><literal>negateInteger#</literal></Primary></IndexTerm>
588 <IndexTerm><Primary><literal>plusInteger#</literal></Primary></IndexTerm>
589 <IndexTerm><Primary><literal>minusInteger#</literal></Primary></IndexTerm>
590 <IndexTerm><Primary><literal>timesInteger#</literal></Primary></IndexTerm>
591 <IndexTerm><Primary><literal>cmpInteger#</literal></Primary></IndexTerm>
592 <IndexTerm><Primary><literal>divModInteger#</literal></Primary></IndexTerm>
593 <IndexTerm><Primary><literal>quotRemInteger#</literal></Primary></IndexTerm>
594 <IndexTerm><Primary><literal>integer2Int#</literal></Primary></IndexTerm>
595 <IndexTerm><Primary><literal>int2Integer#</literal></Primary></IndexTerm>
596 <IndexTerm><Primary><literal>word2Integer#</literal></Primary></IndexTerm>
597 <IndexTerm><Primary><literal>addr2Integer#</literal></Primary></IndexTerm>
603 <Title>Words and addresses</Title>
606 <IndexTerm><Primary>word, primitive type</Primary></IndexTerm>
607 <IndexTerm><Primary>address, primitive type</Primary></IndexTerm>
608 <IndexTerm><Primary>unsigned integer, primitive type</Primary></IndexTerm>
609 <IndexTerm><Primary>pointer, primitive type</Primary></IndexTerm>
613 A <Literal>Word#</Literal> is used for bit-twiddling operations. It is the same size as
614 an <Literal>Int#</Literal>, but has no sign nor any arithmetic operations.
617 type Word# -- Same size/etc as Int# but *unsigned*
618 type Addr# -- A pointer from outside the "Haskell world" (from C, probably);
619 -- described under "arrays"
622 <IndexTerm><Primary><literal>Word#</literal></Primary></IndexTerm>
623 <IndexTerm><Primary><literal>Addr#</literal></Primary></IndexTerm>
627 <Literal>Word#</Literal>s and <Literal>Addr#</Literal>s have the usual comparison operations.
628 Other unboxed-<Literal>Word</Literal> ops (bit-twiddling and coercions):
634 and#, or#, xor# :: Word# -> Word# -> Word#
637 quotWord#, remWord# :: Word# -> Word# -> Word#
638 -- word (i.e. unsigned) versions are different from int
639 -- versions, so we have to provide these explicitly.
641 not# :: Word# -> Word#
643 shiftL#, shiftRA#, shiftRL# :: Word# -> Int# -> Word#
644 -- shift left, right arithmetic, right logical
646 int2Word# :: Int# -> Word# -- just a cast, really
647 word2Int# :: Word# -> Int#
650 <IndexTerm><Primary>bit operations, Word and Addr</Primary></IndexTerm>
651 <IndexTerm><Primary><literal>and#</literal></Primary></IndexTerm>
652 <IndexTerm><Primary><literal>or#</literal></Primary></IndexTerm>
653 <IndexTerm><Primary><literal>xor#</literal></Primary></IndexTerm>
654 <IndexTerm><Primary><literal>not#</literal></Primary></IndexTerm>
655 <IndexTerm><Primary><literal>quotWord#</literal></Primary></IndexTerm>
656 <IndexTerm><Primary><literal>remWord#</literal></Primary></IndexTerm>
657 <IndexTerm><Primary><literal>shiftL#</literal></Primary></IndexTerm>
658 <IndexTerm><Primary><literal>shiftRA#</literal></Primary></IndexTerm>
659 <IndexTerm><Primary><literal>shiftRL#</literal></Primary></IndexTerm>
660 <IndexTerm><Primary><literal>int2Word#</literal></Primary></IndexTerm>
661 <IndexTerm><Primary><literal>word2Int#</literal></Primary></IndexTerm>
665 Unboxed-<Literal>Addr</Literal> ops (C casts, really):
668 int2Addr# :: Int# -> Addr#
669 addr2Int# :: Addr# -> Int#
672 <IndexTerm><Primary><literal>int2Addr#</literal></Primary></IndexTerm>
673 <IndexTerm><Primary><literal>addr2Int#</literal></Primary></IndexTerm>
677 The casts between <Literal>Int#</Literal>, <Literal>Word#</Literal> and <Literal>Addr#</Literal> correspond to null
678 operations at the machine level, but are required to keep the Haskell
683 Operations for indexing off of C pointers (<Literal>Addr#</Literal>s) to snatch values
684 are listed under “arrays”.
690 <Title>Arrays</Title>
693 <IndexTerm><Primary>arrays, primitive</Primary></IndexTerm>
697 The type <Literal>Array# elt</Literal> is the type of primitive, unpointed arrays of
698 values of type <Literal>elt</Literal>.
707 <IndexTerm><Primary><literal>Array#</literal></Primary></IndexTerm>
711 <Literal>Array#</Literal> is more primitive than a Haskell array—indeed, the
712 Haskell <Literal>Array</Literal> interface is implemented using <Literal>Array#</Literal>—in that an
713 <Literal>Array#</Literal> is indexed only by <Literal>Int#</Literal>s, starting at zero. It is also
714 more primitive by virtue of being unboxed. That doesn't mean that it
715 isn't a heap-allocated object—of course, it is. Rather, being
716 unboxed means that it is represented by a pointer to the array itself,
717 and not to a thunk which will evaluate to the array (or to bottom).
718 The components of an <Literal>Array#</Literal> are themselves boxed.
722 The type <Literal>ByteArray#</Literal> is similar to <Literal>Array#</Literal>, except that it contains
723 just a string of (non-pointer) bytes.
732 <IndexTerm><Primary><literal>ByteArray#</literal></Primary></IndexTerm>
736 Arrays of these types are useful when a Haskell program wishes to
737 construct a value to pass to a C procedure. It is also possible to
738 use them to build (say) arrays of unboxed characters for internal use
739 in a Haskell program. Given these uses, <Literal>ByteArray#</Literal> is deliberately
740 a bit vague about the type of its components. Operations are provided
741 to extract values of type <Literal>Char#</Literal>, <Literal>Int#</Literal>, <Literal>Float#</Literal>, <Literal>Double#</Literal>, and
742 <Literal>Addr#</Literal> from arbitrary offsets within a <Literal>ByteArray#</Literal>. (For type
743 <Literal>Foo#</Literal>, the $i$th offset gets you the $i$th <Literal>Foo#</Literal>, not the <Literal>Foo#</Literal> at
744 byte-position $i$. Mumble.) (If you want a <Literal>Word#</Literal>, grab an <Literal>Int#</Literal>,
749 Lastly, we have static byte-arrays, of type <Literal>Addr#</Literal> [mentioned
750 previously]. (Remember the duality between arrays and pointers in C.)
751 Arrays of this types are represented by a pointer to an array in the
752 world outside Haskell, so this pointer is not followed by the garbage
753 collector. In other respects they are just like <Literal>ByteArray#</Literal>. They
754 are only needed in order to pass values from C to Haskell.
760 <Title>Reading and writing</Title>
763 Primitive arrays are linear, and indexed starting at zero.
767 The size and indices of a <Literal>ByteArray#</Literal>, <Literal>Addr#</Literal>, and
768 <Literal>MutableByteArray#</Literal> are all in bytes. It's up to the program to
769 calculate the correct byte offset from the start of the array. This
770 allows a <Literal>ByteArray#</Literal> to contain a mixture of values of different
771 type, which is often needed when preparing data for and unpicking
772 results from C. (Umm…not true of indices…WDP 95/09)
776 <Emphasis>Should we provide some <Literal>sizeOfDouble#</Literal> constants?</Emphasis>
780 Out-of-range errors on indexing should be caught by the code which
781 uses the primitive operation; the primitive operations themselves do
782 <Emphasis>not</Emphasis> check for out-of-range indexes. The intention is that the
783 primitive ops compile to one machine instruction or thereabouts.
787 We use the terms “reading” and “writing” to refer to accessing
788 <Emphasis>mutable</Emphasis> arrays (see <XRef LinkEnd="sect-mutable">), and
789 “indexing” to refer to reading a value from an <Emphasis>immutable</Emphasis>
794 Immutable byte arrays are straightforward to index (all indices in bytes):
797 indexCharArray# :: ByteArray# -> Int# -> Char#
798 indexIntArray# :: ByteArray# -> Int# -> Int#
799 indexAddrArray# :: ByteArray# -> Int# -> Addr#
800 indexFloatArray# :: ByteArray# -> Int# -> Float#
801 indexDoubleArray# :: ByteArray# -> Int# -> Double#
803 indexCharOffAddr# :: Addr# -> Int# -> Char#
804 indexIntOffAddr# :: Addr# -> Int# -> Int#
805 indexFloatOffAddr# :: Addr# -> Int# -> Float#
806 indexDoubleOffAddr# :: Addr# -> Int# -> Double#
807 indexAddrOffAddr# :: Addr# -> Int# -> Addr#
808 -- Get an Addr# from an Addr# offset
811 <IndexTerm><Primary><literal>indexCharArray#</literal></Primary></IndexTerm>
812 <IndexTerm><Primary><literal>indexIntArray#</literal></Primary></IndexTerm>
813 <IndexTerm><Primary><literal>indexAddrArray#</literal></Primary></IndexTerm>
814 <IndexTerm><Primary><literal>indexFloatArray#</literal></Primary></IndexTerm>
815 <IndexTerm><Primary><literal>indexDoubleArray#</literal></Primary></IndexTerm>
816 <IndexTerm><Primary><literal>indexCharOffAddr#</literal></Primary></IndexTerm>
817 <IndexTerm><Primary><literal>indexIntOffAddr#</literal></Primary></IndexTerm>
818 <IndexTerm><Primary><literal>indexFloatOffAddr#</literal></Primary></IndexTerm>
819 <IndexTerm><Primary><literal>indexDoubleOffAddr#</literal></Primary></IndexTerm>
820 <IndexTerm><Primary><literal>indexAddrOffAddr#</literal></Primary></IndexTerm>
824 The last of these, <Function>indexAddrOffAddr#</Function>, extracts an <Literal>Addr#</Literal> using an offset
825 from another <Literal>Addr#</Literal>, thereby providing the ability to follow a chain of
830 Something a bit more interesting goes on when indexing arrays of boxed
831 objects, because the result is simply the boxed object. So presumably
832 it should be entered—we never usually return an unevaluated
833 object! This is a pain: primitive ops aren't supposed to do
834 complicated things like enter objects. The current solution is to
835 return a single element unboxed tuple (see <XRef LinkEnd="unboxed-tuples">).
841 indexArray# :: Array# elt -> Int# -> (# elt #)
844 <IndexTerm><Primary><literal>indexArray#</literal></Primary></IndexTerm>
850 <Title>The state type</Title>
853 <IndexTerm><Primary><literal>state, primitive type</literal></Primary></IndexTerm>
854 <IndexTerm><Primary><literal>State#</literal></Primary></IndexTerm>
858 The primitive type <Literal>State#</Literal> represents the state of a state
859 transformer. It is parameterised on the desired type of state, which
860 serves to keep states from distinct threads distinct from one another.
861 But the <Emphasis>only</Emphasis> effect of this parameterisation is in the type
862 system: all values of type <Literal>State#</Literal> are represented in the same way.
863 Indeed, they are all represented by nothing at all! The code
864 generator “knows” to generate no code, and allocate no registers
865 etc, for primitive states.
877 The type <Literal>GHC.RealWorld</Literal> is truly opaque: there are no values defined
878 of this type, and no operations over it. It is “primitive” in that
879 sense - but it is <Emphasis>not unlifted!</Emphasis> Its only role in life is to be
880 the type which distinguishes the <Literal>IO</Literal> state transformer.
894 <Title>State of the world</Title>
897 A single, primitive, value of type <Literal>State# RealWorld</Literal> is provided.
903 realWorld# :: State# RealWorld
906 <IndexTerm><Primary>realWorld# state object</Primary></IndexTerm>
910 (Note: in the compiler, not a <Literal>PrimOp</Literal>; just a mucho magic
911 <Literal>Id</Literal>. Exported from <Literal>GHC</Literal>, though).
916 <Sect2 id="sect-mutable">
917 <Title>Mutable arrays</Title>
920 <IndexTerm><Primary>mutable arrays</Primary></IndexTerm>
921 <IndexTerm><Primary>arrays, mutable</Primary></IndexTerm>
922 Corresponding to <Literal>Array#</Literal> and <Literal>ByteArray#</Literal>, we have the types of
923 mutable versions of each. In each case, the representation is a
924 pointer to a suitable block of (mutable) heap-allocated storage.
930 type MutableArray# s elt
931 type MutableByteArray# s
934 <IndexTerm><Primary><literal>MutableArray#</literal></Primary></IndexTerm>
935 <IndexTerm><Primary><literal>MutableByteArray#</literal></Primary></IndexTerm>
939 <Title>Allocation</Title>
942 <IndexTerm><Primary>mutable arrays, allocation</Primary></IndexTerm>
943 <IndexTerm><Primary>arrays, allocation</Primary></IndexTerm>
944 <IndexTerm><Primary>allocation, of mutable arrays</Primary></IndexTerm>
948 Mutable arrays can be allocated. Only pointer-arrays are initialised;
949 arrays of non-pointers are filled in by “user code” rather than by
950 the array-allocation primitive. Reason: only the pointer case has to
951 worry about GC striking with a partly-initialised array.
957 newArray# :: Int# -> elt -> State# s -> (# State# s, MutableArray# s elt #)
959 newCharArray# :: Int# -> State# s -> (# State# s, MutableByteArray# s elt #)
960 newIntArray# :: Int# -> State# s -> (# State# s, MutableByteArray# s elt #)
961 newAddrArray# :: Int# -> State# s -> (# State# s, MutableByteArray# s elt #)
962 newFloatArray# :: Int# -> State# s -> (# State# s, MutableByteArray# s elt #)
963 newDoubleArray# :: Int# -> State# s -> (# State# s, MutableByteArray# s elt #)
966 <IndexTerm><Primary><literal>newArray#</literal></Primary></IndexTerm>
967 <IndexTerm><Primary><literal>newCharArray#</literal></Primary></IndexTerm>
968 <IndexTerm><Primary><literal>newIntArray#</literal></Primary></IndexTerm>
969 <IndexTerm><Primary><literal>newAddrArray#</literal></Primary></IndexTerm>
970 <IndexTerm><Primary><literal>newFloatArray#</literal></Primary></IndexTerm>
971 <IndexTerm><Primary><literal>newDoubleArray#</literal></Primary></IndexTerm>
975 The size of a <Literal>ByteArray#</Literal> is given in bytes.
981 <Title>Reading and writing</Title>
984 <IndexTerm><Primary>arrays, reading and writing</Primary></IndexTerm>
990 readArray# :: MutableArray# s elt -> Int# -> State# s -> (# State# s, elt #)
991 readCharArray# :: MutableByteArray# s -> Int# -> State# s -> (# State# s, Char# #)
992 readIntArray# :: MutableByteArray# s -> Int# -> State# s -> (# State# s, Int# #)
993 readAddrArray# :: MutableByteArray# s -> Int# -> State# s -> (# State# s, Addr# #)
994 readFloatArray# :: MutableByteArray# s -> Int# -> State# s -> (# State# s, Float# #)
995 readDoubleArray# :: MutableByteArray# s -> Int# -> State# s -> (# State# s, Double# #)
997 writeArray# :: MutableArray# s elt -> Int# -> elt -> State# s -> State# s
998 writeCharArray# :: MutableByteArray# s -> Int# -> Char# -> State# s -> State# s
999 writeIntArray# :: MutableByteArray# s -> Int# -> Int# -> State# s -> State# s
1000 writeAddrArray# :: MutableByteArray# s -> Int# -> Addr# -> State# s -> State# s
1001 writeFloatArray# :: MutableByteArray# s -> Int# -> Float# -> State# s -> State# s
1002 writeDoubleArray# :: MutableByteArray# s -> Int# -> Double# -> State# s -> State# s
1005 <IndexTerm><Primary><literal>readArray#</literal></Primary></IndexTerm>
1006 <IndexTerm><Primary><literal>readCharArray#</literal></Primary></IndexTerm>
1007 <IndexTerm><Primary><literal>readIntArray#</literal></Primary></IndexTerm>
1008 <IndexTerm><Primary><literal>readAddrArray#</literal></Primary></IndexTerm>
1009 <IndexTerm><Primary><literal>readFloatArray#</literal></Primary></IndexTerm>
1010 <IndexTerm><Primary><literal>readDoubleArray#</literal></Primary></IndexTerm>
1011 <IndexTerm><Primary><literal>writeArray#</literal></Primary></IndexTerm>
1012 <IndexTerm><Primary><literal>writeCharArray#</literal></Primary></IndexTerm>
1013 <IndexTerm><Primary><literal>writeIntArray#</literal></Primary></IndexTerm>
1014 <IndexTerm><Primary><literal>writeAddrArray#</literal></Primary></IndexTerm>
1015 <IndexTerm><Primary><literal>writeFloatArray#</literal></Primary></IndexTerm>
1016 <IndexTerm><Primary><literal>writeDoubleArray#</literal></Primary></IndexTerm>
1022 <Title>Equality</Title>
1025 <IndexTerm><Primary>arrays, testing for equality</Primary></IndexTerm>
1029 One can take “equality” of mutable arrays. What is compared is the
1030 <Emphasis>name</Emphasis> or reference to the mutable array, not its contents.
1036 sameMutableArray# :: MutableArray# s elt -> MutableArray# s elt -> Bool
1037 sameMutableByteArray# :: MutableByteArray# s -> MutableByteArray# s -> Bool
1040 <IndexTerm><Primary><literal>sameMutableArray#</literal></Primary></IndexTerm>
1041 <IndexTerm><Primary><literal>sameMutableByteArray#</literal></Primary></IndexTerm>
1047 <Title>Freezing mutable arrays</Title>
1050 <IndexTerm><Primary>arrays, freezing mutable</Primary></IndexTerm>
1051 <IndexTerm><Primary>freezing mutable arrays</Primary></IndexTerm>
1052 <IndexTerm><Primary>mutable arrays, freezing</Primary></IndexTerm>
1056 Only unsafe-freeze has a primitive. (Safe freeze is done directly in Haskell
1057 by copying the array and then using <Function>unsafeFreeze</Function>.)
1063 unsafeFreezeArray# :: MutableArray# s elt -> State# s -> (# State# s, Array# s elt #)
1064 unsafeFreezeByteArray# :: MutableByteArray# s -> State# s -> (# State# s, ByteArray# #)
1067 <IndexTerm><Primary><literal>unsafeFreezeArray#</literal></Primary></IndexTerm>
1068 <IndexTerm><Primary><literal>unsafeFreezeByteArray#</literal></Primary></IndexTerm>
1076 <Title>Synchronizing variables (M-vars)</Title>
1079 <IndexTerm><Primary>synchronising variables (M-vars)</Primary></IndexTerm>
1080 <IndexTerm><Primary>M-Vars</Primary></IndexTerm>
1084 Synchronising variables are the primitive type used to implement
1085 Concurrent Haskell's MVars (see the Concurrent Haskell paper for
1086 the operational behaviour of these operations).
1092 type MVar# s elt -- primitive
1094 newMVar# :: State# s -> (# State# s, MVar# s elt #)
1095 takeMVar# :: SynchVar# s elt -> State# s -> (# State# s, elt #)
1096 putMVar# :: SynchVar# s elt -> State# s -> State# s
1099 <IndexTerm><Primary><literal>SynchVar#</literal></Primary></IndexTerm>
1100 <IndexTerm><Primary><literal>newSynchVar#</literal></Primary></IndexTerm>
1101 <IndexTerm><Primary><literal>takeMVar</literal></Primary></IndexTerm>
1102 <IndexTerm><Primary><literal>putMVar</literal></Primary></IndexTerm>