1 <?xml version="1.0" encoding="iso-8859-1"?>
2 <!-- UNBOXED TYPES AND PRIMITIVE OPERATIONS -->
4 <sect1 id="primitives">
5 <title>Unboxed types and primitive operations</title>
6 <indexterm><primary>GHC.Exts module</primary></indexterm>
8 <para>This chapter defines all the types which are primitive in
9 Glasgow Haskell, and the operations provided for them. You bring
10 them into scope by importing module <literal>GHC.Exts</literal>.</para>
12 <para>Note: while you really can use this stuff to write fast code,
13 we generally find it a lot less painful, and more satisfying in the
14 long run, to use higher-level language features and libraries. With
15 any luck, the code you write will be optimised to the efficient
16 unboxed version in any case. And if it isn't, we'd like to know
19 <sect2 id="glasgow-unboxed">
24 <indexterm><primary>Unboxed types (Glasgow extension)</primary></indexterm>
27 <para>Most types in GHC are <firstterm>boxed</firstterm>, which means
28 that values of that type are represented by a pointer to a heap
29 object. The representation of a Haskell <literal>Int</literal>, for
30 example, is a two-word heap object. An <firstterm>unboxed</firstterm>
31 type, however, is represented by the value itself, no pointers or heap
32 allocation are involved.
36 Unboxed types correspond to the “raw machine” types you
37 would use in C: <literal>Int#</literal> (long int),
38 <literal>Double#</literal> (double), <literal>Addr#</literal>
39 (void *), etc. The <emphasis>primitive operations</emphasis>
40 (PrimOps) on these types are what you might expect; e.g.,
41 <literal>(+#)</literal> is addition on
42 <literal>Int#</literal>s, and is the machine-addition that we all
43 know and love—usually one instruction.
47 Primitive (unboxed) types cannot be defined in Haskell, and are
48 therefore built into the language and compiler. Primitive types are
49 always unlifted; that is, a value of a primitive type cannot be
50 bottom. We use the convention that primitive types, values, and
51 operations have a <literal>#</literal> suffix.
55 Primitive values are often represented by a simple bit-pattern, such
56 as <literal>Int#</literal>, <literal>Float#</literal>,
57 <literal>Double#</literal>. But this is not necessarily the case:
58 a primitive value might be represented by a pointer to a
59 heap-allocated object. Examples include
60 <literal>Array#</literal>, the type of primitive arrays. A
61 primitive array is heap-allocated because it is too big a value to fit
62 in a register, and would be too expensive to copy around; in a sense,
63 it is accidental that it is represented by a pointer. If a pointer
64 represents a primitive value, then it really does point to that value:
65 no unevaluated thunks, no indirections…nothing can be at the
66 other end of the pointer than the primitive value.
70 There are some restrictions on the use of primitive types, the main
71 one being that you can't pass a primitive value to a polymorphic
72 function or store one in a polymorphic data type. This rules out
73 things like <literal>[Int#]</literal> (i.e. lists of primitive
74 integers). The reason for this restriction is that polymorphic
75 arguments and constructor fields are assumed to be pointers: if an
76 unboxed integer is stored in one of these, the garbage collector would
77 attempt to follow it, leading to unpredictable space leaks. Or a
78 <function>seq</function> operation on the polymorphic component may
79 attempt to dereference the pointer, with disastrous results. Even
80 worse, the unboxed value might be larger than a pointer
81 (<literal>Double#</literal> for instance).
85 Nevertheless, A numerically-intensive program using unboxed types can
86 go a <emphasis>lot</emphasis> faster than its “standard”
87 counterpart—we saw a threefold speedup on one example.
92 <sect2 id="unboxed-tuples">
97 Unboxed tuples aren't really exported by <literal>GHC.Exts</literal>,
98 they're available by default with <option>-fglasgow-exts</option>. An
99 unboxed tuple looks like this:
111 where <literal>e_1..e_n</literal> are expressions of any
112 type (primitive or non-primitive). The type of an unboxed tuple looks
117 Unboxed tuples are used for functions that need to return multiple
118 values, but they avoid the heap allocation normally associated with
119 using fully-fledged tuples. When an unboxed tuple is returned, the
120 components are put directly into registers or on the stack; the
121 unboxed tuple itself does not have a composite representation. Many
122 of the primitive operations listed in this section return unboxed
127 There are some pretty stringent restrictions on the use of unboxed tuples:
136 Unboxed tuple types are subject to the same restrictions as
137 other unboxed types; i.e. they may not be stored in polymorphic data
138 structures or passed to polymorphic functions.
145 Unboxed tuples may only be constructed as the direct result of
146 a function, and may only be deconstructed with a <literal>case</literal> expression.
147 eg. the following are valid:
151 f x y = (# x+1, y-1 #)
152 g x = case f x x of { (# a, b #) -> a + b }
156 but the following are invalid:
170 No variable can have an unboxed tuple type. This is illegal:
174 f :: (# Int, Int #) -> (# Int, Int #)
179 because <literal>x</literal> has an unboxed tuple type.
189 Note: we may relax some of these restrictions in the future.
193 The <literal>IO</literal> and <literal>ST</literal> monads use unboxed
194 tuples to avoid unnecessary allocation during sequences of operations.
200 <title>Character and numeric types</title>
202 <indexterm><primary>character types, primitive</primary></indexterm>
203 <indexterm><primary>numeric types, primitive</primary></indexterm>
204 <indexterm><primary>integer types, primitive</primary></indexterm>
205 <indexterm><primary>floating point types, primitive</primary></indexterm>
207 There are the following obvious primitive types:
221 <indexterm><primary><literal>Char#</literal></primary></indexterm>
222 <indexterm><primary><literal>Int#</literal></primary></indexterm>
223 <indexterm><primary><literal>Word#</literal></primary></indexterm>
224 <indexterm><primary><literal>Addr#</literal></primary></indexterm>
225 <indexterm><primary><literal>Float#</literal></primary></indexterm>
226 <indexterm><primary><literal>Double#</literal></primary></indexterm>
227 <indexterm><primary><literal>Int64#</literal></primary></indexterm>
228 <indexterm><primary><literal>Word64#</literal></primary></indexterm>
231 If you really want to know their exact equivalents in C, see
232 <filename>ghc/includes/StgTypes.h</filename> in the GHC source tree.
236 Literals for these types may be written as follows:
245 'a'# a Char#; for weird characters, use e.g. '\o<octal>'#
246 "a"# an Addr# (a `char *'); only characters '\0'..'\255' allowed
249 <indexterm><primary>literals, primitive</primary></indexterm>
250 <indexterm><primary>constants, primitive</primary></indexterm>
251 <indexterm><primary>numbers, primitive</primary></indexterm>
257 <title>Comparison operations</title>
260 <indexterm><primary>comparisons, primitive</primary></indexterm>
261 <indexterm><primary>operators, comparison</primary></indexterm>
267 {>,>=,==,/=,<,<=}# :: Int# -> Int# -> Bool
269 {gt,ge,eq,ne,lt,le}Char# :: Char# -> Char# -> Bool
270 -- ditto for Word# and Addr#
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><=#</literal></primary></indexterm>
279 <indexterm><primary><literal>gt{Char,Word,Addr}#</literal></primary></indexterm>
280 <indexterm><primary><literal>ge{Char,Word,Addr}#</literal></primary></indexterm>
281 <indexterm><primary><literal>eq{Char,Word,Addr}#</literal></primary></indexterm>
282 <indexterm><primary><literal>ne{Char,Word,Addr}#</literal></primary></indexterm>
283 <indexterm><primary><literal>lt{Char,Word,Addr}#</literal></primary></indexterm>
284 <indexterm><primary><literal>le{Char,Word,Addr}#</literal></primary></indexterm>
290 <title>Primitive-character operations</title>
293 <indexterm><primary>characters, primitive operations</primary></indexterm>
294 <indexterm><primary>operators, primitive character</primary></indexterm>
300 ord# :: Char# -> Int#
301 chr# :: Int# -> Char#
304 <indexterm><primary><literal>ord#</literal></primary></indexterm>
305 <indexterm><primary><literal>chr#</literal></primary></indexterm>
311 <title>Primitive-<literal>Int</literal> operations</title>
314 <indexterm><primary>integers, primitive operations</primary></indexterm>
315 <indexterm><primary>operators, primitive integer</primary></indexterm>
321 {+,-,*,quotInt,remInt,gcdInt}# :: Int# -> Int# -> Int#
322 negateInt# :: Int# -> Int#
324 iShiftL#, iShiftRA#, iShiftRL# :: Int# -> Int# -> Int#
325 -- shift left, right arithmetic, right logical
327 addIntC#, subIntC#, mulIntC# :: Int# -> Int# -> (# Int#, Int# #)
328 -- add, subtract, multiply with carry
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>quotInt#</literal></primary></indexterm>
335 <indexterm><primary><literal>remInt#</literal></primary></indexterm>
336 <indexterm><primary><literal>gcdInt#</literal></primary></indexterm>
337 <indexterm><primary><literal>iShiftL#</literal></primary></indexterm>
338 <indexterm><primary><literal>iShiftRA#</literal></primary></indexterm>
339 <indexterm><primary><literal>iShiftRL#</literal></primary></indexterm>
340 <indexterm><primary><literal>addIntC#</literal></primary></indexterm>
341 <indexterm><primary><literal>subIntC#</literal></primary></indexterm>
342 <indexterm><primary><literal>mulIntC#</literal></primary></indexterm>
343 <indexterm><primary>shift operations, integer</primary></indexterm>
347 <emphasis>Note:</emphasis> No error/overflow checking!
353 <title>Primitive-<literal>Double</literal> and <literal>Float</literal> operations</title>
356 <indexterm><primary>floating point numbers, primitive</primary></indexterm>
357 <indexterm><primary>operators, primitive floating point</primary></indexterm>
363 {+,-,*,/}## :: Double# -> Double# -> Double#
364 {<,<=,==,/=,>=,>}## :: Double# -> Double# -> Bool
365 negateDouble# :: Double# -> Double#
366 double2Int# :: Double# -> Int#
367 int2Double# :: Int# -> Double#
369 {plus,minus,times,divide}Float# :: Float# -> Float# -> Float#
370 {gt,ge,eq,ne,lt,le}Float# :: Float# -> Float# -> Bool
371 negateFloat# :: Float# -> Float#
372 float2Int# :: Float# -> Int#
373 int2Float# :: Int# -> Float#
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>>##</literal></primary></indexterm>
389 <indexterm><primary><literal>negateDouble#</literal></primary></indexterm>
390 <indexterm><primary><literal>double2Int#</literal></primary></indexterm>
391 <indexterm><primary><literal>int2Double#</literal></primary></indexterm>
395 <indexterm><primary><literal>plusFloat#</literal></primary></indexterm>
396 <indexterm><primary><literal>minusFloat#</literal></primary></indexterm>
397 <indexterm><primary><literal>timesFloat#</literal></primary></indexterm>
398 <indexterm><primary><literal>divideFloat#</literal></primary></indexterm>
399 <indexterm><primary><literal>gtFloat#</literal></primary></indexterm>
400 <indexterm><primary><literal>geFloat#</literal></primary></indexterm>
401 <indexterm><primary><literal>eqFloat#</literal></primary></indexterm>
402 <indexterm><primary><literal>neFloat#</literal></primary></indexterm>
403 <indexterm><primary><literal>ltFloat#</literal></primary></indexterm>
404 <indexterm><primary><literal>leFloat#</literal></primary></indexterm>
405 <indexterm><primary><literal>negateFloat#</literal></primary></indexterm>
406 <indexterm><primary><literal>float2Int#</literal></primary></indexterm>
407 <indexterm><primary><literal>int2Float#</literal></primary></indexterm>
411 And a full complement of trigonometric functions:
417 expDouble# :: Double# -> Double#
418 logDouble# :: Double# -> Double#
419 sqrtDouble# :: Double# -> Double#
420 sinDouble# :: Double# -> Double#
421 cosDouble# :: Double# -> Double#
422 tanDouble# :: Double# -> Double#
423 asinDouble# :: Double# -> Double#
424 acosDouble# :: Double# -> Double#
425 atanDouble# :: Double# -> Double#
426 sinhDouble# :: Double# -> Double#
427 coshDouble# :: Double# -> Double#
428 tanhDouble# :: Double# -> Double#
429 powerDouble# :: Double# -> Double# -> Double#
432 <indexterm><primary>trigonometric functions, primitive</primary></indexterm>
436 similarly for <literal>Float#</literal>.
440 There are two coercion functions for <literal>Float#</literal>/<literal>Double#</literal>:
446 float2Double# :: Float# -> Double#
447 double2Float# :: Double# -> Float#
450 <indexterm><primary><literal>float2Double#</literal></primary></indexterm>
451 <indexterm><primary><literal>double2Float#</literal></primary></indexterm>
455 The primitive version of <function>decodeDouble</function>
456 (<function>encodeDouble</function> is implemented as an external C
463 decodeDouble# :: Double# -> PrelNum.ReturnIntAndGMP
466 <indexterm><primary><literal>encodeDouble#</literal></primary></indexterm>
467 <indexterm><primary><literal>decodeDouble#</literal></primary></indexterm>
471 (And the same for <literal>Float#</literal>s.)
476 <sect2 id="integer-operations">
477 <title>Operations on/for <literal>Integers</literal> (interface to GMP)
481 <indexterm><primary>arbitrary precision integers</primary></indexterm>
482 <indexterm><primary>Integer, operations on</primary></indexterm>
486 We implement <literal>Integers</literal> (arbitrary-precision
487 integers) using the GNU multiple-precision (GMP) package (version
492 The data type for <literal>Integer</literal> is either a small
493 integer, represented by an <literal>Int</literal>, or a large integer
494 represented using the pieces required by GMP's
495 <literal>MP_INT</literal> in <filename>gmp.h</filename> (see
496 <filename>gmp.info</filename> in
497 <filename>ghc/includes/runtime/gmp</filename>). It comes out as:
503 data Integer = S# Int# -- small integers
504 | J# Int# ByteArray# -- large integers
507 <indexterm><primary>Integer type</primary></indexterm> The primitive
508 ops to support large <literal>Integers</literal> use the
509 “pieces” of the representation, and are as follows:
515 negateInteger# :: Int# -> ByteArray# -> Integer
517 {plus,minus,times}Integer#, gcdInteger#,
518 quotInteger#, remInteger#, divExactInteger#
519 :: Int# -> ByteArray#
520 -> Int# -> ByteArray#
521 -> (# Int#, ByteArray# #)
524 :: Int# -> ByteArray#
525 -> Int# -> ByteArray#
526 -> Int# -- -1 for <; 0 for ==; +1 for >
529 :: Int# -> ByteArray#
531 -> Int# -- -1 for <; 0 for ==; +1 for >
534 :: Int# -> ByteArray#
538 divModInteger#, quotRemInteger#
539 :: Int# -> ByteArray#
540 -> Int# -> ByteArray#
541 -> (# Int#, ByteArray#,
544 integer2Int# :: Int# -> ByteArray# -> Int#
546 int2Integer# :: Int# -> Integer -- NB: no error-checking on these two!
547 word2Integer# :: Word# -> Integer
549 addr2Integer# :: Addr# -> Integer
550 -- the Addr# is taken to be a `char *' string
551 -- to be converted into an Integer.
554 <indexterm><primary><literal>negateInteger#</literal></primary></indexterm>
555 <indexterm><primary><literal>plusInteger#</literal></primary></indexterm>
556 <indexterm><primary><literal>minusInteger#</literal></primary></indexterm>
557 <indexterm><primary><literal>timesInteger#</literal></primary></indexterm>
558 <indexterm><primary><literal>quotInteger#</literal></primary></indexterm>
559 <indexterm><primary><literal>remInteger#</literal></primary></indexterm>
560 <indexterm><primary><literal>gcdInteger#</literal></primary></indexterm>
561 <indexterm><primary><literal>gcdIntegerInt#</literal></primary></indexterm>
562 <indexterm><primary><literal>divExactInteger#</literal></primary></indexterm>
563 <indexterm><primary><literal>cmpInteger#</literal></primary></indexterm>
564 <indexterm><primary><literal>divModInteger#</literal></primary></indexterm>
565 <indexterm><primary><literal>quotRemInteger#</literal></primary></indexterm>
566 <indexterm><primary><literal>integer2Int#</literal></primary></indexterm>
567 <indexterm><primary><literal>int2Integer#</literal></primary></indexterm>
568 <indexterm><primary><literal>word2Integer#</literal></primary></indexterm>
569 <indexterm><primary><literal>addr2Integer#</literal></primary></indexterm>
575 <title>Words and addresses</title>
578 <indexterm><primary>word, primitive type</primary></indexterm>
579 <indexterm><primary>address, primitive type</primary></indexterm>
580 <indexterm><primary>unsigned integer, primitive type</primary></indexterm>
581 <indexterm><primary>pointer, primitive type</primary></indexterm>
585 A <literal>Word#</literal> is used for bit-twiddling operations.
586 It is the same size as an <literal>Int#</literal>, but has no sign
587 nor any arithmetic operations.
590 type Word# -- Same size/etc as Int# but *unsigned*
591 type Addr# -- A pointer from outside the "Haskell world" (from C, probably);
592 -- described under "arrays"
595 <indexterm><primary><literal>Word#</literal></primary></indexterm>
596 <indexterm><primary><literal>Addr#</literal></primary></indexterm>
600 <literal>Word#</literal>s and <literal>Addr#</literal>s have
601 the usual comparison operations. Other
602 unboxed-<literal>Word</literal> ops (bit-twiddling and coercions):
608 {gt,ge,eq,ne,lt,le}Word# :: Word# -> Word# -> Bool
610 and#, or#, xor# :: Word# -> Word# -> Word#
613 quotWord#, remWord# :: Word# -> Word# -> Word#
614 -- word (i.e. unsigned) versions are different from int
615 -- versions, so we have to provide these explicitly.
617 not# :: Word# -> Word#
619 shiftL#, shiftRL# :: Word# -> Int# -> Word#
620 -- shift left, right logical
622 int2Word# :: Int# -> Word# -- just a cast, really
623 word2Int# :: Word# -> Int#
626 <indexterm><primary>bit operations, Word and Addr</primary></indexterm>
627 <indexterm><primary><literal>gtWord#</literal></primary></indexterm>
628 <indexterm><primary><literal>geWord#</literal></primary></indexterm>
629 <indexterm><primary><literal>eqWord#</literal></primary></indexterm>
630 <indexterm><primary><literal>neWord#</literal></primary></indexterm>
631 <indexterm><primary><literal>ltWord#</literal></primary></indexterm>
632 <indexterm><primary><literal>leWord#</literal></primary></indexterm>
633 <indexterm><primary><literal>and#</literal></primary></indexterm>
634 <indexterm><primary><literal>or#</literal></primary></indexterm>
635 <indexterm><primary><literal>xor#</literal></primary></indexterm>
636 <indexterm><primary><literal>not#</literal></primary></indexterm>
637 <indexterm><primary><literal>quotWord#</literal></primary></indexterm>
638 <indexterm><primary><literal>remWord#</literal></primary></indexterm>
639 <indexterm><primary><literal>shiftL#</literal></primary></indexterm>
640 <indexterm><primary><literal>shiftRA#</literal></primary></indexterm>
641 <indexterm><primary><literal>shiftRL#</literal></primary></indexterm>
642 <indexterm><primary><literal>int2Word#</literal></primary></indexterm>
643 <indexterm><primary><literal>word2Int#</literal></primary></indexterm>
647 Unboxed-<literal>Addr</literal> ops (C casts, really):
650 {gt,ge,eq,ne,lt,le}Addr# :: Addr# -> Addr# -> Bool
652 int2Addr# :: Int# -> Addr#
653 addr2Int# :: Addr# -> Int#
654 addr2Integer# :: Addr# -> (# Int#, ByteArray# #)
657 <indexterm><primary><literal>gtAddr#</literal></primary></indexterm>
658 <indexterm><primary><literal>geAddr#</literal></primary></indexterm>
659 <indexterm><primary><literal>eqAddr#</literal></primary></indexterm>
660 <indexterm><primary><literal>neAddr#</literal></primary></indexterm>
661 <indexterm><primary><literal>ltAddr#</literal></primary></indexterm>
662 <indexterm><primary><literal>leAddr#</literal></primary></indexterm>
663 <indexterm><primary><literal>int2Addr#</literal></primary></indexterm>
664 <indexterm><primary><literal>addr2Int#</literal></primary></indexterm>
665 <indexterm><primary><literal>addr2Integer#</literal></primary></indexterm>
669 The casts between <literal>Int#</literal>,
670 <literal>Word#</literal> and <literal>Addr#</literal>
671 correspond to null operations at the machine level, but are required
672 to keep the Haskell type checker happy.
676 Operations for indexing off of C pointers
677 (<literal>Addr#</literal>s) to snatch values are listed under
678 “arrays”.
684 <title>Arrays</title>
687 <indexterm><primary>arrays, primitive</primary></indexterm>
691 The type <literal>Array# elt</literal> is the type of primitive,
692 unpointed arrays of values of type <literal>elt</literal>.
701 <indexterm><primary><literal>Array#</literal></primary></indexterm>
705 <literal>Array#</literal> is more primitive than a Haskell
706 array—indeed, the Haskell <literal>Array</literal> interface is
707 implemented using <literal>Array#</literal>—in that an
708 <literal>Array#</literal> is indexed only by
709 <literal>Int#</literal>s, starting at zero. It is also more
710 primitive by virtue of being unboxed. That doesn't mean that it isn't
711 a heap-allocated object—of course, it is. Rather, being unboxed
712 means that it is represented by a pointer to the array itself, and not
713 to a thunk which will evaluate to the array (or to bottom). The
714 components of an <literal>Array#</literal> are themselves boxed.
718 The type <literal>ByteArray#</literal> is similar to
719 <literal>Array#</literal>, except that it contains just a string
720 of (non-pointer) bytes.
729 <indexterm><primary><literal>ByteArray#</literal></primary></indexterm>
733 Arrays of these types are useful when a Haskell program wishes to
734 construct a value to pass to a C procedure. It is also possible to use
735 them to build (say) arrays of unboxed characters for internal use in a
736 Haskell program. Given these uses, <literal>ByteArray#</literal>
737 is deliberately a bit vague about the type of its components.
738 Operations are provided to extract values of type
739 <literal>Char#</literal>, <literal>Int#</literal>,
740 <literal>Float#</literal>, <literal>Double#</literal>, and
741 <literal>Addr#</literal> from arbitrary offsets within a
742 <literal>ByteArray#</literal>. (For type
743 <literal>Foo#</literal>, the $i$th offset gets you the $i$th
744 <literal>Foo#</literal>, not the <literal>Foo#</literal> at
745 byte-position $i$. Mumble.) (If you want a
746 <literal>Word#</literal>, grab an <literal>Int#</literal>,
751 Lastly, we have static byte-arrays, of type
752 <literal>Addr#</literal> [mentioned previously]. (Remember
753 the duality between arrays and pointers in C.) Arrays of this types
754 are represented by a pointer to an array in the world outside Haskell,
755 so this pointer is not followed by the garbage collector. In other
756 respects they are just like <literal>ByteArray#</literal>. They
757 are only needed in order to pass values from C to Haskell.
763 <title>Reading and writing</title>
766 Primitive arrays are linear, and indexed starting at zero.
770 The size and indices of a <literal>ByteArray#</literal>, <literal>Addr#</literal>, and
771 <literal>MutableByteArray#</literal> are all in bytes. It's up to the program to
772 calculate the correct byte offset from the start of the array. This
773 allows a <literal>ByteArray#</literal> to contain a mixture of values of different
774 type, which is often needed when preparing data for and unpicking
775 results from C. (Umm…not true of indices…WDP 95/09)
779 <emphasis>Should we provide some <literal>sizeOfDouble#</literal> constants?</emphasis>
783 Out-of-range errors on indexing should be caught by the code which
784 uses the primitive operation; the primitive operations themselves do
785 <emphasis>not</emphasis> check for out-of-range indexes. The intention is that the
786 primitive ops compile to one machine instruction or thereabouts.
790 We use the terms “reading” and “writing” to refer to accessing
791 <emphasis>mutable</emphasis> arrays (see <xref linkend="sect-mutable">), and
792 “indexing” to refer to reading a value from an <emphasis>immutable</emphasis>
797 Immutable byte arrays are straightforward to index (all indices are in
798 units of the size of the object being read):
801 indexCharArray# :: ByteArray# -> Int# -> Char#
802 indexIntArray# :: ByteArray# -> Int# -> Int#
803 indexAddrArray# :: ByteArray# -> Int# -> Addr#
804 indexFloatArray# :: ByteArray# -> Int# -> Float#
805 indexDoubleArray# :: ByteArray# -> Int# -> Double#
807 indexCharOffAddr# :: Addr# -> Int# -> Char#
808 indexIntOffAddr# :: Addr# -> Int# -> Int#
809 indexFloatOffAddr# :: Addr# -> Int# -> Float#
810 indexDoubleOffAddr# :: Addr# -> Int# -> Double#
811 indexAddrOffAddr# :: Addr# -> Int# -> Addr#
812 -- Get an Addr# from an Addr# offset
815 <indexterm><primary><literal>indexCharArray#</literal></primary></indexterm>
816 <indexterm><primary><literal>indexIntArray#</literal></primary></indexterm>
817 <indexterm><primary><literal>indexAddrArray#</literal></primary></indexterm>
818 <indexterm><primary><literal>indexFloatArray#</literal></primary></indexterm>
819 <indexterm><primary><literal>indexDoubleArray#</literal></primary></indexterm>
820 <indexterm><primary><literal>indexCharOffAddr#</literal></primary></indexterm>
821 <indexterm><primary><literal>indexIntOffAddr#</literal></primary></indexterm>
822 <indexterm><primary><literal>indexFloatOffAddr#</literal></primary></indexterm>
823 <indexterm><primary><literal>indexDoubleOffAddr#</literal></primary></indexterm>
824 <indexterm><primary><literal>indexAddrOffAddr#</literal></primary></indexterm>
828 The last of these, <function>indexAddrOffAddr#</function>, extracts an <literal>Addr#</literal> using an offset
829 from another <literal>Addr#</literal>, thereby providing the ability to follow a chain of
834 Something a bit more interesting goes on when indexing arrays of boxed
835 objects, because the result is simply the boxed object. So presumably
836 it should be entered—we never usually return an unevaluated
837 object! This is a pain: primitive ops aren't supposed to do
838 complicated things like enter objects. The current solution is to
839 return a single element unboxed tuple (see <xref linkend="unboxed-tuples">).
845 indexArray# :: Array# elt -> Int# -> (# elt #)
848 <indexterm><primary><literal>indexArray#</literal></primary></indexterm>
854 <title>The state type</title>
857 <indexterm><primary><literal>state, primitive type</literal></primary></indexterm>
858 <indexterm><primary><literal>State#</literal></primary></indexterm>
862 The primitive type <literal>State#</literal> represents the state of a state
863 transformer. It is parameterised on the desired type of state, which
864 serves to keep states from distinct threads distinct from one another.
865 But the <emphasis>only</emphasis> effect of this parameterisation is in the type
866 system: all values of type <literal>State#</literal> are represented in the same way.
867 Indeed, they are all represented by nothing at all! The code
868 generator “knows” to generate no code, and allocate no registers
869 etc, for primitive states.
881 The type <literal>GHC.RealWorld</literal> is truly opaque: there are no values defined
882 of this type, and no operations over it. It is “primitive” in that
883 sense - but it is <emphasis>not unlifted!</emphasis> Its only role in life is to be
884 the type which distinguishes the <literal>IO</literal> state transformer.
898 <title>State of the world</title>
901 A single, primitive, value of type <literal>State# RealWorld</literal> is provided.
907 realWorld# :: State# RealWorld
910 <indexterm><primary>realWorld# state object</primary></indexterm>
914 (Note: in the compiler, not a <literal>PrimOp</literal>; just a mucho magic
915 <literal>Id</literal>. Exported from <literal>GHC</literal>, though).
920 <sect2 id="sect-mutable">
921 <title>Mutable arrays</title>
924 <indexterm><primary>mutable arrays</primary></indexterm>
925 <indexterm><primary>arrays, mutable</primary></indexterm>
926 Corresponding to <literal>Array#</literal> and <literal>ByteArray#</literal>, we have the types of
927 mutable versions of each. In each case, the representation is a
928 pointer to a suitable block of (mutable) heap-allocated storage.
934 type MutableArray# s elt
935 type MutableByteArray# s
938 <indexterm><primary><literal>MutableArray#</literal></primary></indexterm>
939 <indexterm><primary><literal>MutableByteArray#</literal></primary></indexterm>
943 <title>Allocation</title>
946 <indexterm><primary>mutable arrays, allocation</primary></indexterm>
947 <indexterm><primary>arrays, allocation</primary></indexterm>
948 <indexterm><primary>allocation, of mutable arrays</primary></indexterm>
952 Mutable arrays can be allocated. Only pointer-arrays are initialised;
953 arrays of non-pointers are filled in by “user code” rather than by
954 the array-allocation primitive. Reason: only the pointer case has to
955 worry about GC striking with a partly-initialised array.
961 newArray# :: Int# -> elt -> State# s -> (# State# s, MutableArray# s elt #)
963 newCharArray# :: Int# -> State# s -> (# State# s, MutableByteArray# s elt #)
964 newIntArray# :: Int# -> State# s -> (# State# s, MutableByteArray# s elt #)
965 newAddrArray# :: Int# -> State# s -> (# State# s, MutableByteArray# s elt #)
966 newFloatArray# :: Int# -> State# s -> (# State# s, MutableByteArray# s elt #)
967 newDoubleArray# :: Int# -> State# s -> (# State# s, MutableByteArray# s elt #)
970 <indexterm><primary><literal>newArray#</literal></primary></indexterm>
971 <indexterm><primary><literal>newCharArray#</literal></primary></indexterm>
972 <indexterm><primary><literal>newIntArray#</literal></primary></indexterm>
973 <indexterm><primary><literal>newAddrArray#</literal></primary></indexterm>
974 <indexterm><primary><literal>newFloatArray#</literal></primary></indexterm>
975 <indexterm><primary><literal>newDoubleArray#</literal></primary></indexterm>
979 The size of a <literal>ByteArray#</literal> is given in bytes.
985 <title>Reading and writing</title>
988 <indexterm><primary>arrays, reading and writing</primary></indexterm>
994 readArray# :: MutableArray# s elt -> Int# -> State# s -> (# State# s, elt #)
995 readCharArray# :: MutableByteArray# s -> Int# -> State# s -> (# State# s, Char# #)
996 readIntArray# :: MutableByteArray# s -> Int# -> State# s -> (# State# s, Int# #)
997 readAddrArray# :: MutableByteArray# s -> Int# -> State# s -> (# State# s, Addr# #)
998 readFloatArray# :: MutableByteArray# s -> Int# -> State# s -> (# State# s, Float# #)
999 readDoubleArray# :: MutableByteArray# s -> Int# -> State# s -> (# State# s, Double# #)
1001 writeArray# :: MutableArray# s elt -> Int# -> elt -> State# s -> State# s
1002 writeCharArray# :: MutableByteArray# s -> Int# -> Char# -> State# s -> State# s
1003 writeIntArray# :: MutableByteArray# s -> Int# -> Int# -> State# s -> State# s
1004 writeAddrArray# :: MutableByteArray# s -> Int# -> Addr# -> State# s -> State# s
1005 writeFloatArray# :: MutableByteArray# s -> Int# -> Float# -> State# s -> State# s
1006 writeDoubleArray# :: MutableByteArray# s -> Int# -> Double# -> State# s -> State# s
1009 <indexterm><primary><literal>readArray#</literal></primary></indexterm>
1010 <indexterm><primary><literal>readCharArray#</literal></primary></indexterm>
1011 <indexterm><primary><literal>readIntArray#</literal></primary></indexterm>
1012 <indexterm><primary><literal>readAddrArray#</literal></primary></indexterm>
1013 <indexterm><primary><literal>readFloatArray#</literal></primary></indexterm>
1014 <indexterm><primary><literal>readDoubleArray#</literal></primary></indexterm>
1015 <indexterm><primary><literal>writeArray#</literal></primary></indexterm>
1016 <indexterm><primary><literal>writeCharArray#</literal></primary></indexterm>
1017 <indexterm><primary><literal>writeIntArray#</literal></primary></indexterm>
1018 <indexterm><primary><literal>writeAddrArray#</literal></primary></indexterm>
1019 <indexterm><primary><literal>writeFloatArray#</literal></primary></indexterm>
1020 <indexterm><primary><literal>writeDoubleArray#</literal></primary></indexterm>
1026 <title>Equality</title>
1029 <indexterm><primary>arrays, testing for equality</primary></indexterm>
1033 One can take “equality” of mutable arrays. What is compared is the
1034 <emphasis>name</emphasis> or reference to the mutable array, not its contents.
1040 sameMutableArray# :: MutableArray# s elt -> MutableArray# s elt -> Bool
1041 sameMutableByteArray# :: MutableByteArray# s -> MutableByteArray# s -> Bool
1044 <indexterm><primary><literal>sameMutableArray#</literal></primary></indexterm>
1045 <indexterm><primary><literal>sameMutableByteArray#</literal></primary></indexterm>
1051 <title>Freezing mutable arrays</title>
1054 <indexterm><primary>arrays, freezing mutable</primary></indexterm>
1055 <indexterm><primary>freezing mutable arrays</primary></indexterm>
1056 <indexterm><primary>mutable arrays, freezing</primary></indexterm>
1060 Only unsafe-freeze has a primitive. (Safe freeze is done directly in Haskell
1061 by copying the array and then using <function>unsafeFreeze</function>.)
1067 unsafeFreezeArray# :: MutableArray# s elt -> State# s -> (# State# s, Array# s elt #)
1068 unsafeFreezeByteArray# :: MutableByteArray# s -> State# s -> (# State# s, ByteArray# #)
1071 <indexterm><primary><literal>unsafeFreezeArray#</literal></primary></indexterm>
1072 <indexterm><primary><literal>unsafeFreezeByteArray#</literal></primary></indexterm>
1080 <title>Synchronizing variables (M-vars)</title>
1083 <indexterm><primary>synchronising variables (M-vars)</primary></indexterm>
1084 <indexterm><primary>M-Vars</primary></indexterm>
1088 Synchronising variables are the primitive type used to implement
1089 Concurrent Haskell's MVars (see the Concurrent Haskell paper for
1090 the operational behaviour of these operations).
1096 type MVar# s elt -- primitive
1098 newMVar# :: State# s -> (# State# s, MVar# s elt #)
1099 takeMVar# :: SynchVar# s elt -> State# s -> (# State# s, elt #)
1100 putMVar# :: SynchVar# s elt -> State# s -> State# s
1103 <indexterm><primary><literal>SynchVar#</literal></primary></indexterm>
1104 <indexterm><primary><literal>newSynchVar#</literal></primary></indexterm>
1105 <indexterm><primary><literal>takeMVar</literal></primary></indexterm>
1106 <indexterm><primary><literal>putMVar</literal></primary></indexterm>
1111 <sect2 id="glasgow-prim-arrays">
1112 <title>Primitive arrays, mutable and otherwise
1116 <indexterm><primary>primitive arrays (Glasgow extension)</primary></indexterm>
1117 <indexterm><primary>arrays, primitive (Glasgow extension)</primary></indexterm>
1121 GHC knows about quite a few flavours of Large Swathes of Bytes.
1125 First, GHC distinguishes between primitive arrays of (boxed) Haskell
1126 objects (type <literal>Array# obj</literal>) and primitive arrays of bytes (type
1127 <literal>ByteArray#</literal>).
1131 Second, it distinguishes between…
1135 <term>Immutable:</term>
1138 Arrays that do not change (as with “standard” Haskell arrays); you
1139 can only read from them. Obviously, they do not need the care and
1140 attention of the state-transformer monad.
1145 <term>Mutable:</term>
1148 Arrays that may be changed or “mutated.” All the operations on them
1149 live within the state-transformer monad and the updates happen
1150 <emphasis>in-place</emphasis>.
1155 <term>“Static” (in C land):</term>
1158 A C routine may pass an <literal>Addr#</literal> pointer back into Haskell land. There
1159 are then primitive operations with which you may merrily grab values
1160 over in C land, by indexing off the “static” pointer.
1165 <term>“Stable” pointers:</term>
1168 If, for some reason, you wish to hand a Haskell pointer (i.e.,
1169 <emphasis>not</emphasis> an unboxed value) to a C routine, you first make the
1170 pointer “stable,” so that the garbage collector won't forget that it
1171 exists. That is, GHC provides a safe way to pass Haskell pointers to
1176 Please see the module <literal>Foreign.StablePtr</literal> in the
1177 library documentation for more details.
1182 <term>“Foreign objects”:</term>
1185 A “foreign object” is a safe way to pass an external object (a
1186 C-allocated pointer, say) to Haskell and have Haskell do the Right
1187 Thing when it no longer references the object. So, for example, C
1188 could pass a large bitmap over to Haskell and say “please free this
1189 memory when you're done with it.”
1193 Please see module <literal>Foreign.ForeignPtr</literal> in the library
1194 documentatation for more details.
1202 The libraries documentatation gives more details on all these
1203 “primitive array” types and the operations on them.
1211 ;;; Local Variables: ***
1213 ;;; sgml-parent-document: ("users_guide.xml" "book" "chapter" "sect1") ***