1 <!-- UNBOXED TYPES AND PRIMITIVE OPERATIONS -->
3 <sect1 id="primitives">
4 <title>Unboxed types and primitive operations</title>
5 <indexterm><primary>GHC.Prim module</primary></indexterm>
7 <para>This chapter defines all the types which are primitive in
8 Glasgow Haskell, and the operations provided for them. You bring
9 them into scope by importing module <literal>GHC.Prim</literal>.</para>
11 <para>Note: while you really can use this stuff to write fast code,
12 we generally find it a lot less painful, and more satisfying in the
13 long run, to use higher-level language features and libraries. With
14 any luck, the code you write will be optimised to the efficient
15 unboxed version in any case. And if it isn't, we'd like to know
18 <sect2 id="glasgow-unboxed">
23 <indexterm><primary>Unboxed types (Glasgow extension)</primary></indexterm>
26 <para>Most types in GHC are <firstterm>boxed</firstterm>, which means
27 that values of that type are represented by a pointer to a heap
28 object. The representation of a Haskell <literal>Int</literal>, for
29 example, is a two-word heap object. An <firstterm>unboxed</firstterm>
30 type, however, is represented by the value itself, no pointers or heap
31 allocation are involved.
35 Unboxed types correspond to the “raw machine” types you
36 would use in C: <literal>Int#</literal> (long int),
37 <literal>Double#</literal> (double), <literal>Addr#</literal>
38 (void *), etc. The <emphasis>primitive operations</emphasis>
39 (PrimOps) on these types are what you might expect; e.g.,
40 <literal>(+#)</literal> is addition on
41 <literal>Int#</literal>s, and is the machine-addition that we all
42 know and love—usually one instruction.
46 Primitive (unboxed) types cannot be defined in Haskell, and are
47 therefore built into the language and compiler. Primitive types are
48 always unlifted; that is, a value of a primitive type cannot be
49 bottom. We use the convention that primitive types, values, and
50 operations have a <literal>#</literal> suffix.
54 Primitive values are often represented by a simple bit-pattern, such
55 as <literal>Int#</literal>, <literal>Float#</literal>,
56 <literal>Double#</literal>. But this is not necessarily the case:
57 a primitive value might be represented by a pointer to a
58 heap-allocated object. Examples include
59 <literal>Array#</literal>, the type of primitive arrays. A
60 primitive array is heap-allocated because it is too big a value to fit
61 in a register, and would be too expensive to copy around; in a sense,
62 it is accidental that it is represented by a pointer. If a pointer
63 represents a primitive value, then it really does point to that value:
64 no unevaluated thunks, no indirections…nothing can be at the
65 other end of the pointer than the primitive value.
69 There are some restrictions on the use of primitive types, the main
70 one being that you can't pass a primitive value to a polymorphic
71 function or store one in a polymorphic data type. This rules out
72 things like <literal>[Int#]</literal> (i.e. lists of primitive
73 integers). The reason for this restriction is that polymorphic
74 arguments and constructor fields are assumed to be pointers: if an
75 unboxed integer is stored in one of these, the garbage collector would
76 attempt to follow it, leading to unpredictable space leaks. Or a
77 <function>seq</function> operation on the polymorphic component may
78 attempt to dereference the pointer, with disastrous results. Even
79 worse, the unboxed value might be larger than a pointer
80 (<literal>Double#</literal> for instance).
84 Nevertheless, A numerically-intensive program using unboxed types can
85 go a <emphasis>lot</emphasis> faster than its “standard”
86 counterpart—we saw a threefold speedup on one example.
91 <sect2 id="unboxed-tuples">
96 Unboxed tuples aren't really exported by <literal>GHC.Prim</literal>,
97 they're available by default with <option>-fglasgow-exts</option>. An
98 unboxed tuple looks like this:
110 where <literal>e_1..e_n</literal> are expressions of any
111 type (primitive or non-primitive). The type of an unboxed tuple looks
116 Unboxed tuples are used for functions that need to return multiple
117 values, but they avoid the heap allocation normally associated with
118 using fully-fledged tuples. When an unboxed tuple is returned, the
119 components are put directly into registers or on the stack; the
120 unboxed tuple itself does not have a composite representation. Many
121 of the primitive operations listed in this section return unboxed
126 There are some pretty stringent restrictions on the use of unboxed tuples:
135 Unboxed tuple types are subject to the same restrictions as
136 other unboxed types; i.e. they may not be stored in polymorphic data
137 structures or passed to polymorphic functions.
144 Unboxed tuples may only be constructed as the direct result of
145 a function, and may only be deconstructed with a <literal>case</literal> expression.
146 eg. the following are valid:
150 f x y = (# x+1, y-1 #)
151 g x = case f x x of { (# a, b #) -> a + b }
155 but the following are invalid:
169 No variable can have an unboxed tuple type. This is illegal:
173 f :: (# Int, Int #) -> (# Int, Int #)
178 because <literal>x</literal> has an unboxed tuple type.
188 Note: we may relax some of these restrictions in the future.
192 The <literal>IO</literal> and <literal>ST</literal> monads use unboxed
193 tuples to avoid unnecessary allocation during sequences of operations.
199 <title>Character and numeric types</title>
201 <indexterm><primary>character types, primitive</primary></indexterm>
202 <indexterm><primary>numeric types, primitive</primary></indexterm>
203 <indexterm><primary>integer types, primitive</primary></indexterm>
204 <indexterm><primary>floating point types, primitive</primary></indexterm>
206 There are the following obvious primitive types:
220 <indexterm><primary><literal>Char#</literal></primary></indexterm>
221 <indexterm><primary><literal>Int#</literal></primary></indexterm>
222 <indexterm><primary><literal>Word#</literal></primary></indexterm>
223 <indexterm><primary><literal>Addr#</literal></primary></indexterm>
224 <indexterm><primary><literal>Float#</literal></primary></indexterm>
225 <indexterm><primary><literal>Double#</literal></primary></indexterm>
226 <indexterm><primary><literal>Int64#</literal></primary></indexterm>
227 <indexterm><primary><literal>Word64#</literal></primary></indexterm>
230 If you really want to know their exact equivalents in C, see
231 <filename>ghc/includes/StgTypes.h</filename> in the GHC source tree.
235 Literals for these types may be written as follows:
244 'a'# a Char#; for weird characters, use e.g. '\o<octal>'#
245 "a"# an Addr# (a `char *'); only characters '\0'..'\255' allowed
248 <indexterm><primary>literals, primitive</primary></indexterm>
249 <indexterm><primary>constants, primitive</primary></indexterm>
250 <indexterm><primary>numbers, primitive</primary></indexterm>
256 <title>Comparison operations</title>
259 <indexterm><primary>comparisons, primitive</primary></indexterm>
260 <indexterm><primary>operators, comparison</primary></indexterm>
266 {>,>=,==,/=,<,<=}# :: Int# -> Int# -> Bool
268 {gt,ge,eq,ne,lt,le}Char# :: Char# -> Char# -> Bool
269 -- ditto for Word# and Addr#
272 <indexterm><primary><literal>>#</literal></primary></indexterm>
273 <indexterm><primary><literal>>=#</literal></primary></indexterm>
274 <indexterm><primary><literal>==#</literal></primary></indexterm>
275 <indexterm><primary><literal>/=#</literal></primary></indexterm>
276 <indexterm><primary><literal><#</literal></primary></indexterm>
277 <indexterm><primary><literal><=#</literal></primary></indexterm>
278 <indexterm><primary><literal>gt{Char,Word,Addr}#</literal></primary></indexterm>
279 <indexterm><primary><literal>ge{Char,Word,Addr}#</literal></primary></indexterm>
280 <indexterm><primary><literal>eq{Char,Word,Addr}#</literal></primary></indexterm>
281 <indexterm><primary><literal>ne{Char,Word,Addr}#</literal></primary></indexterm>
282 <indexterm><primary><literal>lt{Char,Word,Addr}#</literal></primary></indexterm>
283 <indexterm><primary><literal>le{Char,Word,Addr}#</literal></primary></indexterm>
289 <title>Primitive-character operations</title>
292 <indexterm><primary>characters, primitive operations</primary></indexterm>
293 <indexterm><primary>operators, primitive character</primary></indexterm>
299 ord# :: Char# -> Int#
300 chr# :: Int# -> Char#
303 <indexterm><primary><literal>ord#</literal></primary></indexterm>
304 <indexterm><primary><literal>chr#</literal></primary></indexterm>
310 <title>Primitive-<literal>Int</literal> operations</title>
313 <indexterm><primary>integers, primitive operations</primary></indexterm>
314 <indexterm><primary>operators, primitive integer</primary></indexterm>
320 {+,-,*,quotInt,remInt,gcdInt}# :: Int# -> Int# -> Int#
321 negateInt# :: Int# -> Int#
323 iShiftL#, iShiftRA#, iShiftRL# :: Int# -> Int# -> Int#
324 -- shift left, right arithmetic, right logical
326 addIntC#, subIntC#, mulIntC# :: Int# -> Int# -> (# Int#, Int# #)
327 -- add, subtract, multiply with carry
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>quotInt#</literal></primary></indexterm>
334 <indexterm><primary><literal>remInt#</literal></primary></indexterm>
335 <indexterm><primary><literal>gcdInt#</literal></primary></indexterm>
336 <indexterm><primary><literal>iShiftL#</literal></primary></indexterm>
337 <indexterm><primary><literal>iShiftRA#</literal></primary></indexterm>
338 <indexterm><primary><literal>iShiftRL#</literal></primary></indexterm>
339 <indexterm><primary><literal>addIntC#</literal></primary></indexterm>
340 <indexterm><primary><literal>subIntC#</literal></primary></indexterm>
341 <indexterm><primary><literal>mulIntC#</literal></primary></indexterm>
342 <indexterm><primary>shift operations, integer</primary></indexterm>
346 <emphasis>Note:</emphasis> No error/overflow checking!
352 <title>Primitive-<literal>Double</literal> and <literal>Float</literal> operations</title>
355 <indexterm><primary>floating point numbers, primitive</primary></indexterm>
356 <indexterm><primary>operators, primitive floating point</primary></indexterm>
362 {+,-,*,/}## :: Double# -> Double# -> Double#
363 {<,<=,==,/=,>=,>}## :: Double# -> Double# -> Bool
364 negateDouble# :: Double# -> Double#
365 double2Int# :: Double# -> Int#
366 int2Double# :: Int# -> Double#
368 {plus,minux,times,divide}Float# :: Float# -> Float# -> Float#
369 {gt,ge,eq,ne,lt,le}Float# :: Float# -> Float# -> Bool
370 negateFloat# :: Float# -> Float#
371 float2Int# :: Float# -> Int#
372 int2Float# :: Int# -> Float#
378 <indexterm><primary><literal>+##</literal></primary></indexterm>
379 <indexterm><primary><literal>-##</literal></primary></indexterm>
380 <indexterm><primary><literal>*##</literal></primary></indexterm>
381 <indexterm><primary><literal>/##</literal></primary></indexterm>
382 <indexterm><primary><literal><##</literal></primary></indexterm>
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>>=##</literal></primary></indexterm>
387 <indexterm><primary><literal>>##</literal></primary></indexterm>
388 <indexterm><primary><literal>negateDouble#</literal></primary></indexterm>
389 <indexterm><primary><literal>double2Int#</literal></primary></indexterm>
390 <indexterm><primary><literal>int2Double#</literal></primary></indexterm>
394 <indexterm><primary><literal>plusFloat#</literal></primary></indexterm>
395 <indexterm><primary><literal>minusFloat#</literal></primary></indexterm>
396 <indexterm><primary><literal>timesFloat#</literal></primary></indexterm>
397 <indexterm><primary><literal>divideFloat#</literal></primary></indexterm>
398 <indexterm><primary><literal>gtFloat#</literal></primary></indexterm>
399 <indexterm><primary><literal>geFloat#</literal></primary></indexterm>
400 <indexterm><primary><literal>eqFloat#</literal></primary></indexterm>
401 <indexterm><primary><literal>neFloat#</literal></primary></indexterm>
402 <indexterm><primary><literal>ltFloat#</literal></primary></indexterm>
403 <indexterm><primary><literal>leFloat#</literal></primary></indexterm>
404 <indexterm><primary><literal>negateFloat#</literal></primary></indexterm>
405 <indexterm><primary><literal>float2Int#</literal></primary></indexterm>
406 <indexterm><primary><literal>int2Float#</literal></primary></indexterm>
410 And a full complement of trigonometric functions:
416 expDouble# :: Double# -> Double#
417 logDouble# :: Double# -> Double#
418 sqrtDouble# :: Double# -> Double#
419 sinDouble# :: Double# -> Double#
420 cosDouble# :: Double# -> Double#
421 tanDouble# :: Double# -> Double#
422 asinDouble# :: Double# -> Double#
423 acosDouble# :: Double# -> Double#
424 atanDouble# :: Double# -> Double#
425 sinhDouble# :: Double# -> Double#
426 coshDouble# :: Double# -> Double#
427 tanhDouble# :: Double# -> Double#
428 powerDouble# :: Double# -> Double# -> Double#
431 <indexterm><primary>trigonometric functions, primitive</primary></indexterm>
435 similarly for <literal>Float#</literal>.
439 There are two coercion functions for <literal>Float#</literal>/<literal>Double#</literal>:
445 float2Double# :: Float# -> Double#
446 double2Float# :: Double# -> Float#
449 <indexterm><primary><literal>float2Double#</literal></primary></indexterm>
450 <indexterm><primary><literal>double2Float#</literal></primary></indexterm>
454 The primitive version of <function>decodeDouble</function>
455 (<function>encodeDouble</function> is implemented as an external C
462 decodeDouble# :: Double# -> PrelNum.ReturnIntAndGMP
465 <indexterm><primary><literal>encodeDouble#</literal></primary></indexterm>
466 <indexterm><primary><literal>decodeDouble#</literal></primary></indexterm>
470 (And the same for <literal>Float#</literal>s.)
475 <sect2 id="integer-operations">
476 <title>Operations on/for <literal>Integers</literal> (interface to GMP)
480 <indexterm><primary>arbitrary precision integers</primary></indexterm>
481 <indexterm><primary>Integer, operations on</primary></indexterm>
485 We implement <literal>Integers</literal> (arbitrary-precision
486 integers) using the GNU multiple-precision (GMP) package (version
491 The data type for <literal>Integer</literal> is either a small
492 integer, represented by an <literal>Int</literal>, or a large integer
493 represented using the pieces required by GMP's
494 <literal>MP_INT</literal> in <filename>gmp.h</filename> (see
495 <filename>gmp.info</filename> in
496 <filename>ghc/includes/runtime/gmp</filename>). It comes out as:
502 data Integer = S# Int# -- small integers
503 | J# Int# ByteArray# -- large integers
506 <indexterm><primary>Integer type</primary></indexterm> The primitive
507 ops to support large <literal>Integers</literal> use the
508 “pieces” of the representation, and are as follows:
514 negateInteger# :: Int# -> ByteArray# -> Integer
516 {plus,minus,times}Integer#, gcdInteger#,
517 quotInteger#, remInteger#, divExactInteger#
518 :: Int# -> ByteArray#
519 -> Int# -> ByteArray#
520 -> (# Int#, ByteArray# #)
523 :: Int# -> ByteArray#
524 -> Int# -> ByteArray#
525 -> Int# -- -1 for <; 0 for ==; +1 for >
528 :: Int# -> ByteArray#
530 -> Int# -- -1 for <; 0 for ==; +1 for >
533 :: Int# -> ByteArray#
537 divModInteger#, quotRemInteger#
538 :: Int# -> ByteArray#
539 -> Int# -> ByteArray#
540 -> (# Int#, ByteArray#,
543 integer2Int# :: Int# -> ByteArray# -> Int#
545 int2Integer# :: Int# -> Integer -- NB: no error-checking on these two!
546 word2Integer# :: Word# -> Integer
548 addr2Integer# :: Addr# -> Integer
549 -- the Addr# is taken to be a `char *' string
550 -- to be converted into an Integer.
553 <indexterm><primary><literal>negateInteger#</literal></primary></indexterm>
554 <indexterm><primary><literal>plusInteger#</literal></primary></indexterm>
555 <indexterm><primary><literal>minusInteger#</literal></primary></indexterm>
556 <indexterm><primary><literal>timesInteger#</literal></primary></indexterm>
557 <indexterm><primary><literal>quotInteger#</literal></primary></indexterm>
558 <indexterm><primary><literal>remInteger#</literal></primary></indexterm>
559 <indexterm><primary><literal>gcdInteger#</literal></primary></indexterm>
560 <indexterm><primary><literal>gcdIntegerInt#</literal></primary></indexterm>
561 <indexterm><primary><literal>divExactInteger#</literal></primary></indexterm>
562 <indexterm><primary><literal>cmpInteger#</literal></primary></indexterm>
563 <indexterm><primary><literal>divModInteger#</literal></primary></indexterm>
564 <indexterm><primary><literal>quotRemInteger#</literal></primary></indexterm>
565 <indexterm><primary><literal>integer2Int#</literal></primary></indexterm>
566 <indexterm><primary><literal>int2Integer#</literal></primary></indexterm>
567 <indexterm><primary><literal>word2Integer#</literal></primary></indexterm>
568 <indexterm><primary><literal>addr2Integer#</literal></primary></indexterm>
574 <title>Words and addresses</title>
577 <indexterm><primary>word, primitive type</primary></indexterm>
578 <indexterm><primary>address, primitive type</primary></indexterm>
579 <indexterm><primary>unsigned integer, primitive type</primary></indexterm>
580 <indexterm><primary>pointer, primitive type</primary></indexterm>
584 A <literal>Word#</literal> is used for bit-twiddling operations.
585 It is the same size as an <literal>Int#</literal>, but has no sign
586 nor any arithmetic operations.
589 type Word# -- Same size/etc as Int# but *unsigned*
590 type Addr# -- A pointer from outside the "Haskell world" (from C, probably);
591 -- described under "arrays"
594 <indexterm><primary><literal>Word#</literal></primary></indexterm>
595 <indexterm><primary><literal>Addr#</literal></primary></indexterm>
599 <literal>Word#</literal>s and <literal>Addr#</literal>s have
600 the usual comparison operations. Other
601 unboxed-<literal>Word</literal> ops (bit-twiddling and coercions):
607 {gt,ge,eq,ne,lt,le}Word# :: Word# -> Word# -> Bool
609 and#, or#, xor# :: Word# -> Word# -> Word#
612 quotWord#, remWord# :: Word# -> Word# -> Word#
613 -- word (i.e. unsigned) versions are different from int
614 -- versions, so we have to provide these explicitly.
616 not# :: Word# -> Word#
618 shiftL#, shiftRL# :: Word# -> Int# -> Word#
619 -- shift left, right logical
621 int2Word# :: Int# -> Word# -- just a cast, really
622 word2Int# :: Word# -> Int#
625 <indexterm><primary>bit operations, Word and Addr</primary></indexterm>
626 <indexterm><primary><literal>gtWord#</literal></primary></indexterm>
627 <indexterm><primary><literal>geWord#</literal></primary></indexterm>
628 <indexterm><primary><literal>eqWord#</literal></primary></indexterm>
629 <indexterm><primary><literal>neWord#</literal></primary></indexterm>
630 <indexterm><primary><literal>ltWord#</literal></primary></indexterm>
631 <indexterm><primary><literal>leWord#</literal></primary></indexterm>
632 <indexterm><primary><literal>and#</literal></primary></indexterm>
633 <indexterm><primary><literal>or#</literal></primary></indexterm>
634 <indexterm><primary><literal>xor#</literal></primary></indexterm>
635 <indexterm><primary><literal>not#</literal></primary></indexterm>
636 <indexterm><primary><literal>quotWord#</literal></primary></indexterm>
637 <indexterm><primary><literal>remWord#</literal></primary></indexterm>
638 <indexterm><primary><literal>shiftL#</literal></primary></indexterm>
639 <indexterm><primary><literal>shiftRA#</literal></primary></indexterm>
640 <indexterm><primary><literal>shiftRL#</literal></primary></indexterm>
641 <indexterm><primary><literal>int2Word#</literal></primary></indexterm>
642 <indexterm><primary><literal>word2Int#</literal></primary></indexterm>
646 Unboxed-<literal>Addr</literal> ops (C casts, really):
649 {gt,ge,eq,ne,lt,le}Addr# :: Addr# -> Addr# -> Bool
651 int2Addr# :: Int# -> Addr#
652 addr2Int# :: Addr# -> Int#
653 addr2Integer# :: Addr# -> (# Int#, ByteArray# #)
656 <indexterm><primary><literal>gtAddr#</literal></primary></indexterm>
657 <indexterm><primary><literal>geAddr#</literal></primary></indexterm>
658 <indexterm><primary><literal>eqAddr#</literal></primary></indexterm>
659 <indexterm><primary><literal>neAddr#</literal></primary></indexterm>
660 <indexterm><primary><literal>ltAddr#</literal></primary></indexterm>
661 <indexterm><primary><literal>leAddr#</literal></primary></indexterm>
662 <indexterm><primary><literal>int2Addr#</literal></primary></indexterm>
663 <indexterm><primary><literal>addr2Int#</literal></primary></indexterm>
664 <indexterm><primary><literal>addr2Integer#</literal></primary></indexterm>
668 The casts between <literal>Int#</literal>,
669 <literal>Word#</literal> and <literal>Addr#</literal>
670 correspond to null operations at the machine level, but are required
671 to keep the Haskell type checker happy.
675 Operations for indexing off of C pointers
676 (<literal>Addr#</literal>s) to snatch values are listed under
677 “arrays”.
683 <title>Arrays</title>
686 <indexterm><primary>arrays, primitive</primary></indexterm>
690 The type <literal>Array# elt</literal> is the type of primitive,
691 unpointed arrays of values of type <literal>elt</literal>.
700 <indexterm><primary><literal>Array#</literal></primary></indexterm>
704 <literal>Array#</literal> is more primitive than a Haskell
705 array—indeed, the Haskell <literal>Array</literal> interface is
706 implemented using <literal>Array#</literal>—in that an
707 <literal>Array#</literal> is indexed only by
708 <literal>Int#</literal>s, starting at zero. It is also more
709 primitive by virtue of being unboxed. That doesn't mean that it isn't
710 a heap-allocated object—of course, it is. Rather, being unboxed
711 means that it is represented by a pointer to the array itself, and not
712 to a thunk which will evaluate to the array (or to bottom). The
713 components of an <literal>Array#</literal> are themselves boxed.
717 The type <literal>ByteArray#</literal> is similar to
718 <literal>Array#</literal>, except that it contains just a string
719 of (non-pointer) bytes.
728 <indexterm><primary><literal>ByteArray#</literal></primary></indexterm>
732 Arrays of these types are useful when a Haskell program wishes to
733 construct a value to pass to a C procedure. It is also possible to use
734 them to build (say) arrays of unboxed characters for internal use in a
735 Haskell program. Given these uses, <literal>ByteArray#</literal>
736 is deliberately a bit vague about the type of its components.
737 Operations are provided to extract values of type
738 <literal>Char#</literal>, <literal>Int#</literal>,
739 <literal>Float#</literal>, <literal>Double#</literal>, and
740 <literal>Addr#</literal> from arbitrary offsets within a
741 <literal>ByteArray#</literal>. (For type
742 <literal>Foo#</literal>, the $i$th offset gets you the $i$th
743 <literal>Foo#</literal>, not the <literal>Foo#</literal> at
744 byte-position $i$. Mumble.) (If you want a
745 <literal>Word#</literal>, grab an <literal>Int#</literal>,
750 Lastly, we have static byte-arrays, of type
751 <literal>Addr#</literal> [mentioned previously]. (Remember
752 the duality between arrays and pointers in C.) Arrays of this types
753 are represented by a pointer to an array in the world outside Haskell,
754 so this pointer is not followed by the garbage collector. In other
755 respects they are just like <literal>ByteArray#</literal>. They
756 are only needed in order to pass values from C to Haskell.
762 <title>Reading and writing</title>
765 Primitive arrays are linear, and indexed starting at zero.
769 The size and indices of a <literal>ByteArray#</literal>, <literal>Addr#</literal>, and
770 <literal>MutableByteArray#</literal> are all in bytes. It's up to the program to
771 calculate the correct byte offset from the start of the array. This
772 allows a <literal>ByteArray#</literal> to contain a mixture of values of different
773 type, which is often needed when preparing data for and unpicking
774 results from C. (Umm…not true of indices…WDP 95/09)
778 <emphasis>Should we provide some <literal>sizeOfDouble#</literal> constants?</emphasis>
782 Out-of-range errors on indexing should be caught by the code which
783 uses the primitive operation; the primitive operations themselves do
784 <emphasis>not</emphasis> check for out-of-range indexes. The intention is that the
785 primitive ops compile to one machine instruction or thereabouts.
789 We use the terms “reading” and “writing” to refer to accessing
790 <emphasis>mutable</emphasis> arrays (see <xref LinkEnd="sect-mutable">), and
791 “indexing” to refer to reading a value from an <emphasis>immutable</emphasis>
796 Immutable byte arrays are straightforward to index (all indices are in
797 units of the size of the object being read):
800 indexCharArray# :: ByteArray# -> Int# -> Char#
801 indexIntArray# :: ByteArray# -> Int# -> Int#
802 indexAddrArray# :: ByteArray# -> Int# -> Addr#
803 indexFloatArray# :: ByteArray# -> Int# -> Float#
804 indexDoubleArray# :: ByteArray# -> Int# -> Double#
806 indexCharOffAddr# :: Addr# -> Int# -> Char#
807 indexIntOffAddr# :: Addr# -> Int# -> Int#
808 indexFloatOffAddr# :: Addr# -> Int# -> Float#
809 indexDoubleOffAddr# :: Addr# -> Int# -> Double#
810 indexAddrOffAddr# :: Addr# -> Int# -> Addr#
811 -- Get an Addr# from an Addr# offset
814 <indexterm><primary><literal>indexCharArray#</literal></primary></indexterm>
815 <indexterm><primary><literal>indexIntArray#</literal></primary></indexterm>
816 <indexterm><primary><literal>indexAddrArray#</literal></primary></indexterm>
817 <indexterm><primary><literal>indexFloatArray#</literal></primary></indexterm>
818 <indexterm><primary><literal>indexDoubleArray#</literal></primary></indexterm>
819 <indexterm><primary><literal>indexCharOffAddr#</literal></primary></indexterm>
820 <indexterm><primary><literal>indexIntOffAddr#</literal></primary></indexterm>
821 <indexterm><primary><literal>indexFloatOffAddr#</literal></primary></indexterm>
822 <indexterm><primary><literal>indexDoubleOffAddr#</literal></primary></indexterm>
823 <indexterm><primary><literal>indexAddrOffAddr#</literal></primary></indexterm>
827 The last of these, <function>indexAddrOffAddr#</function>, extracts an <literal>Addr#</literal> using an offset
828 from another <literal>Addr#</literal>, thereby providing the ability to follow a chain of
833 Something a bit more interesting goes on when indexing arrays of boxed
834 objects, because the result is simply the boxed object. So presumably
835 it should be entered—we never usually return an unevaluated
836 object! This is a pain: primitive ops aren't supposed to do
837 complicated things like enter objects. The current solution is to
838 return a single element unboxed tuple (see <xref LinkEnd="unboxed-tuples">).
844 indexArray# :: Array# elt -> Int# -> (# elt #)
847 <indexterm><primary><literal>indexArray#</literal></primary></indexterm>
853 <title>The state type</title>
856 <indexterm><primary><literal>state, primitive type</literal></primary></indexterm>
857 <indexterm><primary><literal>State#</literal></primary></indexterm>
861 The primitive type <literal>State#</literal> represents the state of a state
862 transformer. It is parameterised on the desired type of state, which
863 serves to keep states from distinct threads distinct from one another.
864 But the <emphasis>only</emphasis> effect of this parameterisation is in the type
865 system: all values of type <literal>State#</literal> are represented in the same way.
866 Indeed, they are all represented by nothing at all! The code
867 generator “knows” to generate no code, and allocate no registers
868 etc, for primitive states.
880 The type <literal>GHC.RealWorld</literal> is truly opaque: there are no values defined
881 of this type, and no operations over it. It is “primitive” in that
882 sense - but it is <emphasis>not unlifted!</emphasis> Its only role in life is to be
883 the type which distinguishes the <literal>IO</literal> state transformer.
897 <title>State of the world</title>
900 A single, primitive, value of type <literal>State# RealWorld</literal> is provided.
906 realWorld# :: State# RealWorld
909 <indexterm><primary>realWorld# state object</primary></indexterm>
913 (Note: in the compiler, not a <literal>PrimOp</literal>; just a mucho magic
914 <literal>Id</literal>. Exported from <literal>GHC</literal>, though).
919 <sect2 id="sect-mutable">
920 <title>Mutable arrays</title>
923 <indexterm><primary>mutable arrays</primary></indexterm>
924 <indexterm><primary>arrays, mutable</primary></indexterm>
925 Corresponding to <literal>Array#</literal> and <literal>ByteArray#</literal>, we have the types of
926 mutable versions of each. In each case, the representation is a
927 pointer to a suitable block of (mutable) heap-allocated storage.
933 type MutableArray# s elt
934 type MutableByteArray# s
937 <indexterm><primary><literal>MutableArray#</literal></primary></indexterm>
938 <indexterm><primary><literal>MutableByteArray#</literal></primary></indexterm>
942 <title>Allocation</title>
945 <indexterm><primary>mutable arrays, allocation</primary></indexterm>
946 <indexterm><primary>arrays, allocation</primary></indexterm>
947 <indexterm><primary>allocation, of mutable arrays</primary></indexterm>
951 Mutable arrays can be allocated. Only pointer-arrays are initialised;
952 arrays of non-pointers are filled in by “user code” rather than by
953 the array-allocation primitive. Reason: only the pointer case has to
954 worry about GC striking with a partly-initialised array.
960 newArray# :: Int# -> elt -> State# s -> (# State# s, MutableArray# s elt #)
962 newCharArray# :: Int# -> State# s -> (# State# s, MutableByteArray# s elt #)
963 newIntArray# :: Int# -> State# s -> (# State# s, MutableByteArray# s elt #)
964 newAddrArray# :: Int# -> State# s -> (# State# s, MutableByteArray# s elt #)
965 newFloatArray# :: Int# -> State# s -> (# State# s, MutableByteArray# s elt #)
966 newDoubleArray# :: Int# -> State# s -> (# State# s, MutableByteArray# s elt #)
969 <indexterm><primary><literal>newArray#</literal></primary></indexterm>
970 <indexterm><primary><literal>newCharArray#</literal></primary></indexterm>
971 <indexterm><primary><literal>newIntArray#</literal></primary></indexterm>
972 <indexterm><primary><literal>newAddrArray#</literal></primary></indexterm>
973 <indexterm><primary><literal>newFloatArray#</literal></primary></indexterm>
974 <indexterm><primary><literal>newDoubleArray#</literal></primary></indexterm>
978 The size of a <literal>ByteArray#</literal> is given in bytes.
984 <title>Reading and writing</title>
987 <indexterm><primary>arrays, reading and writing</primary></indexterm>
993 readArray# :: MutableArray# s elt -> Int# -> State# s -> (# State# s, elt #)
994 readCharArray# :: MutableByteArray# s -> Int# -> State# s -> (# State# s, Char# #)
995 readIntArray# :: MutableByteArray# s -> Int# -> State# s -> (# State# s, Int# #)
996 readAddrArray# :: MutableByteArray# s -> Int# -> State# s -> (# State# s, Addr# #)
997 readFloatArray# :: MutableByteArray# s -> Int# -> State# s -> (# State# s, Float# #)
998 readDoubleArray# :: MutableByteArray# s -> Int# -> State# s -> (# State# s, Double# #)
1000 writeArray# :: MutableArray# s elt -> Int# -> elt -> State# s -> State# s
1001 writeCharArray# :: MutableByteArray# s -> Int# -> Char# -> State# s -> State# s
1002 writeIntArray# :: MutableByteArray# s -> Int# -> Int# -> State# s -> State# s
1003 writeAddrArray# :: MutableByteArray# s -> Int# -> Addr# -> State# s -> State# s
1004 writeFloatArray# :: MutableByteArray# s -> Int# -> Float# -> State# s -> State# s
1005 writeDoubleArray# :: MutableByteArray# s -> Int# -> Double# -> State# s -> State# s
1008 <indexterm><primary><literal>readArray#</literal></primary></indexterm>
1009 <indexterm><primary><literal>readCharArray#</literal></primary></indexterm>
1010 <indexterm><primary><literal>readIntArray#</literal></primary></indexterm>
1011 <indexterm><primary><literal>readAddrArray#</literal></primary></indexterm>
1012 <indexterm><primary><literal>readFloatArray#</literal></primary></indexterm>
1013 <indexterm><primary><literal>readDoubleArray#</literal></primary></indexterm>
1014 <indexterm><primary><literal>writeArray#</literal></primary></indexterm>
1015 <indexterm><primary><literal>writeCharArray#</literal></primary></indexterm>
1016 <indexterm><primary><literal>writeIntArray#</literal></primary></indexterm>
1017 <indexterm><primary><literal>writeAddrArray#</literal></primary></indexterm>
1018 <indexterm><primary><literal>writeFloatArray#</literal></primary></indexterm>
1019 <indexterm><primary><literal>writeDoubleArray#</literal></primary></indexterm>
1025 <title>Equality</title>
1028 <indexterm><primary>arrays, testing for equality</primary></indexterm>
1032 One can take “equality” of mutable arrays. What is compared is the
1033 <emphasis>name</emphasis> or reference to the mutable array, not its contents.
1039 sameMutableArray# :: MutableArray# s elt -> MutableArray# s elt -> Bool
1040 sameMutableByteArray# :: MutableByteArray# s -> MutableByteArray# s -> Bool
1043 <indexterm><primary><literal>sameMutableArray#</literal></primary></indexterm>
1044 <indexterm><primary><literal>sameMutableByteArray#</literal></primary></indexterm>
1050 <title>Freezing mutable arrays</title>
1053 <indexterm><primary>arrays, freezing mutable</primary></indexterm>
1054 <indexterm><primary>freezing mutable arrays</primary></indexterm>
1055 <indexterm><primary>mutable arrays, freezing</primary></indexterm>
1059 Only unsafe-freeze has a primitive. (Safe freeze is done directly in Haskell
1060 by copying the array and then using <function>unsafeFreeze</function>.)
1066 unsafeFreezeArray# :: MutableArray# s elt -> State# s -> (# State# s, Array# s elt #)
1067 unsafeFreezeByteArray# :: MutableByteArray# s -> State# s -> (# State# s, ByteArray# #)
1070 <indexterm><primary><literal>unsafeFreezeArray#</literal></primary></indexterm>
1071 <indexterm><primary><literal>unsafeFreezeByteArray#</literal></primary></indexterm>
1079 <title>Synchronizing variables (M-vars)</title>
1082 <indexterm><primary>synchronising variables (M-vars)</primary></indexterm>
1083 <indexterm><primary>M-Vars</primary></indexterm>
1087 Synchronising variables are the primitive type used to implement
1088 Concurrent Haskell's MVars (see the Concurrent Haskell paper for
1089 the operational behaviour of these operations).
1095 type MVar# s elt -- primitive
1097 newMVar# :: State# s -> (# State# s, MVar# s elt #)
1098 takeMVar# :: SynchVar# s elt -> State# s -> (# State# s, elt #)
1099 putMVar# :: SynchVar# s elt -> State# s -> State# s
1102 <indexterm><primary><literal>SynchVar#</literal></primary></indexterm>
1103 <indexterm><primary><literal>newSynchVar#</literal></primary></indexterm>
1104 <indexterm><primary><literal>takeMVar</literal></primary></indexterm>
1105 <indexterm><primary><literal>putMVar</literal></primary></indexterm>
1110 <sect2 id="glasgow-prim-arrays">
1111 <title>Primitive arrays, mutable and otherwise
1115 <indexterm><primary>primitive arrays (Glasgow extension)</primary></indexterm>
1116 <indexterm><primary>arrays, primitive (Glasgow extension)</primary></indexterm>
1120 GHC knows about quite a few flavours of Large Swathes of Bytes.
1124 First, GHC distinguishes between primitive arrays of (boxed) Haskell
1125 objects (type <literal>Array# obj</literal>) and primitive arrays of bytes (type
1126 <literal>ByteArray#</literal>).
1130 Second, it distinguishes between…
1134 <term>Immutable:</term>
1137 Arrays that do not change (as with “standard” Haskell arrays); you
1138 can only read from them. Obviously, they do not need the care and
1139 attention of the state-transformer monad.
1144 <term>Mutable:</term>
1147 Arrays that may be changed or “mutated.” All the operations on them
1148 live within the state-transformer monad and the updates happen
1149 <emphasis>in-place</emphasis>.
1154 <term>“Static” (in C land):</term>
1157 A C routine may pass an <literal>Addr#</literal> pointer back into Haskell land. There
1158 are then primitive operations with which you may merrily grab values
1159 over in C land, by indexing off the “static” pointer.
1164 <term>“Stable” pointers:</term>
1167 If, for some reason, you wish to hand a Haskell pointer (i.e.,
1168 <emphasis>not</emphasis> an unboxed value) to a C routine, you first make the
1169 pointer “stable,” so that the garbage collector won't forget that it
1170 exists. That is, GHC provides a safe way to pass Haskell pointers to
1175 Please see <xref LinkEnd="sec-stable-pointers"> for more details.
1180 <term>“Foreign objects”:</term>
1183 A “foreign object” is a safe way to pass an external object (a
1184 C-allocated pointer, say) to Haskell and have Haskell do the Right
1185 Thing when it no longer references the object. So, for example, C
1186 could pass a large bitmap over to Haskell and say “please free this
1187 memory when you're done with it.”
1191 Please see <xref LinkEnd="sec-ForeignObj"> for more details.
1199 The libraries documentatation gives more details on all these
1200 “primitive array” types and the operations on them.
1208 ;;; Local Variables: ***
1210 ;;; sgml-parent-document: ("users_guide.sgml" "book" "chapter" "sect1") ***