1 -----------------------------------------------------------------------
3 -- (c) 2010 The University of Glasgow
5 -- Primitive Operations and Types
7 -- For more information on PrimOps, see
8 -- http://hackage.haskell.org/trac/ghc/wiki/Commentary/PrimOps
10 -----------------------------------------------------------------------
12 -- This file is processed by the utility program genprimopcode to produce
13 -- a number of include files within the compiler and optionally to produce
14 -- human-readable documentation.
16 -- It should first be preprocessed.
18 -- Information on how PrimOps are implemented and the steps necessary to
19 -- add a new one can be found in the Commentary:
21 -- http://hackage.haskell.org/trac/ghc/wiki/Commentary/PrimOps
23 -- This file is divided into named sections, each containing or more
24 -- primop entries. Section headers have the format:
26 -- section "section-name" {description}
28 -- This information is used solely when producing documentation; it is
29 -- otherwise ignored. The description is optional.
31 -- The format of each primop entry is as follows:
33 -- primop internal-name "name-in-program-text" type category {description} attributes
35 -- The default attribute values which apply if you don't specify
36 -- other ones. Attribute values can be True, False, or arbitrary
37 -- text between curly brackets. This is a kludge to enable
38 -- processors of this file to easily get hold of simple info
39 -- (eg, out_of_line), whilst avoiding parsing complex expressions
40 -- needed for strictness info.
43 has_side_effects = False
46 code_size = { primOpCodeSizeDefault }
48 strictness = { \ arity -> mkStrictSig (mkTopDmdType (replicate arity lazyDmd) TopRes) }
50 -- Currently, documentation is produced using latex, so contents of
51 -- description fields should be legal latex. Descriptions can contain
52 -- matched pairs of embedded curly brackets.
56 -- We need platform defines (tests for mingw32 below). However, we only
57 -- test the TARGET platform, which doesn't vary between stages, so the
58 -- stage1 platform defines are fine:
59 #include "../stage1/ghc_boot_platform.h"
61 section "The word size story."
62 {Haskell98 specifies that signed integers (type {\tt Int})
63 must contain at least 30 bits. GHC always implements {\tt
64 Int} using the primitive type {\tt Int\#}, whose size equals
65 the {\tt MachDeps.h} constant {\tt WORD\_SIZE\_IN\_BITS}.
66 This is normally set based on the {\tt config.h} parameter
67 {\tt SIZEOF\_HSWORD}, i.e., 32 bits on 32-bit machines, 64
68 bits on 64-bit machines. However, it can also be explicitly
69 set to a smaller number, e.g., 31 bits, to allow the
70 possibility of using tag bits. Currently GHC itself has only
71 32-bit and 64-bit variants, but 30 or 31-bit code can be
72 exported as an external core file for use in other back ends.
74 GHC also implements a primitive unsigned integer type {\tt
75 Word\#} which always has the same number of bits as {\tt
78 In addition, GHC supports families of explicit-sized integers
79 and words at 8, 16, 32, and 64 bits, with the usual
80 arithmetic operations, comparisons, and a range of
81 conversions. The 8-bit and 16-bit sizes are always
82 represented as {\tt Int\#} and {\tt Word\#}, and the
83 operations implemented in terms of the the primops on these
84 types, with suitable range restrictions on the results (using
85 the {\tt narrow$n$Int\#} and {\tt narrow$n$Word\#} families
86 of primops. The 32-bit sizes are represented using {\tt
87 Int\#} and {\tt Word\#} when {\tt WORD\_SIZE\_IN\_BITS}
88 $\geq$ 32; otherwise, these are represented using distinct
89 primitive types {\tt Int32\#} and {\tt Word32\#}. These (when
90 needed) have a complete set of corresponding operations;
91 however, nearly all of these are implemented as external C
92 functions rather than as primops. Exactly the same story
93 applies to the 64-bit sizes. All of these details are hidden
94 under the {\tt PrelInt} and {\tt PrelWord} modules, which use
95 {\tt \#if}-defs to invoke the appropriate types and
98 Word size also matters for the families of primops for
99 indexing/reading/writing fixed-size quantities at offsets
100 from an array base, address, or foreign pointer. Here, a
101 slightly different approach is taken. The names of these
102 primops are fixed, but their {\it types} vary according to
103 the value of {\tt WORD\_SIZE\_IN\_BITS}. For example, if word
104 size is at least 32 bits then an operator like
105 \texttt{indexInt32Array\#} has type {\tt ByteArray\# -> Int\#
106 -> Int\#}; otherwise it has type {\tt ByteArray\# -> Int\# ->
107 Int32\#}. This approach confines the necessary {\tt
108 \#if}-defs to this file; no conditional compilation is needed
109 in the files that expose these primops.
111 Finally, there are strongly deprecated primops for coercing
112 between {\tt Addr\#}, the primitive type of machine
113 addresses, and {\tt Int\#}. These are pretty bogus anyway,
114 but will work on existing 32-bit and 64-bit GHC targets; they
115 are completely bogus when tag bits are used in {\tt Int\#},
116 so are not available in this case. }
118 -- Define synonyms for indexing ops.
120 #if WORD_SIZE_IN_BITS < 32
122 #define WORD32 Word32#
128 #if WORD_SIZE_IN_BITS < 64
130 #define WORD64 Word64#
136 ------------------------------------------------------------------------
138 {Operations on 31-bit characters.}
139 ------------------------------------------------------------------------
143 primop CharGtOp "gtChar#" Compare Char# -> Char# -> Bool
144 primop CharGeOp "geChar#" Compare Char# -> Char# -> Bool
146 primop CharEqOp "eqChar#" Compare
147 Char# -> Char# -> Bool
148 with commutable = True
150 primop CharNeOp "neChar#" Compare
151 Char# -> Char# -> Bool
152 with commutable = True
154 primop CharLtOp "ltChar#" Compare Char# -> Char# -> Bool
155 primop CharLeOp "leChar#" Compare Char# -> Char# -> Bool
157 primop OrdOp "ord#" GenPrimOp Char# -> Int#
160 ------------------------------------------------------------------------
162 {Operations on native-size integers (30+ bits).}
163 ------------------------------------------------------------------------
167 primop IntAddOp "+#" Dyadic
169 with commutable = True
171 primop IntSubOp "-#" Dyadic Int# -> Int# -> Int#
174 Dyadic Int# -> Int# -> Int#
175 {Low word of signed integer multiply.}
176 with commutable = True
178 primop IntMulMayOfloOp "mulIntMayOflo#"
179 Dyadic Int# -> Int# -> Int#
180 {Return non-zero if there is any possibility that the upper word of a
181 signed integer multiply might contain useful information. Return
182 zero only if you are completely sure that no overflow can occur.
183 On a 32-bit platform, the recommmended implementation is to do a
184 32 x 32 -> 64 signed multiply, and subtract result[63:32] from
185 (result[31] >>signed 31). If this is zero, meaning that the
186 upper word is merely a sign extension of the lower one, no
189 On a 64-bit platform it is not always possible to
190 acquire the top 64 bits of the result. Therefore, a recommended
191 implementation is to take the absolute value of both operands, and
192 return 0 iff bits[63:31] of them are zero, since that means that their
193 magnitudes fit within 31 bits, so the magnitude of the product must fit
196 If in doubt, return non-zero, but do make an effort to create the
197 correct answer for small args, since otherwise the performance of
198 \texttt{(*) :: Integer -> Integer -> Integer} will be poor.
200 with commutable = True
202 primop IntQuotOp "quotInt#" Dyadic
204 {Rounds towards zero.}
207 primop IntRemOp "remInt#" Dyadic
209 {Satisfies \texttt{(quotInt\# x y) *\# y +\# (remInt\# x y) == x}.}
212 primop IntNegOp "negateInt#" Monadic Int# -> Int#
213 primop IntAddCOp "addIntC#" GenPrimOp Int# -> Int# -> (# Int#, Int# #)
214 {Add with carry. First member of result is (wrapped) sum;
215 second member is 0 iff no overflow occured.}
218 primop IntSubCOp "subIntC#" GenPrimOp Int# -> Int# -> (# Int#, Int# #)
219 {Subtract with carry. First member of result is (wrapped) difference;
220 second member is 0 iff no overflow occured.}
223 primop IntGtOp ">#" Compare Int# -> Int# -> Bool
224 primop IntGeOp ">=#" Compare Int# -> Int# -> Bool
226 primop IntEqOp "==#" Compare
228 with commutable = True
230 primop IntNeOp "/=#" Compare
232 with commutable = True
234 primop IntLtOp "<#" Compare Int# -> Int# -> Bool
235 primop IntLeOp "<=#" Compare Int# -> Int# -> Bool
237 primop ChrOp "chr#" GenPrimOp Int# -> Char#
240 primop Int2WordOp "int2Word#" GenPrimOp Int# -> Word#
243 primop Int2FloatOp "int2Float#" GenPrimOp Int# -> Float#
244 primop Int2DoubleOp "int2Double#" GenPrimOp Int# -> Double#
246 primop ISllOp "uncheckedIShiftL#" GenPrimOp Int# -> Int# -> Int#
247 {Shift left. Result undefined if shift amount is not
248 in the range 0 to word size - 1 inclusive.}
249 primop ISraOp "uncheckedIShiftRA#" GenPrimOp Int# -> Int# -> Int#
250 {Shift right arithmetic. Result undefined if shift amount is not
251 in the range 0 to word size - 1 inclusive.}
252 primop ISrlOp "uncheckedIShiftRL#" GenPrimOp Int# -> Int# -> Int#
253 {Shift right logical. Result undefined if shift amount is not
254 in the range 0 to word size - 1 inclusive.}
256 ------------------------------------------------------------------------
258 {Operations on native-sized unsigned words (30+ bits).}
259 ------------------------------------------------------------------------
263 primop WordAddOp "plusWord#" Dyadic Word# -> Word# -> Word#
264 with commutable = True
266 primop WordSubOp "minusWord#" Dyadic Word# -> Word# -> Word#
268 primop WordMulOp "timesWord#" Dyadic Word# -> Word# -> Word#
269 with commutable = True
271 primop WordQuotOp "quotWord#" Dyadic Word# -> Word# -> Word#
274 primop WordRemOp "remWord#" Dyadic Word# -> Word# -> Word#
277 primop AndOp "and#" Dyadic Word# -> Word# -> Word#
278 with commutable = True
280 primop OrOp "or#" Dyadic Word# -> Word# -> Word#
281 with commutable = True
283 primop XorOp "xor#" Dyadic Word# -> Word# -> Word#
284 with commutable = True
286 primop NotOp "not#" Monadic Word# -> Word#
288 primop SllOp "uncheckedShiftL#" GenPrimOp Word# -> Int# -> Word#
289 {Shift left logical. Result undefined if shift amount is not
290 in the range 0 to word size - 1 inclusive.}
291 primop SrlOp "uncheckedShiftRL#" GenPrimOp Word# -> Int# -> Word#
292 {Shift right logical. Result undefined if shift amount is not
293 in the range 0 to word size - 1 inclusive.}
295 primop Word2IntOp "word2Int#" GenPrimOp Word# -> Int#
298 primop WordGtOp "gtWord#" Compare Word# -> Word# -> Bool
299 primop WordGeOp "geWord#" Compare Word# -> Word# -> Bool
300 primop WordEqOp "eqWord#" Compare Word# -> Word# -> Bool
301 primop WordNeOp "neWord#" Compare Word# -> Word# -> Bool
302 primop WordLtOp "ltWord#" Compare Word# -> Word# -> Bool
303 primop WordLeOp "leWord#" Compare Word# -> Word# -> Bool
305 ------------------------------------------------------------------------
307 {Explicit narrowing of native-sized ints or words.}
308 ------------------------------------------------------------------------
310 primop Narrow8IntOp "narrow8Int#" Monadic Int# -> Int#
311 primop Narrow16IntOp "narrow16Int#" Monadic Int# -> Int#
312 primop Narrow32IntOp "narrow32Int#" Monadic Int# -> Int#
313 primop Narrow8WordOp "narrow8Word#" Monadic Word# -> Word#
314 primop Narrow16WordOp "narrow16Word#" Monadic Word# -> Word#
315 primop Narrow32WordOp "narrow32Word#" Monadic Word# -> Word#
318 #if WORD_SIZE_IN_BITS < 32
319 ------------------------------------------------------------------------
321 {Operations on 32-bit integers ({\tt Int32\#}). This type is only used
322 if plain {\tt Int\#} has less than 32 bits. In any case, the operations
323 are not primops; they are implemented (if needed) as ccalls instead.}
324 ------------------------------------------------------------------------
328 ------------------------------------------------------------------------
330 {Operations on 32-bit unsigned words. This type is only used
331 if plain {\tt Word\#} has less than 32 bits. In any case, the operations
332 are not primops; they are implemented (if needed) as ccalls instead.}
333 ------------------------------------------------------------------------
340 #if WORD_SIZE_IN_BITS < 64
341 ------------------------------------------------------------------------
343 {Operations on 64-bit unsigned words. This type is only used
344 if plain {\tt Int\#} has less than 64 bits. In any case, the operations
345 are not primops; they are implemented (if needed) as ccalls instead.}
346 ------------------------------------------------------------------------
350 ------------------------------------------------------------------------
352 {Operations on 64-bit unsigned words. This type is only used
353 if plain {\tt Word\#} has less than 64 bits. In any case, the operations
354 are not primops; they are implemented (if needed) as ccalls instead.}
355 ------------------------------------------------------------------------
361 ------------------------------------------------------------------------
363 {Operations on double-precision (64 bit) floating-point numbers.}
364 ------------------------------------------------------------------------
368 primop DoubleGtOp ">##" Compare Double# -> Double# -> Bool
369 primop DoubleGeOp ">=##" Compare Double# -> Double# -> Bool
371 primop DoubleEqOp "==##" Compare
372 Double# -> Double# -> Bool
373 with commutable = True
375 primop DoubleNeOp "/=##" Compare
376 Double# -> Double# -> Bool
377 with commutable = True
379 primop DoubleLtOp "<##" Compare Double# -> Double# -> Bool
380 primop DoubleLeOp "<=##" Compare Double# -> Double# -> Bool
382 primop DoubleAddOp "+##" Dyadic
383 Double# -> Double# -> Double#
384 with commutable = True
386 primop DoubleSubOp "-##" Dyadic Double# -> Double# -> Double#
388 primop DoubleMulOp "*##" Dyadic
389 Double# -> Double# -> Double#
390 with commutable = True
392 primop DoubleDivOp "/##" Dyadic
393 Double# -> Double# -> Double#
396 primop DoubleNegOp "negateDouble#" Monadic Double# -> Double#
398 primop Double2IntOp "double2Int#" GenPrimOp Double# -> Int#
399 {Truncates a {\tt Double#} value to the nearest {\tt Int#}.
400 Results are undefined if the truncation if truncation yields
401 a value outside the range of {\tt Int#}.}
403 primop Double2FloatOp "double2Float#" GenPrimOp Double# -> Float#
405 primop DoubleExpOp "expDouble#" Monadic
408 code_size = { primOpCodeSizeForeignCall }
410 primop DoubleLogOp "logDouble#" Monadic
413 code_size = { primOpCodeSizeForeignCall }
416 primop DoubleSqrtOp "sqrtDouble#" Monadic
419 code_size = { primOpCodeSizeForeignCall }
421 primop DoubleSinOp "sinDouble#" Monadic
424 code_size = { primOpCodeSizeForeignCall }
426 primop DoubleCosOp "cosDouble#" Monadic
429 code_size = { primOpCodeSizeForeignCall }
431 primop DoubleTanOp "tanDouble#" Monadic
434 code_size = { primOpCodeSizeForeignCall }
436 primop DoubleAsinOp "asinDouble#" Monadic
439 code_size = { primOpCodeSizeForeignCall }
442 primop DoubleAcosOp "acosDouble#" Monadic
445 code_size = { primOpCodeSizeForeignCall }
448 primop DoubleAtanOp "atanDouble#" Monadic
451 code_size = { primOpCodeSizeForeignCall }
453 primop DoubleSinhOp "sinhDouble#" Monadic
456 code_size = { primOpCodeSizeForeignCall }
458 primop DoubleCoshOp "coshDouble#" Monadic
461 code_size = { primOpCodeSizeForeignCall }
463 primop DoubleTanhOp "tanhDouble#" Monadic
466 code_size = { primOpCodeSizeForeignCall }
468 primop DoublePowerOp "**##" Dyadic
469 Double# -> Double# -> Double#
472 code_size = { primOpCodeSizeForeignCall }
474 primop DoubleDecode_2IntOp "decodeDouble_2Int#" GenPrimOp
475 Double# -> (# Int#, Word#, Word#, Int# #)
477 First component of the result is -1 or 1, indicating the sign of the
478 mantissa. The next two are the high and low 32 bits of the mantissa
479 respectively, and the last is the exponent.}
480 with out_of_line = True
482 ------------------------------------------------------------------------
484 {Operations on single-precision (32-bit) floating-point numbers.}
485 ------------------------------------------------------------------------
489 primop FloatGtOp "gtFloat#" Compare Float# -> Float# -> Bool
490 primop FloatGeOp "geFloat#" Compare Float# -> Float# -> Bool
492 primop FloatEqOp "eqFloat#" Compare
493 Float# -> Float# -> Bool
494 with commutable = True
496 primop FloatNeOp "neFloat#" Compare
497 Float# -> Float# -> Bool
498 with commutable = True
500 primop FloatLtOp "ltFloat#" Compare Float# -> Float# -> Bool
501 primop FloatLeOp "leFloat#" Compare Float# -> Float# -> Bool
503 primop FloatAddOp "plusFloat#" Dyadic
504 Float# -> Float# -> Float#
505 with commutable = True
507 primop FloatSubOp "minusFloat#" Dyadic Float# -> Float# -> Float#
509 primop FloatMulOp "timesFloat#" Dyadic
510 Float# -> Float# -> Float#
511 with commutable = True
513 primop FloatDivOp "divideFloat#" Dyadic
514 Float# -> Float# -> Float#
517 primop FloatNegOp "negateFloat#" Monadic Float# -> Float#
519 primop Float2IntOp "float2Int#" GenPrimOp Float# -> Int#
520 {Truncates a {\tt Float#} value to the nearest {\tt Int#}.
521 Results are undefined if the truncation if truncation yields
522 a value outside the range of {\tt Int#}.}
524 primop FloatExpOp "expFloat#" Monadic
527 code_size = { primOpCodeSizeForeignCall }
529 primop FloatLogOp "logFloat#" Monadic
532 code_size = { primOpCodeSizeForeignCall }
535 primop FloatSqrtOp "sqrtFloat#" Monadic
538 code_size = { primOpCodeSizeForeignCall }
540 primop FloatSinOp "sinFloat#" Monadic
543 code_size = { primOpCodeSizeForeignCall }
545 primop FloatCosOp "cosFloat#" Monadic
548 code_size = { primOpCodeSizeForeignCall }
550 primop FloatTanOp "tanFloat#" Monadic
553 code_size = { primOpCodeSizeForeignCall }
555 primop FloatAsinOp "asinFloat#" Monadic
558 code_size = { primOpCodeSizeForeignCall }
561 primop FloatAcosOp "acosFloat#" Monadic
564 code_size = { primOpCodeSizeForeignCall }
567 primop FloatAtanOp "atanFloat#" Monadic
570 code_size = { primOpCodeSizeForeignCall }
572 primop FloatSinhOp "sinhFloat#" Monadic
575 code_size = { primOpCodeSizeForeignCall }
577 primop FloatCoshOp "coshFloat#" Monadic
580 code_size = { primOpCodeSizeForeignCall }
582 primop FloatTanhOp "tanhFloat#" Monadic
585 code_size = { primOpCodeSizeForeignCall }
587 primop FloatPowerOp "powerFloat#" Dyadic
588 Float# -> Float# -> Float#
590 code_size = { primOpCodeSizeForeignCall }
592 primop Float2DoubleOp "float2Double#" GenPrimOp Float# -> Double#
594 primop FloatDecode_IntOp "decodeFloat_Int#" GenPrimOp
595 Float# -> (# Int#, Int# #)
596 {Convert to integers.
597 First {\tt Int\#} in result is the mantissa; second is the exponent.}
598 with out_of_line = True
600 ------------------------------------------------------------------------
602 {Operations on {\tt Array\#}.}
603 ------------------------------------------------------------------------
607 primtype MutableArray# s a
609 primop NewArrayOp "newArray#" GenPrimOp
610 Int# -> a -> State# s -> (# State# s, MutableArray# s a #)
611 {Create a new mutable array with the specified number of elements,
612 in the specified state thread,
613 with each element containing the specified initial value.}
616 has_side_effects = True
618 primop SameMutableArrayOp "sameMutableArray#" GenPrimOp
619 MutableArray# s a -> MutableArray# s a -> Bool
621 primop ReadArrayOp "readArray#" GenPrimOp
622 MutableArray# s a -> Int# -> State# s -> (# State# s, a #)
623 {Read from specified index of mutable array. Result is not yet evaluated.}
625 has_side_effects = True
627 primop WriteArrayOp "writeArray#" GenPrimOp
628 MutableArray# s a -> Int# -> a -> State# s -> State# s
629 {Write to specified index of mutable array.}
631 has_side_effects = True
632 code_size = 2 -- card update too
634 primop SizeofArrayOp "sizeofArray#" GenPrimOp
636 {Return the number of elements in the array.}
638 primop SizeofMutableArrayOp "sizeofMutableArray#" GenPrimOp
639 MutableArray# s a -> Int#
640 {Return the number of elements in the array.}
642 primop IndexArrayOp "indexArray#" GenPrimOp
643 Array# a -> Int# -> (# a #)
644 {Read from specified index of immutable array. Result is packaged into
645 an unboxed singleton; the result itself is not yet evaluated.}
647 primop UnsafeFreezeArrayOp "unsafeFreezeArray#" GenPrimOp
648 MutableArray# s a -> State# s -> (# State# s, Array# a #)
649 {Make a mutable array immutable, without copying.}
651 has_side_effects = True
653 primop UnsafeThawArrayOp "unsafeThawArray#" GenPrimOp
654 Array# a -> State# s -> (# State# s, MutableArray# s a #)
655 {Make an immutable array mutable, without copying.}
658 has_side_effects = True
660 primop CopyArrayOp "copyArray#" GenPrimOp
661 Array# a -> Int# -> MutableArray# s a -> Int# -> Int# -> State# s -> State# s
662 {Copy a range of the Array# to the specified region in the MutableArray#.
663 Both arrays must fully contain the specified ranges, but this is not checked.
664 The two arrays must not be the same array in different states, but this is not checked either.}
666 has_side_effects = True
667 code_size = { primOpCodeSizeForeignCall + 4 }
669 primop CopyMutableArrayOp "copyMutableArray#" GenPrimOp
670 MutableArray# s a -> Int# -> MutableArray# s a -> Int# -> Int# -> State# s -> State# s
671 {Copy a range of the first MutableArray# to the specified region in the second MutableArray#.
672 Both arrays must fully contain the specified ranges, but this is not checked.}
674 has_side_effects = True
675 code_size = { primOpCodeSizeForeignCall + 4 }
677 primop CloneArrayOp "cloneArray#" GenPrimOp
678 Array# a -> Int# -> Int# -> Array# a
679 {Return a newly allocated Array# with the specified subrange of the provided Array#.
680 The provided Array# should contain the full subrange specified by the two Int#s, but this is not checked.}
682 has_side_effects = True
683 code_size = { primOpCodeSizeForeignCall + 4 }
685 primop CloneMutableArrayOp "cloneMutableArray#" GenPrimOp
686 MutableArray# s a -> Int# -> Int# -> State# s -> (# State# s, MutableArray# s a #)
687 {Return a newly allocated Array# with the specified subrange of the provided Array#.
688 The provided MutableArray# should contain the full subrange specified by the two Int#s, but this is not checked.}
690 has_side_effects = True
691 code_size = { primOpCodeSizeForeignCall + 4 }
693 primop FreezeArrayOp "freezeArray#" GenPrimOp
694 MutableArray# s a -> Int# -> Int# -> State# s -> (# State# s, Array# a #)
695 {Return a newly allocated Array# with the specified subrange of the provided MutableArray#.
696 The provided MutableArray# should contain the full subrange specified by the two Int#s, but this is not checked.}
698 has_side_effects = True
699 code_size = { primOpCodeSizeForeignCall + 4 }
701 primop ThawArrayOp "thawArray#" GenPrimOp
702 Array# a -> Int# -> Int# -> State# s -> (# State# s, MutableArray# s a #)
703 {Return a newly allocated Array# with the specified subrange of the provided MutableArray#.
704 The provided Array# should contain the full subrange specified by the two Int#s, but this is not checked.}
706 has_side_effects = True
707 code_size = { primOpCodeSizeForeignCall + 4 }
709 ------------------------------------------------------------------------
710 section "Byte Arrays"
711 {Operations on {\tt ByteArray\#}. A {\tt ByteArray\#} is a just a region of
712 raw memory in the garbage-collected heap, which is not
713 scanned for pointers. It carries its own size (in bytes).
715 three sets of operations for accessing byte array contents:
716 index for reading from immutable byte arrays, and read/write
717 for mutable byte arrays. Each set contains operations for a
718 range of useful primitive data types. Each operation takes
719 an offset measured in terms of the size fo the primitive type
720 being read or written.}
722 ------------------------------------------------------------------------
726 primtype MutableByteArray# s
728 primop NewByteArrayOp_Char "newByteArray#" GenPrimOp
729 Int# -> State# s -> (# State# s, MutableByteArray# s #)
730 {Create a new mutable byte array of specified size (in bytes), in
731 the specified state thread.}
732 with out_of_line = True
733 has_side_effects = True
735 primop NewPinnedByteArrayOp_Char "newPinnedByteArray#" GenPrimOp
736 Int# -> State# s -> (# State# s, MutableByteArray# s #)
737 {Create a mutable byte array that the GC guarantees not to move.}
738 with out_of_line = True
739 has_side_effects = True
741 primop NewAlignedPinnedByteArrayOp_Char "newAlignedPinnedByteArray#" GenPrimOp
742 Int# -> Int# -> State# s -> (# State# s, MutableByteArray# s #)
743 {Create a mutable byte array, aligned by the specified amount, that the GC guarantees not to move.}
744 with out_of_line = True
745 has_side_effects = True
747 primop ByteArrayContents_Char "byteArrayContents#" GenPrimOp
749 {Intended for use with pinned arrays; otherwise very unsafe!}
751 primop SameMutableByteArrayOp "sameMutableByteArray#" GenPrimOp
752 MutableByteArray# s -> MutableByteArray# s -> Bool
754 primop UnsafeFreezeByteArrayOp "unsafeFreezeByteArray#" GenPrimOp
755 MutableByteArray# s -> State# s -> (# State# s, ByteArray# #)
756 {Make a mutable byte array immutable, without copying.}
758 has_side_effects = True
760 primop SizeofByteArrayOp "sizeofByteArray#" GenPrimOp
762 {Return the size of the array in bytes.}
764 primop SizeofMutableByteArrayOp "sizeofMutableByteArray#" GenPrimOp
765 MutableByteArray# s -> Int#
766 {Return the size of the array in bytes.}
768 primop IndexByteArrayOp_Char "indexCharArray#" GenPrimOp
769 ByteArray# -> Int# -> Char#
770 {Read 8-bit character; offset in bytes.}
772 primop IndexByteArrayOp_WideChar "indexWideCharArray#" GenPrimOp
773 ByteArray# -> Int# -> Char#
774 {Read 31-bit character; offset in 4-byte words.}
776 primop IndexByteArrayOp_Int "indexIntArray#" GenPrimOp
777 ByteArray# -> Int# -> Int#
779 primop IndexByteArrayOp_Word "indexWordArray#" GenPrimOp
780 ByteArray# -> Int# -> Word#
782 primop IndexByteArrayOp_Addr "indexAddrArray#" GenPrimOp
783 ByteArray# -> Int# -> Addr#
785 primop IndexByteArrayOp_Float "indexFloatArray#" GenPrimOp
786 ByteArray# -> Int# -> Float#
788 primop IndexByteArrayOp_Double "indexDoubleArray#" GenPrimOp
789 ByteArray# -> Int# -> Double#
791 primop IndexByteArrayOp_StablePtr "indexStablePtrArray#" GenPrimOp
792 ByteArray# -> Int# -> StablePtr# a
794 primop IndexByteArrayOp_Int8 "indexInt8Array#" GenPrimOp
795 ByteArray# -> Int# -> Int#
797 primop IndexByteArrayOp_Int16 "indexInt16Array#" GenPrimOp
798 ByteArray# -> Int# -> Int#
800 primop IndexByteArrayOp_Int32 "indexInt32Array#" GenPrimOp
801 ByteArray# -> Int# -> INT32
803 primop IndexByteArrayOp_Int64 "indexInt64Array#" GenPrimOp
804 ByteArray# -> Int# -> INT64
806 primop IndexByteArrayOp_Word8 "indexWord8Array#" GenPrimOp
807 ByteArray# -> Int# -> Word#
809 primop IndexByteArrayOp_Word16 "indexWord16Array#" GenPrimOp
810 ByteArray# -> Int# -> Word#
812 primop IndexByteArrayOp_Word32 "indexWord32Array#" GenPrimOp
813 ByteArray# -> Int# -> WORD32
815 primop IndexByteArrayOp_Word64 "indexWord64Array#" GenPrimOp
816 ByteArray# -> Int# -> WORD64
818 primop ReadByteArrayOp_Char "readCharArray#" GenPrimOp
819 MutableByteArray# s -> Int# -> State# s -> (# State# s, Char# #)
820 {Read 8-bit character; offset in bytes.}
821 with has_side_effects = True
823 primop ReadByteArrayOp_WideChar "readWideCharArray#" GenPrimOp
824 MutableByteArray# s -> Int# -> State# s -> (# State# s, Char# #)
825 {Read 31-bit character; offset in 4-byte words.}
826 with has_side_effects = True
828 primop ReadByteArrayOp_Int "readIntArray#" GenPrimOp
829 MutableByteArray# s -> Int# -> State# s -> (# State# s, Int# #)
830 with has_side_effects = True
832 primop ReadByteArrayOp_Word "readWordArray#" GenPrimOp
833 MutableByteArray# s -> Int# -> State# s -> (# State# s, Word# #)
834 with has_side_effects = True
836 primop ReadByteArrayOp_Addr "readAddrArray#" GenPrimOp
837 MutableByteArray# s -> Int# -> State# s -> (# State# s, Addr# #)
838 with has_side_effects = True
840 primop ReadByteArrayOp_Float "readFloatArray#" GenPrimOp
841 MutableByteArray# s -> Int# -> State# s -> (# State# s, Float# #)
842 with has_side_effects = True
844 primop ReadByteArrayOp_Double "readDoubleArray#" GenPrimOp
845 MutableByteArray# s -> Int# -> State# s -> (# State# s, Double# #)
846 with has_side_effects = True
848 primop ReadByteArrayOp_StablePtr "readStablePtrArray#" GenPrimOp
849 MutableByteArray# s -> Int# -> State# s -> (# State# s, StablePtr# a #)
850 with has_side_effects = True
852 primop ReadByteArrayOp_Int8 "readInt8Array#" GenPrimOp
853 MutableByteArray# s -> Int# -> State# s -> (# State# s, Int# #)
854 with has_side_effects = True
856 primop ReadByteArrayOp_Int16 "readInt16Array#" GenPrimOp
857 MutableByteArray# s -> Int# -> State# s -> (# State# s, Int# #)
858 with has_side_effects = True
860 primop ReadByteArrayOp_Int32 "readInt32Array#" GenPrimOp
861 MutableByteArray# s -> Int# -> State# s -> (# State# s, INT32 #)
862 with has_side_effects = True
864 primop ReadByteArrayOp_Int64 "readInt64Array#" GenPrimOp
865 MutableByteArray# s -> Int# -> State# s -> (# State# s, INT64 #)
866 with has_side_effects = True
868 primop ReadByteArrayOp_Word8 "readWord8Array#" GenPrimOp
869 MutableByteArray# s -> Int# -> State# s -> (# State# s, Word# #)
870 with has_side_effects = True
872 primop ReadByteArrayOp_Word16 "readWord16Array#" GenPrimOp
873 MutableByteArray# s -> Int# -> State# s -> (# State# s, Word# #)
874 with has_side_effects = True
876 primop ReadByteArrayOp_Word32 "readWord32Array#" GenPrimOp
877 MutableByteArray# s -> Int# -> State# s -> (# State# s, WORD32 #)
878 with has_side_effects = True
880 primop ReadByteArrayOp_Word64 "readWord64Array#" GenPrimOp
881 MutableByteArray# s -> Int# -> State# s -> (# State# s, WORD64 #)
882 with has_side_effects = True
884 primop WriteByteArrayOp_Char "writeCharArray#" GenPrimOp
885 MutableByteArray# s -> Int# -> Char# -> State# s -> State# s
886 {Write 8-bit character; offset in bytes.}
887 with has_side_effects = True
889 primop WriteByteArrayOp_WideChar "writeWideCharArray#" GenPrimOp
890 MutableByteArray# s -> Int# -> Char# -> State# s -> State# s
891 {Write 31-bit character; offset in 4-byte words.}
892 with has_side_effects = True
894 primop WriteByteArrayOp_Int "writeIntArray#" GenPrimOp
895 MutableByteArray# s -> Int# -> Int# -> State# s -> State# s
896 with has_side_effects = True
898 primop WriteByteArrayOp_Word "writeWordArray#" GenPrimOp
899 MutableByteArray# s -> Int# -> Word# -> State# s -> State# s
900 with has_side_effects = True
902 primop WriteByteArrayOp_Addr "writeAddrArray#" GenPrimOp
903 MutableByteArray# s -> Int# -> Addr# -> State# s -> State# s
904 with has_side_effects = True
906 primop WriteByteArrayOp_Float "writeFloatArray#" GenPrimOp
907 MutableByteArray# s -> Int# -> Float# -> State# s -> State# s
908 with has_side_effects = True
910 primop WriteByteArrayOp_Double "writeDoubleArray#" GenPrimOp
911 MutableByteArray# s -> Int# -> Double# -> State# s -> State# s
912 with has_side_effects = True
914 primop WriteByteArrayOp_StablePtr "writeStablePtrArray#" GenPrimOp
915 MutableByteArray# s -> Int# -> StablePtr# a -> State# s -> State# s
916 with has_side_effects = True
918 primop WriteByteArrayOp_Int8 "writeInt8Array#" GenPrimOp
919 MutableByteArray# s -> Int# -> Int# -> State# s -> State# s
920 with has_side_effects = True
922 primop WriteByteArrayOp_Int16 "writeInt16Array#" GenPrimOp
923 MutableByteArray# s -> Int# -> Int# -> State# s -> State# s
924 with has_side_effects = True
926 primop WriteByteArrayOp_Int32 "writeInt32Array#" GenPrimOp
927 MutableByteArray# s -> Int# -> INT32 -> State# s -> State# s
928 with has_side_effects = True
930 primop WriteByteArrayOp_Int64 "writeInt64Array#" GenPrimOp
931 MutableByteArray# s -> Int# -> INT64 -> State# s -> State# s
932 with has_side_effects = True
934 primop WriteByteArrayOp_Word8 "writeWord8Array#" GenPrimOp
935 MutableByteArray# s -> Int# -> Word# -> State# s -> State# s
936 with has_side_effects = True
938 primop WriteByteArrayOp_Word16 "writeWord16Array#" GenPrimOp
939 MutableByteArray# s -> Int# -> Word# -> State# s -> State# s
940 with has_side_effects = True
942 primop WriteByteArrayOp_Word32 "writeWord32Array#" GenPrimOp
943 MutableByteArray# s -> Int# -> WORD32 -> State# s -> State# s
944 with has_side_effects = True
946 primop WriteByteArrayOp_Word64 "writeWord64Array#" GenPrimOp
947 MutableByteArray# s -> Int# -> WORD64 -> State# s -> State# s
948 with has_side_effects = True
950 ------------------------------------------------------------------------
952 ------------------------------------------------------------------------
955 { An arbitrary machine address assumed to point outside
956 the garbage-collected heap. }
958 pseudoop "nullAddr#" Addr#
959 { The null address. }
961 primop AddrAddOp "plusAddr#" GenPrimOp Addr# -> Int# -> Addr#
962 primop AddrSubOp "minusAddr#" GenPrimOp Addr# -> Addr# -> Int#
963 {Result is meaningless if two {\tt Addr\#}s are so far apart that their
964 difference doesn't fit in an {\tt Int\#}.}
965 primop AddrRemOp "remAddr#" GenPrimOp Addr# -> Int# -> Int#
966 {Return the remainder when the {\tt Addr\#} arg, treated like an {\tt Int\#},
967 is divided by the {\tt Int\#} arg.}
968 #if (WORD_SIZE_IN_BITS == 32 || WORD_SIZE_IN_BITS == 64)
969 primop Addr2IntOp "addr2Int#" GenPrimOp Addr# -> Int#
970 {Coerce directly from address to int. Strongly deprecated.}
972 primop Int2AddrOp "int2Addr#" GenPrimOp Int# -> Addr#
973 {Coerce directly from int to address. Strongly deprecated.}
977 primop AddrGtOp "gtAddr#" Compare Addr# -> Addr# -> Bool
978 primop AddrGeOp "geAddr#" Compare Addr# -> Addr# -> Bool
979 primop AddrEqOp "eqAddr#" Compare Addr# -> Addr# -> Bool
980 primop AddrNeOp "neAddr#" Compare Addr# -> Addr# -> Bool
981 primop AddrLtOp "ltAddr#" Compare Addr# -> Addr# -> Bool
982 primop AddrLeOp "leAddr#" Compare Addr# -> Addr# -> Bool
984 primop IndexOffAddrOp_Char "indexCharOffAddr#" GenPrimOp
985 Addr# -> Int# -> Char#
986 {Reads 8-bit character; offset in bytes.}
988 primop IndexOffAddrOp_WideChar "indexWideCharOffAddr#" GenPrimOp
989 Addr# -> Int# -> Char#
990 {Reads 31-bit character; offset in 4-byte words.}
992 primop IndexOffAddrOp_Int "indexIntOffAddr#" GenPrimOp
993 Addr# -> Int# -> Int#
995 primop IndexOffAddrOp_Word "indexWordOffAddr#" GenPrimOp
996 Addr# -> Int# -> Word#
998 primop IndexOffAddrOp_Addr "indexAddrOffAddr#" GenPrimOp
999 Addr# -> Int# -> Addr#
1001 primop IndexOffAddrOp_Float "indexFloatOffAddr#" GenPrimOp
1002 Addr# -> Int# -> Float#
1004 primop IndexOffAddrOp_Double "indexDoubleOffAddr#" GenPrimOp
1005 Addr# -> Int# -> Double#
1007 primop IndexOffAddrOp_StablePtr "indexStablePtrOffAddr#" GenPrimOp
1008 Addr# -> Int# -> StablePtr# a
1010 primop IndexOffAddrOp_Int8 "indexInt8OffAddr#" GenPrimOp
1011 Addr# -> Int# -> Int#
1013 primop IndexOffAddrOp_Int16 "indexInt16OffAddr#" GenPrimOp
1014 Addr# -> Int# -> Int#
1016 primop IndexOffAddrOp_Int32 "indexInt32OffAddr#" GenPrimOp
1017 Addr# -> Int# -> INT32
1019 primop IndexOffAddrOp_Int64 "indexInt64OffAddr#" GenPrimOp
1020 Addr# -> Int# -> INT64
1022 primop IndexOffAddrOp_Word8 "indexWord8OffAddr#" GenPrimOp
1023 Addr# -> Int# -> Word#
1025 primop IndexOffAddrOp_Word16 "indexWord16OffAddr#" GenPrimOp
1026 Addr# -> Int# -> Word#
1028 primop IndexOffAddrOp_Word32 "indexWord32OffAddr#" GenPrimOp
1029 Addr# -> Int# -> WORD32
1031 primop IndexOffAddrOp_Word64 "indexWord64OffAddr#" GenPrimOp
1032 Addr# -> Int# -> WORD64
1034 primop ReadOffAddrOp_Char "readCharOffAddr#" GenPrimOp
1035 Addr# -> Int# -> State# s -> (# State# s, Char# #)
1036 {Reads 8-bit character; offset in bytes.}
1037 with has_side_effects = True
1039 primop ReadOffAddrOp_WideChar "readWideCharOffAddr#" GenPrimOp
1040 Addr# -> Int# -> State# s -> (# State# s, Char# #)
1041 {Reads 31-bit character; offset in 4-byte words.}
1042 with has_side_effects = True
1044 primop ReadOffAddrOp_Int "readIntOffAddr#" GenPrimOp
1045 Addr# -> Int# -> State# s -> (# State# s, Int# #)
1046 with has_side_effects = True
1048 primop ReadOffAddrOp_Word "readWordOffAddr#" GenPrimOp
1049 Addr# -> Int# -> State# s -> (# State# s, Word# #)
1050 with has_side_effects = True
1052 primop ReadOffAddrOp_Addr "readAddrOffAddr#" GenPrimOp
1053 Addr# -> Int# -> State# s -> (# State# s, Addr# #)
1054 with has_side_effects = True
1056 primop ReadOffAddrOp_Float "readFloatOffAddr#" GenPrimOp
1057 Addr# -> Int# -> State# s -> (# State# s, Float# #)
1058 with has_side_effects = True
1060 primop ReadOffAddrOp_Double "readDoubleOffAddr#" GenPrimOp
1061 Addr# -> Int# -> State# s -> (# State# s, Double# #)
1062 with has_side_effects = True
1064 primop ReadOffAddrOp_StablePtr "readStablePtrOffAddr#" GenPrimOp
1065 Addr# -> Int# -> State# s -> (# State# s, StablePtr# a #)
1066 with has_side_effects = True
1068 primop ReadOffAddrOp_Int8 "readInt8OffAddr#" GenPrimOp
1069 Addr# -> Int# -> State# s -> (# State# s, Int# #)
1070 with has_side_effects = True
1072 primop ReadOffAddrOp_Int16 "readInt16OffAddr#" GenPrimOp
1073 Addr# -> Int# -> State# s -> (# State# s, Int# #)
1074 with has_side_effects = True
1076 primop ReadOffAddrOp_Int32 "readInt32OffAddr#" GenPrimOp
1077 Addr# -> Int# -> State# s -> (# State# s, INT32 #)
1078 with has_side_effects = True
1080 primop ReadOffAddrOp_Int64 "readInt64OffAddr#" GenPrimOp
1081 Addr# -> Int# -> State# s -> (# State# s, INT64 #)
1082 with has_side_effects = True
1084 primop ReadOffAddrOp_Word8 "readWord8OffAddr#" GenPrimOp
1085 Addr# -> Int# -> State# s -> (# State# s, Word# #)
1086 with has_side_effects = True
1088 primop ReadOffAddrOp_Word16 "readWord16OffAddr#" GenPrimOp
1089 Addr# -> Int# -> State# s -> (# State# s, Word# #)
1090 with has_side_effects = True
1092 primop ReadOffAddrOp_Word32 "readWord32OffAddr#" GenPrimOp
1093 Addr# -> Int# -> State# s -> (# State# s, WORD32 #)
1094 with has_side_effects = True
1096 primop ReadOffAddrOp_Word64 "readWord64OffAddr#" GenPrimOp
1097 Addr# -> Int# -> State# s -> (# State# s, WORD64 #)
1098 with has_side_effects = True
1101 primop WriteOffAddrOp_Char "writeCharOffAddr#" GenPrimOp
1102 Addr# -> Int# -> Char# -> State# s -> State# s
1103 with has_side_effects = True
1105 primop WriteOffAddrOp_WideChar "writeWideCharOffAddr#" GenPrimOp
1106 Addr# -> Int# -> Char# -> State# s -> State# s
1107 with has_side_effects = True
1109 primop WriteOffAddrOp_Int "writeIntOffAddr#" GenPrimOp
1110 Addr# -> Int# -> Int# -> State# s -> State# s
1111 with has_side_effects = True
1113 primop WriteOffAddrOp_Word "writeWordOffAddr#" GenPrimOp
1114 Addr# -> Int# -> Word# -> State# s -> State# s
1115 with has_side_effects = True
1117 primop WriteOffAddrOp_Addr "writeAddrOffAddr#" GenPrimOp
1118 Addr# -> Int# -> Addr# -> State# s -> State# s
1119 with has_side_effects = True
1121 primop WriteOffAddrOp_Float "writeFloatOffAddr#" GenPrimOp
1122 Addr# -> Int# -> Float# -> State# s -> State# s
1123 with has_side_effects = True
1125 primop WriteOffAddrOp_Double "writeDoubleOffAddr#" GenPrimOp
1126 Addr# -> Int# -> Double# -> State# s -> State# s
1127 with has_side_effects = True
1129 primop WriteOffAddrOp_StablePtr "writeStablePtrOffAddr#" GenPrimOp
1130 Addr# -> Int# -> StablePtr# a -> State# s -> State# s
1131 with has_side_effects = True
1133 primop WriteOffAddrOp_Int8 "writeInt8OffAddr#" GenPrimOp
1134 Addr# -> Int# -> Int# -> State# s -> State# s
1135 with has_side_effects = True
1137 primop WriteOffAddrOp_Int16 "writeInt16OffAddr#" GenPrimOp
1138 Addr# -> Int# -> Int# -> State# s -> State# s
1139 with has_side_effects = True
1141 primop WriteOffAddrOp_Int32 "writeInt32OffAddr#" GenPrimOp
1142 Addr# -> Int# -> INT32 -> State# s -> State# s
1143 with has_side_effects = True
1145 primop WriteOffAddrOp_Int64 "writeInt64OffAddr#" GenPrimOp
1146 Addr# -> Int# -> INT64 -> State# s -> State# s
1147 with has_side_effects = True
1149 primop WriteOffAddrOp_Word8 "writeWord8OffAddr#" GenPrimOp
1150 Addr# -> Int# -> Word# -> State# s -> State# s
1151 with has_side_effects = True
1153 primop WriteOffAddrOp_Word16 "writeWord16OffAddr#" GenPrimOp
1154 Addr# -> Int# -> Word# -> State# s -> State# s
1155 with has_side_effects = True
1157 primop WriteOffAddrOp_Word32 "writeWord32OffAddr#" GenPrimOp
1158 Addr# -> Int# -> WORD32 -> State# s -> State# s
1159 with has_side_effects = True
1161 primop WriteOffAddrOp_Word64 "writeWord64OffAddr#" GenPrimOp
1162 Addr# -> Int# -> WORD64 -> State# s -> State# s
1163 with has_side_effects = True
1165 ------------------------------------------------------------------------
1166 section "Mutable variables"
1167 {Operations on MutVar\#s.}
1168 ------------------------------------------------------------------------
1170 primtype MutVar# s a
1171 {A {\tt MutVar\#} behaves like a single-element mutable array.}
1173 primop NewMutVarOp "newMutVar#" GenPrimOp
1174 a -> State# s -> (# State# s, MutVar# s a #)
1175 {Create {\tt MutVar\#} with specified initial value in specified state thread.}
1178 has_side_effects = True
1180 primop ReadMutVarOp "readMutVar#" GenPrimOp
1181 MutVar# s a -> State# s -> (# State# s, a #)
1182 {Read contents of {\tt MutVar\#}. Result is not yet evaluated.}
1184 has_side_effects = True
1186 primop WriteMutVarOp "writeMutVar#" GenPrimOp
1187 MutVar# s a -> a -> State# s -> State# s
1188 {Write contents of {\tt MutVar\#}.}
1190 has_side_effects = True
1191 code_size = { primOpCodeSizeForeignCall } -- for the write barrier
1193 primop SameMutVarOp "sameMutVar#" GenPrimOp
1194 MutVar# s a -> MutVar# s a -> Bool
1196 -- not really the right type, but we don't know about pairs here. The
1199 -- MutVar# s a -> (a -> (a,b)) -> State# s -> (# State# s, b #)
1201 primop AtomicModifyMutVarOp "atomicModifyMutVar#" GenPrimOp
1202 MutVar# s a -> (a -> b) -> State# s -> (# State# s, c #)
1205 has_side_effects = True
1207 primop CasMutVarOp "casMutVar#" GenPrimOp
1208 MutVar# s a -> a -> a -> State# s -> (# State# s, Int#, a #)
1211 has_side_effects = True
1213 ------------------------------------------------------------------------
1214 section "Exceptions"
1215 ------------------------------------------------------------------------
1217 primop CatchOp "catch#" GenPrimOp
1218 (State# RealWorld -> (# State# RealWorld, a #) )
1219 -> (b -> State# RealWorld -> (# State# RealWorld, a #) )
1221 -> (# State# RealWorld, a #)
1223 -- Catch is actually strict in its first argument
1224 -- but we don't want to tell the strictness
1225 -- analyser about that!
1226 -- might use caught action multiply
1228 has_side_effects = True
1230 primop RaiseOp "raise#" GenPrimOp
1233 strictness = { \ _arity -> mkStrictSig (mkTopDmdType [lazyDmd] BotRes) }
1234 -- NB: result is bottom
1237 -- raiseIO# needs to be a primop, because exceptions in the IO monad
1238 -- must be *precise* - we don't want the strictness analyser turning
1239 -- one kind of bottom into another, as it is allowed to do in pure code.
1241 -- But we *do* want to know that it returns bottom after
1242 -- being applied to two arguments
1244 primop RaiseIOOp "raiseIO#" GenPrimOp
1245 a -> State# RealWorld -> (# State# RealWorld, b #)
1247 strictness = { \ _arity -> mkStrictSig (mkTopDmdType [lazyDmd,lazyDmd] BotRes) }
1249 has_side_effects = True
1251 primop MaskAsyncExceptionsOp "maskAsyncExceptions#" GenPrimOp
1252 (State# RealWorld -> (# State# RealWorld, a #))
1253 -> (State# RealWorld -> (# State# RealWorld, a #))
1256 has_side_effects = True
1258 primop MaskUninterruptibleOp "maskUninterruptible#" GenPrimOp
1259 (State# RealWorld -> (# State# RealWorld, a #))
1260 -> (State# RealWorld -> (# State# RealWorld, a #))
1263 has_side_effects = True
1265 primop UnmaskAsyncExceptionsOp "unmaskAsyncExceptions#" GenPrimOp
1266 (State# RealWorld -> (# State# RealWorld, a #))
1267 -> (State# RealWorld -> (# State# RealWorld, a #))
1270 has_side_effects = True
1272 primop MaskStatus "getMaskingState#" GenPrimOp
1273 State# RealWorld -> (# State# RealWorld, Int# #)
1276 has_side_effects = True
1278 ------------------------------------------------------------------------
1279 section "STM-accessible Mutable Variables"
1280 ------------------------------------------------------------------------
1284 primop AtomicallyOp "atomically#" GenPrimOp
1285 (State# RealWorld -> (# State# RealWorld, a #) )
1286 -> State# RealWorld -> (# State# RealWorld, a #)
1289 has_side_effects = True
1291 primop RetryOp "retry#" GenPrimOp
1292 State# RealWorld -> (# State# RealWorld, a #)
1295 has_side_effects = True
1297 primop CatchRetryOp "catchRetry#" GenPrimOp
1298 (State# RealWorld -> (# State# RealWorld, a #) )
1299 -> (State# RealWorld -> (# State# RealWorld, a #) )
1300 -> (State# RealWorld -> (# State# RealWorld, a #) )
1303 has_side_effects = True
1305 primop CatchSTMOp "catchSTM#" GenPrimOp
1306 (State# RealWorld -> (# State# RealWorld, a #) )
1307 -> (b -> State# RealWorld -> (# State# RealWorld, a #) )
1308 -> (State# RealWorld -> (# State# RealWorld, a #) )
1311 has_side_effects = True
1313 primop Check "check#" GenPrimOp
1314 (State# RealWorld -> (# State# RealWorld, a #) )
1315 -> (State# RealWorld -> (# State# RealWorld, () #) )
1318 has_side_effects = True
1320 primop NewTVarOp "newTVar#" GenPrimOp
1322 -> State# s -> (# State# s, TVar# s a #)
1323 {Create a new {\tt TVar\#} holding a specified initial value.}
1326 has_side_effects = True
1328 primop ReadTVarOp "readTVar#" GenPrimOp
1330 -> State# s -> (# State# s, a #)
1331 {Read contents of {\tt TVar\#}. Result is not yet evaluated.}
1334 has_side_effects = True
1336 primop ReadTVarIOOp "readTVarIO#" GenPrimOp
1338 -> State# s -> (# State# s, a #)
1339 {Read contents of {\tt TVar\#} outside an STM transaction}
1342 has_side_effects = True
1344 primop WriteTVarOp "writeTVar#" GenPrimOp
1347 -> State# s -> State# s
1348 {Write contents of {\tt TVar\#}.}
1351 has_side_effects = True
1353 primop SameTVarOp "sameTVar#" GenPrimOp
1354 TVar# s a -> TVar# s a -> Bool
1357 ------------------------------------------------------------------------
1358 section "Synchronized Mutable Variables"
1359 {Operations on {\tt MVar\#}s. }
1360 ------------------------------------------------------------------------
1363 { A shared mutable variable ({\it not} the same as a {\tt MutVar\#}!).
1364 (Note: in a non-concurrent implementation, {\tt (MVar\# a)} can be
1365 represented by {\tt (MutVar\# (Maybe a))}.) }
1367 primop NewMVarOp "newMVar#" GenPrimOp
1368 State# s -> (# State# s, MVar# s a #)
1369 {Create new {\tt MVar\#}; initially empty.}
1372 has_side_effects = True
1374 primop TakeMVarOp "takeMVar#" GenPrimOp
1375 MVar# s a -> State# s -> (# State# s, a #)
1376 {If {\tt MVar\#} is empty, block until it becomes full.
1377 Then remove and return its contents, and set it empty.}
1380 has_side_effects = True
1382 primop TryTakeMVarOp "tryTakeMVar#" GenPrimOp
1383 MVar# s a -> State# s -> (# State# s, Int#, a #)
1384 {If {\tt MVar\#} is empty, immediately return with integer 0 and value undefined.
1385 Otherwise, return with integer 1 and contents of {\tt MVar\#}, and set {\tt MVar\#} empty.}
1388 has_side_effects = True
1390 primop PutMVarOp "putMVar#" GenPrimOp
1391 MVar# s a -> a -> State# s -> State# s
1392 {If {\tt MVar\#} is full, block until it becomes empty.
1393 Then store value arg as its new contents.}
1396 has_side_effects = True
1398 primop TryPutMVarOp "tryPutMVar#" GenPrimOp
1399 MVar# s a -> a -> State# s -> (# State# s, Int# #)
1400 {If {\tt MVar\#} is full, immediately return with integer 0.
1401 Otherwise, store value arg as {\tt MVar\#}'s new contents, and return with integer 1.}
1404 has_side_effects = True
1406 primop SameMVarOp "sameMVar#" GenPrimOp
1407 MVar# s a -> MVar# s a -> Bool
1409 primop IsEmptyMVarOp "isEmptyMVar#" GenPrimOp
1410 MVar# s a -> State# s -> (# State# s, Int# #)
1411 {Return 1 if {\tt MVar\#} is empty; 0 otherwise.}
1414 has_side_effects = True
1416 ------------------------------------------------------------------------
1417 section "Delay/wait operations"
1418 ------------------------------------------------------------------------
1420 primop DelayOp "delay#" GenPrimOp
1421 Int# -> State# s -> State# s
1422 {Sleep specified number of microseconds.}
1424 has_side_effects = True
1427 primop WaitReadOp "waitRead#" GenPrimOp
1428 Int# -> State# s -> State# s
1429 {Block until input is available on specified file descriptor.}
1431 has_side_effects = True
1434 primop WaitWriteOp "waitWrite#" GenPrimOp
1435 Int# -> State# s -> State# s
1436 {Block until output is possible on specified file descriptor.}
1438 has_side_effects = True
1441 #ifdef mingw32_TARGET_OS
1442 primop AsyncReadOp "asyncRead#" GenPrimOp
1443 Int# -> Int# -> Int# -> Addr# -> State# RealWorld-> (# State# RealWorld, Int#, Int# #)
1444 {Asynchronously read bytes from specified file descriptor.}
1446 has_side_effects = True
1449 primop AsyncWriteOp "asyncWrite#" GenPrimOp
1450 Int# -> Int# -> Int# -> Addr# -> State# RealWorld-> (# State# RealWorld, Int#, Int# #)
1451 {Asynchronously write bytes from specified file descriptor.}
1453 has_side_effects = True
1456 primop AsyncDoProcOp "asyncDoProc#" GenPrimOp
1457 Addr# -> Addr# -> State# RealWorld-> (# State# RealWorld, Int#, Int# #)
1458 {Asynchronously perform procedure (first arg), passing it 2nd arg.}
1460 has_side_effects = True
1465 ------------------------------------------------------------------------
1466 section "Concurrency primitives"
1467 ------------------------------------------------------------------------
1470 { {\tt State\#} is the primitive, unlifted type of states. It has
1471 one type parameter, thus {\tt State\# RealWorld}, or {\tt State\# s},
1472 where s is a type variable. The only purpose of the type parameter
1473 is to keep different state threads separate. It is represented by
1477 { {\tt RealWorld} is deeply magical. It is {\it primitive}, but it is not
1478 {\it unlifted} (hence {\tt ptrArg}). We never manipulate values of type
1479 {\tt RealWorld}; it's only used in the type system, to parameterise {\tt State\#}. }
1482 {(In a non-concurrent implementation, this can be a singleton
1483 type, whose (unique) value is returned by {\tt myThreadId\#}. The
1484 other operations can be omitted.)}
1486 primop ForkOp "fork#" GenPrimOp
1487 a -> State# RealWorld -> (# State# RealWorld, ThreadId# #)
1489 has_side_effects = True
1492 primop ForkOnOp "forkOn#" GenPrimOp
1493 Int# -> a -> State# RealWorld -> (# State# RealWorld, ThreadId# #)
1495 has_side_effects = True
1498 primop KillThreadOp "killThread#" GenPrimOp
1499 ThreadId# -> a -> State# RealWorld -> State# RealWorld
1501 has_side_effects = True
1504 primop YieldOp "yield#" GenPrimOp
1505 State# RealWorld -> State# RealWorld
1507 has_side_effects = True
1510 primop MyThreadIdOp "myThreadId#" GenPrimOp
1511 State# RealWorld -> (# State# RealWorld, ThreadId# #)
1514 has_side_effects = True
1516 primop LabelThreadOp "labelThread#" GenPrimOp
1517 ThreadId# -> Addr# -> State# RealWorld -> State# RealWorld
1519 has_side_effects = True
1522 primop IsCurrentThreadBoundOp "isCurrentThreadBound#" GenPrimOp
1523 State# RealWorld -> (# State# RealWorld, Int# #)
1526 has_side_effects = True
1528 primop NoDuplicateOp "noDuplicate#" GenPrimOp
1529 State# RealWorld -> State# RealWorld
1532 has_side_effects = True
1534 primop ThreadStatusOp "threadStatus#" GenPrimOp
1535 ThreadId# -> State# RealWorld -> (# State# RealWorld, Int#, Int#, Int# #)
1538 has_side_effects = True
1540 ------------------------------------------------------------------------
1541 section "Weak pointers"
1542 ------------------------------------------------------------------------
1546 -- note that tyvar "o" denotes openAlphaTyVar
1548 primop MkWeakOp "mkWeak#" GenPrimOp
1549 o -> b -> c -> State# RealWorld -> (# State# RealWorld, Weak# b #)
1551 has_side_effects = True
1554 primop MkWeakForeignEnvOp "mkWeakForeignEnv#" GenPrimOp
1555 o -> b -> Addr# -> Addr# -> Int# -> Addr# -> State# RealWorld -> (# State# RealWorld, Weak# b #)
1557 has_side_effects = True
1560 primop DeRefWeakOp "deRefWeak#" GenPrimOp
1561 Weak# a -> State# RealWorld -> (# State# RealWorld, Int#, a #)
1563 has_side_effects = True
1566 primop FinalizeWeakOp "finalizeWeak#" GenPrimOp
1567 Weak# a -> State# RealWorld -> (# State# RealWorld, Int#,
1568 (State# RealWorld -> (# State# RealWorld, () #)) #)
1570 has_side_effects = True
1573 primop TouchOp "touch#" GenPrimOp
1574 o -> State# RealWorld -> State# RealWorld
1577 has_side_effects = True
1579 ------------------------------------------------------------------------
1580 section "Stable pointers and names"
1581 ------------------------------------------------------------------------
1583 primtype StablePtr# a
1585 primtype StableName# a
1587 primop MakeStablePtrOp "makeStablePtr#" GenPrimOp
1588 a -> State# RealWorld -> (# State# RealWorld, StablePtr# a #)
1590 has_side_effects = True
1593 primop DeRefStablePtrOp "deRefStablePtr#" GenPrimOp
1594 StablePtr# a -> State# RealWorld -> (# State# RealWorld, a #)
1596 has_side_effects = True
1599 primop EqStablePtrOp "eqStablePtr#" GenPrimOp
1600 StablePtr# a -> StablePtr# a -> Int#
1602 has_side_effects = True
1604 primop MakeStableNameOp "makeStableName#" GenPrimOp
1605 a -> State# RealWorld -> (# State# RealWorld, StableName# a #)
1607 has_side_effects = True
1610 primop EqStableNameOp "eqStableName#" GenPrimOp
1611 StableName# a -> StableName# a -> Int#
1613 primop StableNameToIntOp "stableNameToInt#" GenPrimOp
1614 StableName# a -> Int#
1616 ------------------------------------------------------------------------
1617 section "Unsafe pointer equality"
1618 -- (#1 Bad Guy: Alistair Reid :)
1619 ------------------------------------------------------------------------
1621 primop ReallyUnsafePtrEqualityOp "reallyUnsafePtrEquality#" GenPrimOp
1624 ------------------------------------------------------------------------
1625 section "Parallelism"
1626 ------------------------------------------------------------------------
1628 primop ParOp "par#" GenPrimOp
1631 -- Note that Par is lazy to avoid that the sparked thing
1632 -- gets evaluted strictly, which it should *not* be
1633 has_side_effects = True
1634 code_size = { primOpCodeSizeForeignCall }
1636 primop GetSparkOp "getSpark#" GenPrimOp
1637 State# s -> (# State# s, Int#, a #)
1639 has_side_effects = True
1642 primop NumSparks "numSparks#" GenPrimOp
1643 State# s -> (# State# s, Int# #)
1644 { Returns the number of sparks in the local spark pool. }
1646 has_side_effects = True
1649 -- HWL: The first 4 Int# in all par... annotations denote:
1650 -- name, granularity info, size of result, degree of parallelism
1651 -- Same structure as _seq_ i.e. returns Int#
1652 -- KSW: v, the second arg in parAt# and parAtForNow#, is used only to determine
1653 -- `the processor containing the expression v'; it is not evaluated
1655 primop ParGlobalOp "parGlobal#" GenPrimOp
1656 a -> Int# -> Int# -> Int# -> Int# -> b -> Int#
1658 has_side_effects = True
1660 primop ParLocalOp "parLocal#" GenPrimOp
1661 a -> Int# -> Int# -> Int# -> Int# -> b -> Int#
1663 has_side_effects = True
1665 primop ParAtOp "parAt#" GenPrimOp
1666 b -> a -> Int# -> Int# -> Int# -> Int# -> c -> Int#
1668 has_side_effects = True
1670 primop ParAtAbsOp "parAtAbs#" GenPrimOp
1671 a -> Int# -> Int# -> Int# -> Int# -> Int# -> b -> Int#
1673 has_side_effects = True
1675 primop ParAtRelOp "parAtRel#" GenPrimOp
1676 a -> Int# -> Int# -> Int# -> Int# -> Int# -> b -> Int#
1678 has_side_effects = True
1680 primop ParAtForNowOp "parAtForNow#" GenPrimOp
1681 b -> a -> Int# -> Int# -> Int# -> Int# -> c -> Int#
1683 has_side_effects = True
1685 -- copyable# and noFollow# are yet to be implemented (for GpH)
1687 --primop CopyableOp "copyable#" GenPrimOp
1690 -- has_side_effects = True
1692 --primop NoFollowOp "noFollow#" GenPrimOp
1695 -- has_side_effects = True
1698 ------------------------------------------------------------------------
1699 section "Tag to enum stuff"
1700 {Convert back and forth between values of enumerated types
1701 and small integers.}
1702 ------------------------------------------------------------------------
1704 primop DataToTagOp "dataToTag#" GenPrimOp
1707 strictness = { \ _arity -> mkStrictSig (mkTopDmdType [seqDmd] TopRes) }
1708 -- dataToTag# must have an evaluated argument
1710 primop TagToEnumOp "tagToEnum#" GenPrimOp
1713 ------------------------------------------------------------------------
1714 section "Bytecode operations"
1715 {Support for the bytecode interpreter and linker.}
1716 ------------------------------------------------------------------------
1719 {Primitive bytecode type.}
1721 primop AddrToHValueOp "addrToHValue#" GenPrimOp
1723 {Convert an {\tt Addr\#} to a followable type.}
1727 primop MkApUpd0_Op "mkApUpd0#" GenPrimOp
1732 primop NewBCOOp "newBCO#" GenPrimOp
1733 ByteArray# -> ByteArray# -> Array# a -> Int# -> ByteArray# -> State# s -> (# State# s, BCO# #)
1735 has_side_effects = True
1738 primop UnpackClosureOp "unpackClosure#" GenPrimOp
1739 a -> (# Addr#, Array# b, ByteArray# #)
1743 primop GetApStackValOp "getApStackVal#" GenPrimOp
1744 a -> Int# -> (# Int#, b #)
1748 ------------------------------------------------------------------------
1750 {These aren't nearly as wired in as Etc...}
1751 ------------------------------------------------------------------------
1753 primop TraceCcsOp "traceCcs#" GenPrimOp
1756 has_side_effects = True
1759 ------------------------------------------------------------------------
1761 {Miscellaneous built-ins}
1762 ------------------------------------------------------------------------
1766 { Evaluates its first argument to head normal form, and then returns its second
1767 argument as the result. }
1771 { The call {\tt (inline f)} arranges that f is inlined, regardless of its size.
1772 More precisely, the call {\tt (inline f)} rewrites to the right-hand side of
1773 {\tt f}'s definition. This allows the programmer to control inlining from a
1774 particular call site rather than the definition site of the function (c.f.
1775 {\tt INLINE} pragmas in User's Guide, Section 7.10.3, "INLINE and NOINLINE
1778 This inlining occurs regardless of the argument to the call or the size of
1779 {\tt f}'s definition; it is unconditional. The main caveat is that {\tt f}'s
1780 definition must be visible to the compiler. That is, {\tt f} must be
1781 {\tt let}-bound in the current scope. If no inlining takes place, the
1782 {\tt inline} function expands to the identity function in Phase zero; so its
1783 use imposes no overhead.
1785 It is good practice to mark the function with an INLINABLE pragma at
1786 its definition, (a) so that GHC guarantees to expose its unfolding regardless
1787 of size, and (b) so that you have control over exactly what is inlined. }
1791 { The {\tt lazy} function restrains strictness analysis a little. The call
1792 {\tt (lazy e)} means the same as {\tt e}, but {\tt lazy} has a magical
1793 property so far as strictness analysis is concerned: it is lazy in its first
1794 argument, even though its semantics is strict. After strictness analysis has
1795 run, calls to {\tt lazy} are inlined to be the identity function.
1797 This behaviour is occasionally useful when controlling evaluation order.
1798 Notably, {\tt lazy} is used in the library definition of {\tt Control.Parallel.par}:
1800 {\tt par :: a -> b -> b}
1802 {\tt par x y = case (par\# x) of \_ -> lazy y}
1804 If {\tt lazy} were not lazy, {\tt par} would look strict in {\tt y} which
1805 would defeat the whole purpose of {\tt par}.
1807 Like {\tt seq}, the argument of {\tt lazy} can have an unboxed type. }
1810 { The type constructor {\tt Any} is type to which you can unsafely coerce any
1811 lifted type, and back.
1813 * It is lifted, and hence represented by a pointer
1815 * It does not claim to be a {\it data} type, and that's important for
1816 the code generator, because the code gen may {\it enter} a data value
1817 but never enters a function value.
1819 It's also used to instantiate un-constrained type variables after type
1820 checking. For example, {\tt length} has type
1822 {\tt length :: forall a. [a] -> Int}
1824 and the list datacon for the empty list has type
1826 {\tt [] :: forall a. [a]}
1828 In order to compose these two terms as {\tt length []} a type
1829 application is required, but there is no constraint on the
1830 choice. In this situation GHC uses {\tt Any}:
1832 {\tt length Any ([] Any)}
1834 Annoyingly, we sometimes need {\tt Any}s of other kinds, such as {\tt (* -> *)} etc.
1835 This is a bit like tuples. We define a couple of useful ones here,
1836 and make others up on the fly. If any of these others end up being exported
1837 into interface files, we'll get a crash; at least until we add interface-file
1838 syntax to support them. }
1840 pseudoop "unsafeCoerce#"
1842 { The function {\tt unsafeCoerce\#} allows you to side-step the typechecker entirely. That
1843 is, it allows you to coerce any type into any other type. If you use this function,
1844 you had better get it right, otherwise segmentation faults await. It is generally
1845 used when you want to write a program that you know is well-typed, but where Haskell's
1846 type system is not expressive enough to prove that it is well typed.
1848 The following uses of {\tt unsafeCoerce\#} are supposed to work (i.e. not lead to
1849 spurious compile-time or run-time crashes):
1851 * Casting any lifted type to {\tt Any}
1853 * Casting {\tt Any} back to the real type
1855 * Casting an unboxed type to another unboxed type of the same size
1856 (but not coercions between floating-point and integral types)
1858 * Casting between two types that have the same runtime representation. One case is when
1859 the two types differ only in "phantom" type parameters, for example
1860 {\tt Ptr Int} to {\tt Ptr Float}, or {\tt [Int]} to {\tt [Float]} when the list is
1861 known to be empty. Also, a {\tt newtype} of a type {\tt T} has the same representation
1862 at runtime as {\tt T}.
1864 Other uses of {\tt unsafeCoerce\#} are undefined. In particular, you should not use
1865 {\tt unsafeCoerce\#} to cast a T to an algebraic data type D, unless T is also
1866 an algebraic data type. For example, do not cast {\tt Int->Int} to {\tt Bool}, even if
1867 you later cast that {\tt Bool} back to {\tt Int->Int} before applying it. The reasons
1868 have to do with GHC's internal representation details (for the congnoscenti, data values
1869 can be entered but function closures cannot). If you want a safe type to cast things
1870 to, use {\tt Any}, which is not an algebraic data type.
1874 -- NB. It is tempting to think that casting a value to a type that it doesn't have is safe
1875 -- as long as you don't "do anything" with the value in its cast form, such as seq on it. This
1876 -- isn't the case: the compiler can insert seqs itself, and if these happen at the wrong type,
1877 -- Bad Things Might Happen. See bug #1616: in this case we cast a function of type (a,b) -> (a,b)
1878 -- to () -> () and back again. The strictness analyser saw that the function was strict, but
1879 -- the wrapper had type () -> (), and hence the wrapper de-constructed the (), the worker re-constructed
1880 -- a new (), with the result that the code ended up with "case () of (a,b) -> ...".
1882 primop TraceEventOp "traceEvent#" GenPrimOp
1883 Addr# -> State# s -> State# s
1884 { Emits an event via the RTS tracing framework. The contents
1885 of the event is the zero-terminated byte string passed as the first
1886 argument. The event will be emitted either to the .eventlog file,
1887 or to stderr, depending on the runtime RTS flags. }
1889 has_side_effects = True
1892 ------------------------------------------------------------------------
1894 ------------------------------------------------------------------------