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
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#
159 ------------------------------------------------------------------------
161 {Operations on native-size integers (30+ bits).}
162 ------------------------------------------------------------------------
166 primop IntAddOp "+#" Dyadic
168 with commutable = True
170 primop IntSubOp "-#" Dyadic Int# -> Int# -> Int#
173 Dyadic Int# -> Int# -> Int#
174 {Low word of signed integer multiply.}
175 with commutable = True
177 primop IntMulMayOfloOp "mulIntMayOflo#"
178 Dyadic Int# -> Int# -> Int#
179 {Return non-zero if there is any possibility that the upper word of a
180 signed integer multiply might contain useful information. Return
181 zero only if you are completely sure that no overflow can occur.
182 On a 32-bit platform, the recommmended implementation is to do a
183 32 x 32 -> 64 signed multiply, and subtract result[63:32] from
184 (result[31] >>signed 31). If this is zero, meaning that the
185 upper word is merely a sign extension of the lower one, no
188 On a 64-bit platform it is not always possible to
189 acquire the top 64 bits of the result. Therefore, a recommended
190 implementation is to take the absolute value of both operands, and
191 return 0 iff bits[63:31] of them are zero, since that means that their
192 magnitudes fit within 31 bits, so the magnitude of the product must fit
195 If in doubt, return non-zero, but do make an effort to create the
196 correct answer for small args, since otherwise the performance of
197 \texttt{(*) :: Integer -> Integer -> Integer} will be poor.
199 with commutable = True
201 primop IntQuotOp "quotInt#" Dyadic
203 {Rounds towards zero.}
206 primop IntRemOp "remInt#" Dyadic
208 {Satisfies \texttt{(quotInt\# x y) *\# y +\# (remInt\# x y) == x}.}
211 primop IntNegOp "negateInt#" Monadic Int# -> Int#
212 primop IntAddCOp "addIntC#" GenPrimOp Int# -> Int# -> (# Int#, Int# #)
213 {Add with carry. First member of result is (wrapped) sum;
214 second member is 0 iff no overflow occured.}
215 primop IntSubCOp "subIntC#" GenPrimOp Int# -> Int# -> (# Int#, Int# #)
216 {Subtract with carry. First member of result is (wrapped) difference;
217 second member is 0 iff no overflow occured.}
219 primop IntGtOp ">#" Compare Int# -> Int# -> Bool
220 primop IntGeOp ">=#" Compare Int# -> Int# -> Bool
222 primop IntEqOp "==#" Compare
224 with commutable = True
226 primop IntNeOp "/=#" Compare
228 with commutable = True
230 primop IntLtOp "<#" Compare Int# -> Int# -> Bool
231 primop IntLeOp "<=#" Compare Int# -> Int# -> Bool
233 primop ChrOp "chr#" GenPrimOp Int# -> Char#
235 primop Int2WordOp "int2Word#" GenPrimOp Int# -> Word#
236 primop Int2FloatOp "int2Float#" GenPrimOp Int# -> Float#
237 primop Int2DoubleOp "int2Double#" GenPrimOp Int# -> Double#
239 primop ISllOp "uncheckedIShiftL#" GenPrimOp Int# -> Int# -> Int#
240 {Shift left. Result undefined if shift amount is not
241 in the range 0 to word size - 1 inclusive.}
242 primop ISraOp "uncheckedIShiftRA#" GenPrimOp Int# -> Int# -> Int#
243 {Shift right arithmetic. Result undefined if shift amount is not
244 in the range 0 to word size - 1 inclusive.}
245 primop ISrlOp "uncheckedIShiftRL#" GenPrimOp Int# -> Int# -> Int#
246 {Shift right logical. Result undefined if shift amount is not
247 in the range 0 to word size - 1 inclusive.}
249 ------------------------------------------------------------------------
251 {Operations on native-sized unsigned words (30+ bits).}
252 ------------------------------------------------------------------------
256 primop WordAddOp "plusWord#" Dyadic Word# -> Word# -> Word#
257 with commutable = True
259 primop WordSubOp "minusWord#" Dyadic Word# -> Word# -> Word#
261 primop WordMulOp "timesWord#" Dyadic Word# -> Word# -> Word#
262 with commutable = True
264 primop WordQuotOp "quotWord#" Dyadic Word# -> Word# -> Word#
267 primop WordRemOp "remWord#" Dyadic Word# -> Word# -> Word#
270 primop AndOp "and#" Dyadic Word# -> Word# -> Word#
271 with commutable = True
273 primop OrOp "or#" Dyadic Word# -> Word# -> Word#
274 with commutable = True
276 primop XorOp "xor#" Dyadic Word# -> Word# -> Word#
277 with commutable = True
279 primop NotOp "not#" Monadic Word# -> Word#
281 primop SllOp "uncheckedShiftL#" GenPrimOp Word# -> Int# -> Word#
282 {Shift left logical. Result undefined if shift amount is not
283 in the range 0 to word size - 1 inclusive.}
284 primop SrlOp "uncheckedShiftRL#" GenPrimOp Word# -> Int# -> Word#
285 {Shift right logical. Result undefined if shift amount is not
286 in the range 0 to word size - 1 inclusive.}
288 primop Word2IntOp "word2Int#" GenPrimOp Word# -> Int#
290 primop WordGtOp "gtWord#" Compare Word# -> Word# -> Bool
291 primop WordGeOp "geWord#" Compare Word# -> Word# -> Bool
292 primop WordEqOp "eqWord#" Compare Word# -> Word# -> Bool
293 primop WordNeOp "neWord#" Compare Word# -> Word# -> Bool
294 primop WordLtOp "ltWord#" Compare Word# -> Word# -> Bool
295 primop WordLeOp "leWord#" Compare Word# -> Word# -> Bool
297 ------------------------------------------------------------------------
299 {Explicit narrowing of native-sized ints or words.}
300 ------------------------------------------------------------------------
302 primop Narrow8IntOp "narrow8Int#" Monadic Int# -> Int#
303 primop Narrow16IntOp "narrow16Int#" Monadic Int# -> Int#
304 primop Narrow32IntOp "narrow32Int#" Monadic Int# -> Int#
305 primop Narrow8WordOp "narrow8Word#" Monadic Word# -> Word#
306 primop Narrow16WordOp "narrow16Word#" Monadic Word# -> Word#
307 primop Narrow32WordOp "narrow32Word#" Monadic Word# -> Word#
310 #if WORD_SIZE_IN_BITS < 32
311 ------------------------------------------------------------------------
313 {Operations on 32-bit integers ({\tt Int32\#}). This type is only used
314 if plain {\tt Int\#} has less than 32 bits. In any case, the operations
315 are not primops; they are implemented (if needed) as ccalls instead.}
316 ------------------------------------------------------------------------
320 ------------------------------------------------------------------------
322 {Operations on 32-bit unsigned words. This type is only used
323 if plain {\tt Word\#} has less than 32 bits. In any case, the operations
324 are not primops; they are implemented (if needed) as ccalls instead.}
325 ------------------------------------------------------------------------
332 #if WORD_SIZE_IN_BITS < 64
333 ------------------------------------------------------------------------
335 {Operations on 64-bit unsigned words. This type is only used
336 if plain {\tt Int\#} has less than 64 bits. In any case, the operations
337 are not primops; they are implemented (if needed) as ccalls instead.}
338 ------------------------------------------------------------------------
342 ------------------------------------------------------------------------
344 {Operations on 64-bit unsigned words. This type is only used
345 if plain {\tt Word\#} has less than 64 bits. In any case, the operations
346 are not primops; they are implemented (if needed) as ccalls instead.}
347 ------------------------------------------------------------------------
353 ------------------------------------------------------------------------
355 {Operations on double-precision (64 bit) floating-point numbers.}
356 ------------------------------------------------------------------------
360 primop DoubleGtOp ">##" Compare Double# -> Double# -> Bool
361 primop DoubleGeOp ">=##" Compare Double# -> Double# -> Bool
363 primop DoubleEqOp "==##" Compare
364 Double# -> Double# -> Bool
365 with commutable = True
367 primop DoubleNeOp "/=##" Compare
368 Double# -> Double# -> Bool
369 with commutable = True
371 primop DoubleLtOp "<##" Compare Double# -> Double# -> Bool
372 primop DoubleLeOp "<=##" Compare Double# -> Double# -> Bool
374 primop DoubleAddOp "+##" Dyadic
375 Double# -> Double# -> Double#
376 with commutable = True
378 primop DoubleSubOp "-##" Dyadic Double# -> Double# -> Double#
380 primop DoubleMulOp "*##" Dyadic
381 Double# -> Double# -> Double#
382 with commutable = True
384 primop DoubleDivOp "/##" Dyadic
385 Double# -> Double# -> Double#
388 primop DoubleNegOp "negateDouble#" Monadic Double# -> Double#
390 primop Double2IntOp "double2Int#" GenPrimOp Double# -> Int#
391 {Truncates a {\tt Double#} value to the nearest {\tt Int#}.
392 Results are undefined if the truncation if truncation yields
393 a value outside the range of {\tt Int#}.}
395 primop Double2FloatOp "double2Float#" GenPrimOp Double# -> Float#
397 primop DoubleExpOp "expDouble#" Monadic
399 with needs_wrapper = True
401 primop DoubleLogOp "logDouble#" Monadic
407 primop DoubleSqrtOp "sqrtDouble#" Monadic
409 with needs_wrapper = True
411 primop DoubleSinOp "sinDouble#" Monadic
413 with needs_wrapper = True
415 primop DoubleCosOp "cosDouble#" Monadic
417 with needs_wrapper = True
419 primop DoubleTanOp "tanDouble#" Monadic
421 with needs_wrapper = True
423 primop DoubleAsinOp "asinDouble#" Monadic
429 primop DoubleAcosOp "acosDouble#" Monadic
435 primop DoubleAtanOp "atanDouble#" Monadic
440 primop DoubleSinhOp "sinhDouble#" Monadic
442 with needs_wrapper = True
444 primop DoubleCoshOp "coshDouble#" Monadic
446 with needs_wrapper = True
448 primop DoubleTanhOp "tanhDouble#" Monadic
450 with needs_wrapper = True
452 primop DoublePowerOp "**##" Dyadic
453 Double# -> Double# -> Double#
455 with needs_wrapper = True
457 primop DoubleDecode_2IntOp "decodeDouble_2Int#" GenPrimOp
458 Double# -> (# Int#, Word#, Word#, Int# #)
460 First component of the result is -1 or 1, indicating the sign of the
461 mantissa. The next two are the high and low 32 bits of the mantissa
462 respectively, and the last is the exponent.}
463 with out_of_line = True
465 ------------------------------------------------------------------------
467 {Operations on single-precision (32-bit) floating-point numbers.}
468 ------------------------------------------------------------------------
472 primop FloatGtOp "gtFloat#" Compare Float# -> Float# -> Bool
473 primop FloatGeOp "geFloat#" Compare Float# -> Float# -> Bool
475 primop FloatEqOp "eqFloat#" Compare
476 Float# -> Float# -> Bool
477 with commutable = True
479 primop FloatNeOp "neFloat#" Compare
480 Float# -> Float# -> Bool
481 with commutable = True
483 primop FloatLtOp "ltFloat#" Compare Float# -> Float# -> Bool
484 primop FloatLeOp "leFloat#" Compare Float# -> Float# -> Bool
486 primop FloatAddOp "plusFloat#" Dyadic
487 Float# -> Float# -> Float#
488 with commutable = True
490 primop FloatSubOp "minusFloat#" Dyadic Float# -> Float# -> Float#
492 primop FloatMulOp "timesFloat#" Dyadic
493 Float# -> Float# -> Float#
494 with commutable = True
496 primop FloatDivOp "divideFloat#" Dyadic
497 Float# -> Float# -> Float#
500 primop FloatNegOp "negateFloat#" Monadic Float# -> Float#
502 primop Float2IntOp "float2Int#" GenPrimOp Float# -> Int#
503 {Truncates a {\tt Float#} value to the nearest {\tt Int#}.
504 Results are undefined if the truncation if truncation yields
505 a value outside the range of {\tt Int#}.}
507 primop FloatExpOp "expFloat#" Monadic
509 with needs_wrapper = True
511 primop FloatLogOp "logFloat#" Monadic
513 with needs_wrapper = True
516 primop FloatSqrtOp "sqrtFloat#" Monadic
518 with needs_wrapper = True
520 primop FloatSinOp "sinFloat#" Monadic
522 with needs_wrapper = True
524 primop FloatCosOp "cosFloat#" Monadic
526 with needs_wrapper = True
528 primop FloatTanOp "tanFloat#" Monadic
530 with needs_wrapper = True
532 primop FloatAsinOp "asinFloat#" Monadic
534 with needs_wrapper = True
537 primop FloatAcosOp "acosFloat#" Monadic
539 with needs_wrapper = True
542 primop FloatAtanOp "atanFloat#" Monadic
544 with needs_wrapper = True
546 primop FloatSinhOp "sinhFloat#" Monadic
548 with needs_wrapper = True
550 primop FloatCoshOp "coshFloat#" Monadic
552 with needs_wrapper = True
554 primop FloatTanhOp "tanhFloat#" Monadic
556 with needs_wrapper = True
558 primop FloatPowerOp "powerFloat#" Dyadic
559 Float# -> Float# -> Float#
560 with needs_wrapper = True
562 primop Float2DoubleOp "float2Double#" GenPrimOp Float# -> Double#
564 primop FloatDecode_IntOp "decodeFloat_Int#" GenPrimOp
565 Float# -> (# Int#, Int# #)
566 {Convert to integers.
567 First {\tt Int\#} in result is the mantissa; second is the exponent.}
568 with out_of_line = True
570 ------------------------------------------------------------------------
572 {Operations on {\tt Array\#}.}
573 ------------------------------------------------------------------------
577 primtype MutableArray# s a
579 primop NewArrayOp "newArray#" GenPrimOp
580 Int# -> a -> State# s -> (# State# s, MutableArray# s a #)
581 {Create a new mutable array with the specified number of elements,
582 in the specified state thread,
583 with each element containing the specified initial value.}
586 has_side_effects = True
588 primop SameMutableArrayOp "sameMutableArray#" GenPrimOp
589 MutableArray# s a -> MutableArray# s a -> Bool
591 primop ReadArrayOp "readArray#" GenPrimOp
592 MutableArray# s a -> Int# -> State# s -> (# State# s, a #)
593 {Read from specified index of mutable array. Result is not yet evaluated.}
595 has_side_effects = True
597 primop WriteArrayOp "writeArray#" GenPrimOp
598 MutableArray# s a -> Int# -> a -> State# s -> State# s
599 {Write to specified index of mutable array.}
601 has_side_effects = True
603 primop SizeofArrayOp "sizeofArray#" GenPrimOp
605 {Return the number of elements in the array.}
607 primop SizeofMutableArrayOp "sizeofMutableArray#" GenPrimOp
608 MutableArray# s a -> Int#
609 {Return the number of elements in the array.}
611 primop IndexArrayOp "indexArray#" GenPrimOp
612 Array# a -> Int# -> (# a #)
613 {Read from specified index of immutable array. Result is packaged into
614 an unboxed singleton; the result itself is not yet evaluated.}
616 primop UnsafeFreezeArrayOp "unsafeFreezeArray#" GenPrimOp
617 MutableArray# s a -> State# s -> (# State# s, Array# a #)
618 {Make a mutable array immutable, without copying.}
620 has_side_effects = True
622 primop UnsafeThawArrayOp "unsafeThawArray#" GenPrimOp
623 Array# a -> State# s -> (# State# s, MutableArray# s a #)
624 {Make an immutable array mutable, without copying.}
627 has_side_effects = True
629 primop CopyArrayOp "copyArray#" GenPrimOp
630 Array# a -> Int# -> MutableArray# s a -> Int# -> Int# -> State# s -> State# s
631 {Copy a range of the Array# to the specified region in the MutableArray#.
632 Both arrays must fully contain the specified ranges, but this is not checked.
633 The two arrays must not be the same array in different states, but this is not checked either.}
635 has_side_effects = True
637 primop CopyMutableArrayOp "copyMutableArray#" GenPrimOp
638 MutableArray# s a -> Int# -> MutableArray# s a -> Int# -> Int# -> State# s -> State# s
639 {Copy a range of the first MutableArray# to the specified region in the second MutableArray#.
640 Both arrays must fully contain the specified ranges, but this is not checked.}
642 has_side_effects = True
644 primop CloneArrayOp "cloneArray#" GenPrimOp
645 Array# a -> Int# -> Int# -> Array# a
646 {Return a newly allocated Array# with the specified subrange of the provided Array#.
647 The provided Array# should contain the full subrange specified by the two Int#s, but this is not checked.}
649 has_side_effects = True
651 primop CloneMutableArrayOp "cloneMutableArray#" GenPrimOp
652 MutableArray# s a -> Int# -> Int# -> State# s -> (# State# s, MutableArray# s a #)
653 {Return a newly allocated Array# with the specified subrange of the provided Array#.
654 The provided MutableArray# should contain the full subrange specified by the two Int#s, but this is not checked.}
656 has_side_effects = True
658 primop FreezeArrayOp "freezeArray#" GenPrimOp
659 MutableArray# s a -> Int# -> Int# -> State# s -> (# State# s, Array# a #)
660 {Return a newly allocated Array# with the specified subrange of the provided MutableArray#.
661 The provided MutableArray# should contain the full subrange specified by the two Int#s, but this is not checked.}
663 has_side_effects = True
665 primop ThawArrayOp "thawArray#" GenPrimOp
666 Array# a -> Int# -> Int# -> State# s -> (# State# s, MutableArray# s a #)
667 {Return a newly allocated Array# with the specified subrange of the provided MutableArray#.
668 The provided Array# should contain the full subrange specified by the two Int#s, but this is not checked.}
670 has_side_effects = True
672 ------------------------------------------------------------------------
673 section "Byte Arrays"
674 {Operations on {\tt ByteArray\#}. A {\tt ByteArray\#} is a just a region of
675 raw memory in the garbage-collected heap, which is not
676 scanned for pointers. It carries its own size (in bytes).
678 three sets of operations for accessing byte array contents:
679 index for reading from immutable byte arrays, and read/write
680 for mutable byte arrays. Each set contains operations for a
681 range of useful primitive data types. Each operation takes
682 an offset measured in terms of the size fo the primitive type
683 being read or written.}
685 ------------------------------------------------------------------------
689 primtype MutableByteArray# s
691 primop NewByteArrayOp_Char "newByteArray#" GenPrimOp
692 Int# -> State# s -> (# State# s, MutableByteArray# s #)
693 {Create a new mutable byte array of specified size (in bytes), in
694 the specified state thread.}
695 with out_of_line = True
696 has_side_effects = True
698 primop NewPinnedByteArrayOp_Char "newPinnedByteArray#" GenPrimOp
699 Int# -> State# s -> (# State# s, MutableByteArray# s #)
700 {Create a mutable byte array that the GC guarantees not to move.}
701 with out_of_line = True
702 has_side_effects = True
704 primop NewAlignedPinnedByteArrayOp_Char "newAlignedPinnedByteArray#" GenPrimOp
705 Int# -> Int# -> State# s -> (# State# s, MutableByteArray# s #)
706 {Create a mutable byte array, aligned by the specified amount, that the GC guarantees not to move.}
707 with out_of_line = True
708 has_side_effects = True
710 primop ByteArrayContents_Char "byteArrayContents#" GenPrimOp
712 {Intended for use with pinned arrays; otherwise very unsafe!}
714 primop SameMutableByteArrayOp "sameMutableByteArray#" GenPrimOp
715 MutableByteArray# s -> MutableByteArray# s -> Bool
717 primop UnsafeFreezeByteArrayOp "unsafeFreezeByteArray#" GenPrimOp
718 MutableByteArray# s -> State# s -> (# State# s, ByteArray# #)
719 {Make a mutable byte array immutable, without copying.}
721 has_side_effects = True
723 primop SizeofByteArrayOp "sizeofByteArray#" GenPrimOp
725 {Return the size of the array in bytes.}
727 primop SizeofMutableByteArrayOp "sizeofMutableByteArray#" GenPrimOp
728 MutableByteArray# s -> Int#
729 {Return the size of the array in bytes.}
731 primop IndexByteArrayOp_Char "indexCharArray#" GenPrimOp
732 ByteArray# -> Int# -> Char#
733 {Read 8-bit character; offset in bytes.}
735 primop IndexByteArrayOp_WideChar "indexWideCharArray#" GenPrimOp
736 ByteArray# -> Int# -> Char#
737 {Read 31-bit character; offset in 4-byte words.}
739 primop IndexByteArrayOp_Int "indexIntArray#" GenPrimOp
740 ByteArray# -> Int# -> Int#
742 primop IndexByteArrayOp_Word "indexWordArray#" GenPrimOp
743 ByteArray# -> Int# -> Word#
745 primop IndexByteArrayOp_Addr "indexAddrArray#" GenPrimOp
746 ByteArray# -> Int# -> Addr#
748 primop IndexByteArrayOp_Float "indexFloatArray#" GenPrimOp
749 ByteArray# -> Int# -> Float#
751 primop IndexByteArrayOp_Double "indexDoubleArray#" GenPrimOp
752 ByteArray# -> Int# -> Double#
754 primop IndexByteArrayOp_StablePtr "indexStablePtrArray#" GenPrimOp
755 ByteArray# -> Int# -> StablePtr# a
757 primop IndexByteArrayOp_Int8 "indexInt8Array#" GenPrimOp
758 ByteArray# -> Int# -> Int#
760 primop IndexByteArrayOp_Int16 "indexInt16Array#" GenPrimOp
761 ByteArray# -> Int# -> Int#
763 primop IndexByteArrayOp_Int32 "indexInt32Array#" GenPrimOp
764 ByteArray# -> Int# -> INT32
766 primop IndexByteArrayOp_Int64 "indexInt64Array#" GenPrimOp
767 ByteArray# -> Int# -> INT64
769 primop IndexByteArrayOp_Word8 "indexWord8Array#" GenPrimOp
770 ByteArray# -> Int# -> Word#
772 primop IndexByteArrayOp_Word16 "indexWord16Array#" GenPrimOp
773 ByteArray# -> Int# -> Word#
775 primop IndexByteArrayOp_Word32 "indexWord32Array#" GenPrimOp
776 ByteArray# -> Int# -> WORD32
778 primop IndexByteArrayOp_Word64 "indexWord64Array#" GenPrimOp
779 ByteArray# -> Int# -> WORD64
781 primop ReadByteArrayOp_Char "readCharArray#" GenPrimOp
782 MutableByteArray# s -> Int# -> State# s -> (# State# s, Char# #)
783 {Read 8-bit character; offset in bytes.}
784 with has_side_effects = True
786 primop ReadByteArrayOp_WideChar "readWideCharArray#" GenPrimOp
787 MutableByteArray# s -> Int# -> State# s -> (# State# s, Char# #)
788 {Read 31-bit character; offset in 4-byte words.}
789 with has_side_effects = True
791 primop ReadByteArrayOp_Int "readIntArray#" GenPrimOp
792 MutableByteArray# s -> Int# -> State# s -> (# State# s, Int# #)
793 with has_side_effects = True
795 primop ReadByteArrayOp_Word "readWordArray#" GenPrimOp
796 MutableByteArray# s -> Int# -> State# s -> (# State# s, Word# #)
797 with has_side_effects = True
799 primop ReadByteArrayOp_Addr "readAddrArray#" GenPrimOp
800 MutableByteArray# s -> Int# -> State# s -> (# State# s, Addr# #)
801 with has_side_effects = True
803 primop ReadByteArrayOp_Float "readFloatArray#" GenPrimOp
804 MutableByteArray# s -> Int# -> State# s -> (# State# s, Float# #)
805 with has_side_effects = True
807 primop ReadByteArrayOp_Double "readDoubleArray#" GenPrimOp
808 MutableByteArray# s -> Int# -> State# s -> (# State# s, Double# #)
809 with has_side_effects = True
811 primop ReadByteArrayOp_StablePtr "readStablePtrArray#" GenPrimOp
812 MutableByteArray# s -> Int# -> State# s -> (# State# s, StablePtr# a #)
813 with has_side_effects = True
815 primop ReadByteArrayOp_Int8 "readInt8Array#" GenPrimOp
816 MutableByteArray# s -> Int# -> State# s -> (# State# s, Int# #)
817 with has_side_effects = True
819 primop ReadByteArrayOp_Int16 "readInt16Array#" GenPrimOp
820 MutableByteArray# s -> Int# -> State# s -> (# State# s, Int# #)
821 with has_side_effects = True
823 primop ReadByteArrayOp_Int32 "readInt32Array#" GenPrimOp
824 MutableByteArray# s -> Int# -> State# s -> (# State# s, INT32 #)
825 with has_side_effects = True
827 primop ReadByteArrayOp_Int64 "readInt64Array#" GenPrimOp
828 MutableByteArray# s -> Int# -> State# s -> (# State# s, INT64 #)
829 with has_side_effects = True
831 primop ReadByteArrayOp_Word8 "readWord8Array#" GenPrimOp
832 MutableByteArray# s -> Int# -> State# s -> (# State# s, Word# #)
833 with has_side_effects = True
835 primop ReadByteArrayOp_Word16 "readWord16Array#" GenPrimOp
836 MutableByteArray# s -> Int# -> State# s -> (# State# s, Word# #)
837 with has_side_effects = True
839 primop ReadByteArrayOp_Word32 "readWord32Array#" GenPrimOp
840 MutableByteArray# s -> Int# -> State# s -> (# State# s, WORD32 #)
841 with has_side_effects = True
843 primop ReadByteArrayOp_Word64 "readWord64Array#" GenPrimOp
844 MutableByteArray# s -> Int# -> State# s -> (# State# s, WORD64 #)
845 with has_side_effects = True
847 primop WriteByteArrayOp_Char "writeCharArray#" GenPrimOp
848 MutableByteArray# s -> Int# -> Char# -> State# s -> State# s
849 {Write 8-bit character; offset in bytes.}
850 with has_side_effects = True
852 primop WriteByteArrayOp_WideChar "writeWideCharArray#" GenPrimOp
853 MutableByteArray# s -> Int# -> Char# -> State# s -> State# s
854 {Write 31-bit character; offset in 4-byte words.}
855 with has_side_effects = True
857 primop WriteByteArrayOp_Int "writeIntArray#" GenPrimOp
858 MutableByteArray# s -> Int# -> Int# -> State# s -> State# s
859 with has_side_effects = True
861 primop WriteByteArrayOp_Word "writeWordArray#" GenPrimOp
862 MutableByteArray# s -> Int# -> Word# -> State# s -> State# s
863 with has_side_effects = True
865 primop WriteByteArrayOp_Addr "writeAddrArray#" GenPrimOp
866 MutableByteArray# s -> Int# -> Addr# -> State# s -> State# s
867 with has_side_effects = True
869 primop WriteByteArrayOp_Float "writeFloatArray#" GenPrimOp
870 MutableByteArray# s -> Int# -> Float# -> State# s -> State# s
871 with has_side_effects = True
873 primop WriteByteArrayOp_Double "writeDoubleArray#" GenPrimOp
874 MutableByteArray# s -> Int# -> Double# -> State# s -> State# s
875 with has_side_effects = True
877 primop WriteByteArrayOp_StablePtr "writeStablePtrArray#" GenPrimOp
878 MutableByteArray# s -> Int# -> StablePtr# a -> State# s -> State# s
879 with has_side_effects = True
881 primop WriteByteArrayOp_Int8 "writeInt8Array#" GenPrimOp
882 MutableByteArray# s -> Int# -> Int# -> State# s -> State# s
883 with has_side_effects = True
885 primop WriteByteArrayOp_Int16 "writeInt16Array#" GenPrimOp
886 MutableByteArray# s -> Int# -> Int# -> State# s -> State# s
887 with has_side_effects = True
889 primop WriteByteArrayOp_Int32 "writeInt32Array#" GenPrimOp
890 MutableByteArray# s -> Int# -> INT32 -> State# s -> State# s
891 with has_side_effects = True
893 primop WriteByteArrayOp_Int64 "writeInt64Array#" GenPrimOp
894 MutableByteArray# s -> Int# -> INT64 -> State# s -> State# s
895 with has_side_effects = True
897 primop WriteByteArrayOp_Word8 "writeWord8Array#" GenPrimOp
898 MutableByteArray# s -> Int# -> Word# -> State# s -> State# s
899 with has_side_effects = True
901 primop WriteByteArrayOp_Word16 "writeWord16Array#" GenPrimOp
902 MutableByteArray# s -> Int# -> Word# -> State# s -> State# s
903 with has_side_effects = True
905 primop WriteByteArrayOp_Word32 "writeWord32Array#" GenPrimOp
906 MutableByteArray# s -> Int# -> WORD32 -> State# s -> State# s
907 with has_side_effects = True
909 primop WriteByteArrayOp_Word64 "writeWord64Array#" GenPrimOp
910 MutableByteArray# s -> Int# -> WORD64 -> State# s -> State# s
911 with has_side_effects = True
913 ------------------------------------------------------------------------
915 ------------------------------------------------------------------------
918 { An arbitrary machine address assumed to point outside
919 the garbage-collected heap. }
921 pseudoop "nullAddr#" Addr#
922 { The null address. }
924 primop AddrAddOp "plusAddr#" GenPrimOp Addr# -> Int# -> Addr#
925 primop AddrSubOp "minusAddr#" GenPrimOp Addr# -> Addr# -> Int#
926 {Result is meaningless if two {\tt Addr\#}s are so far apart that their
927 difference doesn't fit in an {\tt Int\#}.}
928 primop AddrRemOp "remAddr#" GenPrimOp Addr# -> Int# -> Int#
929 {Return the remainder when the {\tt Addr\#} arg, treated like an {\tt Int\#},
930 is divided by the {\tt Int\#} arg.}
931 #if (WORD_SIZE_IN_BITS == 32 || WORD_SIZE_IN_BITS == 64)
932 primop Addr2IntOp "addr2Int#" GenPrimOp Addr# -> Int#
933 {Coerce directly from address to int. Strongly deprecated.}
934 primop Int2AddrOp "int2Addr#" GenPrimOp Int# -> Addr#
935 {Coerce directly from int to address. Strongly deprecated.}
938 primop AddrGtOp "gtAddr#" Compare Addr# -> Addr# -> Bool
939 primop AddrGeOp "geAddr#" Compare Addr# -> Addr# -> Bool
940 primop AddrEqOp "eqAddr#" Compare Addr# -> Addr# -> Bool
941 primop AddrNeOp "neAddr#" Compare Addr# -> Addr# -> Bool
942 primop AddrLtOp "ltAddr#" Compare Addr# -> Addr# -> Bool
943 primop AddrLeOp "leAddr#" Compare Addr# -> Addr# -> Bool
945 primop IndexOffAddrOp_Char "indexCharOffAddr#" GenPrimOp
946 Addr# -> Int# -> Char#
947 {Reads 8-bit character; offset in bytes.}
949 primop IndexOffAddrOp_WideChar "indexWideCharOffAddr#" GenPrimOp
950 Addr# -> Int# -> Char#
951 {Reads 31-bit character; offset in 4-byte words.}
953 primop IndexOffAddrOp_Int "indexIntOffAddr#" GenPrimOp
954 Addr# -> Int# -> Int#
956 primop IndexOffAddrOp_Word "indexWordOffAddr#" GenPrimOp
957 Addr# -> Int# -> Word#
959 primop IndexOffAddrOp_Addr "indexAddrOffAddr#" GenPrimOp
960 Addr# -> Int# -> Addr#
962 primop IndexOffAddrOp_Float "indexFloatOffAddr#" GenPrimOp
963 Addr# -> Int# -> Float#
965 primop IndexOffAddrOp_Double "indexDoubleOffAddr#" GenPrimOp
966 Addr# -> Int# -> Double#
968 primop IndexOffAddrOp_StablePtr "indexStablePtrOffAddr#" GenPrimOp
969 Addr# -> Int# -> StablePtr# a
971 primop IndexOffAddrOp_Int8 "indexInt8OffAddr#" GenPrimOp
972 Addr# -> Int# -> Int#
974 primop IndexOffAddrOp_Int16 "indexInt16OffAddr#" GenPrimOp
975 Addr# -> Int# -> Int#
977 primop IndexOffAddrOp_Int32 "indexInt32OffAddr#" GenPrimOp
978 Addr# -> Int# -> INT32
980 primop IndexOffAddrOp_Int64 "indexInt64OffAddr#" GenPrimOp
981 Addr# -> Int# -> INT64
983 primop IndexOffAddrOp_Word8 "indexWord8OffAddr#" GenPrimOp
984 Addr# -> Int# -> Word#
986 primop IndexOffAddrOp_Word16 "indexWord16OffAddr#" GenPrimOp
987 Addr# -> Int# -> Word#
989 primop IndexOffAddrOp_Word32 "indexWord32OffAddr#" GenPrimOp
990 Addr# -> Int# -> WORD32
992 primop IndexOffAddrOp_Word64 "indexWord64OffAddr#" GenPrimOp
993 Addr# -> Int# -> WORD64
995 primop ReadOffAddrOp_Char "readCharOffAddr#" GenPrimOp
996 Addr# -> Int# -> State# s -> (# State# s, Char# #)
997 {Reads 8-bit character; offset in bytes.}
998 with has_side_effects = True
1000 primop ReadOffAddrOp_WideChar "readWideCharOffAddr#" GenPrimOp
1001 Addr# -> Int# -> State# s -> (# State# s, Char# #)
1002 {Reads 31-bit character; offset in 4-byte words.}
1003 with has_side_effects = True
1005 primop ReadOffAddrOp_Int "readIntOffAddr#" GenPrimOp
1006 Addr# -> Int# -> State# s -> (# State# s, Int# #)
1007 with has_side_effects = True
1009 primop ReadOffAddrOp_Word "readWordOffAddr#" GenPrimOp
1010 Addr# -> Int# -> State# s -> (# State# s, Word# #)
1011 with has_side_effects = True
1013 primop ReadOffAddrOp_Addr "readAddrOffAddr#" GenPrimOp
1014 Addr# -> Int# -> State# s -> (# State# s, Addr# #)
1015 with has_side_effects = True
1017 primop ReadOffAddrOp_Float "readFloatOffAddr#" GenPrimOp
1018 Addr# -> Int# -> State# s -> (# State# s, Float# #)
1019 with has_side_effects = True
1021 primop ReadOffAddrOp_Double "readDoubleOffAddr#" GenPrimOp
1022 Addr# -> Int# -> State# s -> (# State# s, Double# #)
1023 with has_side_effects = True
1025 primop ReadOffAddrOp_StablePtr "readStablePtrOffAddr#" GenPrimOp
1026 Addr# -> Int# -> State# s -> (# State# s, StablePtr# a #)
1027 with has_side_effects = True
1029 primop ReadOffAddrOp_Int8 "readInt8OffAddr#" GenPrimOp
1030 Addr# -> Int# -> State# s -> (# State# s, Int# #)
1031 with has_side_effects = True
1033 primop ReadOffAddrOp_Int16 "readInt16OffAddr#" GenPrimOp
1034 Addr# -> Int# -> State# s -> (# State# s, Int# #)
1035 with has_side_effects = True
1037 primop ReadOffAddrOp_Int32 "readInt32OffAddr#" GenPrimOp
1038 Addr# -> Int# -> State# s -> (# State# s, INT32 #)
1039 with has_side_effects = True
1041 primop ReadOffAddrOp_Int64 "readInt64OffAddr#" GenPrimOp
1042 Addr# -> Int# -> State# s -> (# State# s, INT64 #)
1043 with has_side_effects = True
1045 primop ReadOffAddrOp_Word8 "readWord8OffAddr#" GenPrimOp
1046 Addr# -> Int# -> State# s -> (# State# s, Word# #)
1047 with has_side_effects = True
1049 primop ReadOffAddrOp_Word16 "readWord16OffAddr#" GenPrimOp
1050 Addr# -> Int# -> State# s -> (# State# s, Word# #)
1051 with has_side_effects = True
1053 primop ReadOffAddrOp_Word32 "readWord32OffAddr#" GenPrimOp
1054 Addr# -> Int# -> State# s -> (# State# s, WORD32 #)
1055 with has_side_effects = True
1057 primop ReadOffAddrOp_Word64 "readWord64OffAddr#" GenPrimOp
1058 Addr# -> Int# -> State# s -> (# State# s, WORD64 #)
1059 with has_side_effects = True
1062 primop WriteOffAddrOp_Char "writeCharOffAddr#" GenPrimOp
1063 Addr# -> Int# -> Char# -> State# s -> State# s
1064 with has_side_effects = True
1066 primop WriteOffAddrOp_WideChar "writeWideCharOffAddr#" GenPrimOp
1067 Addr# -> Int# -> Char# -> State# s -> State# s
1068 with has_side_effects = True
1070 primop WriteOffAddrOp_Int "writeIntOffAddr#" GenPrimOp
1071 Addr# -> Int# -> Int# -> State# s -> State# s
1072 with has_side_effects = True
1074 primop WriteOffAddrOp_Word "writeWordOffAddr#" GenPrimOp
1075 Addr# -> Int# -> Word# -> State# s -> State# s
1076 with has_side_effects = True
1078 primop WriteOffAddrOp_Addr "writeAddrOffAddr#" GenPrimOp
1079 Addr# -> Int# -> Addr# -> State# s -> State# s
1080 with has_side_effects = True
1082 primop WriteOffAddrOp_Float "writeFloatOffAddr#" GenPrimOp
1083 Addr# -> Int# -> Float# -> State# s -> State# s
1084 with has_side_effects = True
1086 primop WriteOffAddrOp_Double "writeDoubleOffAddr#" GenPrimOp
1087 Addr# -> Int# -> Double# -> State# s -> State# s
1088 with has_side_effects = True
1090 primop WriteOffAddrOp_StablePtr "writeStablePtrOffAddr#" GenPrimOp
1091 Addr# -> Int# -> StablePtr# a -> State# s -> State# s
1092 with has_side_effects = True
1094 primop WriteOffAddrOp_Int8 "writeInt8OffAddr#" GenPrimOp
1095 Addr# -> Int# -> Int# -> State# s -> State# s
1096 with has_side_effects = True
1098 primop WriteOffAddrOp_Int16 "writeInt16OffAddr#" GenPrimOp
1099 Addr# -> Int# -> Int# -> State# s -> State# s
1100 with has_side_effects = True
1102 primop WriteOffAddrOp_Int32 "writeInt32OffAddr#" GenPrimOp
1103 Addr# -> Int# -> INT32 -> State# s -> State# s
1104 with has_side_effects = True
1106 primop WriteOffAddrOp_Int64 "writeInt64OffAddr#" GenPrimOp
1107 Addr# -> Int# -> INT64 -> State# s -> State# s
1108 with has_side_effects = True
1110 primop WriteOffAddrOp_Word8 "writeWord8OffAddr#" GenPrimOp
1111 Addr# -> Int# -> Word# -> State# s -> State# s
1112 with has_side_effects = True
1114 primop WriteOffAddrOp_Word16 "writeWord16OffAddr#" GenPrimOp
1115 Addr# -> Int# -> Word# -> State# s -> State# s
1116 with has_side_effects = True
1118 primop WriteOffAddrOp_Word32 "writeWord32OffAddr#" GenPrimOp
1119 Addr# -> Int# -> WORD32 -> State# s -> State# s
1120 with has_side_effects = True
1122 primop WriteOffAddrOp_Word64 "writeWord64OffAddr#" GenPrimOp
1123 Addr# -> Int# -> WORD64 -> State# s -> State# s
1124 with has_side_effects = True
1126 ------------------------------------------------------------------------
1127 section "Mutable variables"
1128 {Operations on MutVar\#s.}
1129 ------------------------------------------------------------------------
1131 primtype MutVar# s a
1132 {A {\tt MutVar\#} behaves like a single-element mutable array.}
1134 primop NewMutVarOp "newMutVar#" GenPrimOp
1135 a -> State# s -> (# State# s, MutVar# s a #)
1136 {Create {\tt MutVar\#} with specified initial value in specified state thread.}
1139 has_side_effects = True
1141 primop ReadMutVarOp "readMutVar#" GenPrimOp
1142 MutVar# s a -> State# s -> (# State# s, a #)
1143 {Read contents of {\tt MutVar\#}. Result is not yet evaluated.}
1145 has_side_effects = True
1147 primop WriteMutVarOp "writeMutVar#" GenPrimOp
1148 MutVar# s a -> a -> State# s -> State# s
1149 {Write contents of {\tt MutVar\#}.}
1151 has_side_effects = True
1153 primop SameMutVarOp "sameMutVar#" GenPrimOp
1154 MutVar# s a -> MutVar# s a -> Bool
1156 -- not really the right type, but we don't know about pairs here. The
1159 -- MutVar# s a -> (a -> (a,b)) -> State# s -> (# State# s, b #)
1161 primop AtomicModifyMutVarOp "atomicModifyMutVar#" GenPrimOp
1162 MutVar# s a -> (a -> b) -> State# s -> (# State# s, c #)
1165 has_side_effects = True
1167 primop CasMutVarOp "casMutVar#" GenPrimOp
1168 MutVar# s a -> a -> a -> State# s -> (# State# s, Int#, a #)
1171 has_side_effects = True
1173 ------------------------------------------------------------------------
1174 section "Exceptions"
1175 ------------------------------------------------------------------------
1177 primop CatchOp "catch#" GenPrimOp
1178 (State# RealWorld -> (# State# RealWorld, a #) )
1179 -> (b -> State# RealWorld -> (# State# RealWorld, a #) )
1181 -> (# State# RealWorld, a #)
1183 -- Catch is actually strict in its first argument
1184 -- but we don't want to tell the strictness
1185 -- analyser about that!
1186 -- might use caught action multiply
1188 has_side_effects = True
1190 primop RaiseOp "raise#" GenPrimOp
1193 strictness = { \ _arity -> mkStrictSig (mkTopDmdType [lazyDmd] BotRes) }
1194 -- NB: result is bottom
1197 -- raiseIO# needs to be a primop, because exceptions in the IO monad
1198 -- must be *precise* - we don't want the strictness analyser turning
1199 -- one kind of bottom into another, as it is allowed to do in pure code.
1201 -- But we *do* want to know that it returns bottom after
1202 -- being applied to two arguments
1204 primop RaiseIOOp "raiseIO#" GenPrimOp
1205 a -> State# RealWorld -> (# State# RealWorld, b #)
1207 strictness = { \ _arity -> mkStrictSig (mkTopDmdType [lazyDmd,lazyDmd] BotRes) }
1209 has_side_effects = True
1211 primop MaskAsyncExceptionsOp "maskAsyncExceptions#" GenPrimOp
1212 (State# RealWorld -> (# State# RealWorld, a #))
1213 -> (State# RealWorld -> (# State# RealWorld, a #))
1216 has_side_effects = True
1218 primop MaskUninterruptibleOp "maskUninterruptible#" GenPrimOp
1219 (State# RealWorld -> (# State# RealWorld, a #))
1220 -> (State# RealWorld -> (# State# RealWorld, a #))
1223 has_side_effects = True
1225 primop UnmaskAsyncExceptionsOp "unmaskAsyncExceptions#" GenPrimOp
1226 (State# RealWorld -> (# State# RealWorld, a #))
1227 -> (State# RealWorld -> (# State# RealWorld, a #))
1230 has_side_effects = True
1232 primop MaskStatus "getMaskingState#" GenPrimOp
1233 State# RealWorld -> (# State# RealWorld, Int# #)
1236 has_side_effects = True
1238 ------------------------------------------------------------------------
1239 section "STM-accessible Mutable Variables"
1240 ------------------------------------------------------------------------
1244 primop AtomicallyOp "atomically#" GenPrimOp
1245 (State# RealWorld -> (# State# RealWorld, a #) )
1246 -> State# RealWorld -> (# State# RealWorld, a #)
1249 has_side_effects = True
1251 primop RetryOp "retry#" GenPrimOp
1252 State# RealWorld -> (# State# RealWorld, a #)
1255 has_side_effects = True
1257 primop CatchRetryOp "catchRetry#" GenPrimOp
1258 (State# RealWorld -> (# State# RealWorld, a #) )
1259 -> (State# RealWorld -> (# State# RealWorld, a #) )
1260 -> (State# RealWorld -> (# State# RealWorld, a #) )
1263 has_side_effects = True
1265 primop CatchSTMOp "catchSTM#" GenPrimOp
1266 (State# RealWorld -> (# State# RealWorld, a #) )
1267 -> (b -> State# RealWorld -> (# State# RealWorld, a #) )
1268 -> (State# RealWorld -> (# State# RealWorld, a #) )
1271 has_side_effects = True
1273 primop Check "check#" GenPrimOp
1274 (State# RealWorld -> (# State# RealWorld, a #) )
1275 -> (State# RealWorld -> (# State# RealWorld, () #) )
1278 has_side_effects = True
1280 primop NewTVarOp "newTVar#" GenPrimOp
1282 -> State# s -> (# State# s, TVar# s a #)
1283 {Create a new {\tt TVar\#} holding a specified initial value.}
1286 has_side_effects = True
1288 primop ReadTVarOp "readTVar#" GenPrimOp
1290 -> State# s -> (# State# s, a #)
1291 {Read contents of {\tt TVar\#}. Result is not yet evaluated.}
1294 has_side_effects = True
1296 primop ReadTVarIOOp "readTVarIO#" GenPrimOp
1298 -> State# s -> (# State# s, a #)
1299 {Read contents of {\tt TVar\#} outside an STM transaction}
1302 has_side_effects = True
1304 primop WriteTVarOp "writeTVar#" GenPrimOp
1307 -> State# s -> State# s
1308 {Write contents of {\tt TVar\#}.}
1311 has_side_effects = True
1313 primop SameTVarOp "sameTVar#" GenPrimOp
1314 TVar# s a -> TVar# s a -> Bool
1317 ------------------------------------------------------------------------
1318 section "Synchronized Mutable Variables"
1319 {Operations on {\tt MVar\#}s. }
1320 ------------------------------------------------------------------------
1323 { A shared mutable variable ({\it not} the same as a {\tt MutVar\#}!).
1324 (Note: in a non-concurrent implementation, {\tt (MVar\# a)} can be
1325 represented by {\tt (MutVar\# (Maybe a))}.) }
1327 primop NewMVarOp "newMVar#" GenPrimOp
1328 State# s -> (# State# s, MVar# s a #)
1329 {Create new {\tt MVar\#}; initially empty.}
1332 has_side_effects = True
1334 primop TakeMVarOp "takeMVar#" GenPrimOp
1335 MVar# s a -> State# s -> (# State# s, a #)
1336 {If {\tt MVar\#} is empty, block until it becomes full.
1337 Then remove and return its contents, and set it empty.}
1340 has_side_effects = True
1342 primop TryTakeMVarOp "tryTakeMVar#" GenPrimOp
1343 MVar# s a -> State# s -> (# State# s, Int#, a #)
1344 {If {\tt MVar\#} is empty, immediately return with integer 0 and value undefined.
1345 Otherwise, return with integer 1 and contents of {\tt MVar\#}, and set {\tt MVar\#} empty.}
1348 has_side_effects = True
1350 primop PutMVarOp "putMVar#" GenPrimOp
1351 MVar# s a -> a -> State# s -> State# s
1352 {If {\tt MVar\#} is full, block until it becomes empty.
1353 Then store value arg as its new contents.}
1356 has_side_effects = True
1358 primop TryPutMVarOp "tryPutMVar#" GenPrimOp
1359 MVar# s a -> a -> State# s -> (# State# s, Int# #)
1360 {If {\tt MVar\#} is full, immediately return with integer 0.
1361 Otherwise, store value arg as {\tt MVar\#}'s new contents, and return with integer 1.}
1364 has_side_effects = True
1366 primop SameMVarOp "sameMVar#" GenPrimOp
1367 MVar# s a -> MVar# s a -> Bool
1369 primop IsEmptyMVarOp "isEmptyMVar#" GenPrimOp
1370 MVar# s a -> State# s -> (# State# s, Int# #)
1371 {Return 1 if {\tt MVar\#} is empty; 0 otherwise.}
1374 has_side_effects = True
1376 ------------------------------------------------------------------------
1377 section "Delay/wait operations"
1378 ------------------------------------------------------------------------
1380 primop DelayOp "delay#" GenPrimOp
1381 Int# -> State# s -> State# s
1382 {Sleep specified number of microseconds.}
1384 needs_wrapper = True
1385 has_side_effects = True
1388 primop WaitReadOp "waitRead#" GenPrimOp
1389 Int# -> State# s -> State# s
1390 {Block until input is available on specified file descriptor.}
1392 needs_wrapper = True
1393 has_side_effects = True
1396 primop WaitWriteOp "waitWrite#" GenPrimOp
1397 Int# -> State# s -> State# s
1398 {Block until output is possible on specified file descriptor.}
1400 needs_wrapper = True
1401 has_side_effects = True
1404 #ifdef mingw32_TARGET_OS
1405 primop AsyncReadOp "asyncRead#" GenPrimOp
1406 Int# -> Int# -> Int# -> Addr# -> State# RealWorld-> (# State# RealWorld, Int#, Int# #)
1407 {Asynchronously read bytes from specified file descriptor.}
1409 needs_wrapper = True
1410 has_side_effects = True
1413 primop AsyncWriteOp "asyncWrite#" GenPrimOp
1414 Int# -> Int# -> Int# -> Addr# -> State# RealWorld-> (# State# RealWorld, Int#, Int# #)
1415 {Asynchronously write bytes from specified file descriptor.}
1417 needs_wrapper = True
1418 has_side_effects = True
1421 primop AsyncDoProcOp "asyncDoProc#" GenPrimOp
1422 Addr# -> Addr# -> State# RealWorld-> (# State# RealWorld, Int#, Int# #)
1423 {Asynchronously perform procedure (first arg), passing it 2nd arg.}
1425 needs_wrapper = True
1426 has_side_effects = True
1431 ------------------------------------------------------------------------
1432 section "Concurrency primitives"
1433 ------------------------------------------------------------------------
1436 { {\tt State\#} is the primitive, unlifted type of states. It has
1437 one type parameter, thus {\tt State\# RealWorld}, or {\tt State\# s},
1438 where s is a type variable. The only purpose of the type parameter
1439 is to keep different state threads separate. It is represented by
1443 { {\tt RealWorld} is deeply magical. It is {\it primitive}, but it is not
1444 {\it unlifted} (hence {\tt ptrArg}). We never manipulate values of type
1445 {\tt RealWorld}; it's only used in the type system, to parameterise {\tt State\#}. }
1448 {(In a non-concurrent implementation, this can be a singleton
1449 type, whose (unique) value is returned by {\tt myThreadId\#}. The
1450 other operations can be omitted.)}
1452 primop ForkOp "fork#" GenPrimOp
1453 a -> State# RealWorld -> (# State# RealWorld, ThreadId# #)
1455 has_side_effects = True
1458 primop ForkOnOp "forkOn#" GenPrimOp
1459 Int# -> a -> State# RealWorld -> (# State# RealWorld, ThreadId# #)
1461 has_side_effects = True
1464 primop KillThreadOp "killThread#" GenPrimOp
1465 ThreadId# -> a -> State# RealWorld -> State# RealWorld
1467 has_side_effects = True
1470 primop YieldOp "yield#" GenPrimOp
1471 State# RealWorld -> State# RealWorld
1473 has_side_effects = True
1476 primop MyThreadIdOp "myThreadId#" GenPrimOp
1477 State# RealWorld -> (# State# RealWorld, ThreadId# #)
1480 has_side_effects = True
1482 primop LabelThreadOp "labelThread#" GenPrimOp
1483 ThreadId# -> Addr# -> State# RealWorld -> State# RealWorld
1485 has_side_effects = True
1488 primop IsCurrentThreadBoundOp "isCurrentThreadBound#" GenPrimOp
1489 State# RealWorld -> (# State# RealWorld, Int# #)
1492 has_side_effects = True
1494 primop NoDuplicateOp "noDuplicate#" GenPrimOp
1495 State# RealWorld -> State# RealWorld
1498 has_side_effects = True
1500 primop ThreadStatusOp "threadStatus#" GenPrimOp
1501 ThreadId# -> State# RealWorld -> (# State# RealWorld, Int#, Int#, Int# #)
1504 has_side_effects = True
1506 ------------------------------------------------------------------------
1507 section "Weak pointers"
1508 ------------------------------------------------------------------------
1512 -- note that tyvar "o" denotes openAlphaTyVar
1514 primop MkWeakOp "mkWeak#" GenPrimOp
1515 o -> b -> c -> State# RealWorld -> (# State# RealWorld, Weak# b #)
1517 has_side_effects = True
1520 primop MkWeakForeignEnvOp "mkWeakForeignEnv#" GenPrimOp
1521 o -> b -> Addr# -> Addr# -> Int# -> Addr# -> State# RealWorld -> (# State# RealWorld, Weak# b #)
1523 has_side_effects = True
1526 primop DeRefWeakOp "deRefWeak#" GenPrimOp
1527 Weak# a -> State# RealWorld -> (# State# RealWorld, Int#, a #)
1529 has_side_effects = True
1532 primop FinalizeWeakOp "finalizeWeak#" GenPrimOp
1533 Weak# a -> State# RealWorld -> (# State# RealWorld, Int#,
1534 (State# RealWorld -> (# State# RealWorld, () #)) #)
1536 has_side_effects = True
1539 primop TouchOp "touch#" GenPrimOp
1540 o -> State# RealWorld -> State# RealWorld
1542 has_side_effects = True
1544 ------------------------------------------------------------------------
1545 section "Stable pointers and names"
1546 ------------------------------------------------------------------------
1548 primtype StablePtr# a
1550 primtype StableName# a
1552 primop MakeStablePtrOp "makeStablePtr#" GenPrimOp
1553 a -> State# RealWorld -> (# State# RealWorld, StablePtr# a #)
1555 has_side_effects = True
1558 primop DeRefStablePtrOp "deRefStablePtr#" GenPrimOp
1559 StablePtr# a -> State# RealWorld -> (# State# RealWorld, a #)
1561 needs_wrapper = True
1562 has_side_effects = True
1565 primop EqStablePtrOp "eqStablePtr#" GenPrimOp
1566 StablePtr# a -> StablePtr# a -> Int#
1568 has_side_effects = True
1570 primop MakeStableNameOp "makeStableName#" GenPrimOp
1571 a -> State# RealWorld -> (# State# RealWorld, StableName# a #)
1573 needs_wrapper = True
1574 has_side_effects = True
1577 primop EqStableNameOp "eqStableName#" GenPrimOp
1578 StableName# a -> StableName# a -> Int#
1580 primop StableNameToIntOp "stableNameToInt#" GenPrimOp
1581 StableName# a -> Int#
1583 ------------------------------------------------------------------------
1584 section "Unsafe pointer equality"
1585 -- (#1 Bad Guy: Alistair Reid :)
1586 ------------------------------------------------------------------------
1588 primop ReallyUnsafePtrEqualityOp "reallyUnsafePtrEquality#" GenPrimOp
1591 ------------------------------------------------------------------------
1592 section "Parallelism"
1593 ------------------------------------------------------------------------
1595 primop ParOp "par#" GenPrimOp
1598 -- Note that Par is lazy to avoid that the sparked thing
1599 -- gets evaluted strictly, which it should *not* be
1600 has_side_effects = True
1602 primop GetSparkOp "getSpark#" GenPrimOp
1603 State# s -> (# State# s, Int#, a #)
1605 has_side_effects = True
1608 primop NumSparks "numSparks#" GenPrimOp
1609 State# s -> (# State# s, Int# #)
1610 { Returns the number of sparks in the local spark pool. }
1612 has_side_effects = True
1615 -- HWL: The first 4 Int# in all par... annotations denote:
1616 -- name, granularity info, size of result, degree of parallelism
1617 -- Same structure as _seq_ i.e. returns Int#
1618 -- KSW: v, the second arg in parAt# and parAtForNow#, is used only to determine
1619 -- `the processor containing the expression v'; it is not evaluated
1621 primop ParGlobalOp "parGlobal#" GenPrimOp
1622 a -> Int# -> Int# -> Int# -> Int# -> b -> Int#
1624 has_side_effects = True
1626 primop ParLocalOp "parLocal#" GenPrimOp
1627 a -> Int# -> Int# -> Int# -> Int# -> b -> Int#
1629 has_side_effects = True
1631 primop ParAtOp "parAt#" GenPrimOp
1632 b -> a -> Int# -> Int# -> Int# -> Int# -> c -> Int#
1634 has_side_effects = True
1636 primop ParAtAbsOp "parAtAbs#" GenPrimOp
1637 a -> Int# -> Int# -> Int# -> Int# -> Int# -> b -> Int#
1639 has_side_effects = True
1641 primop ParAtRelOp "parAtRel#" GenPrimOp
1642 a -> Int# -> Int# -> Int# -> Int# -> Int# -> b -> Int#
1644 has_side_effects = True
1646 primop ParAtForNowOp "parAtForNow#" GenPrimOp
1647 b -> a -> Int# -> Int# -> Int# -> Int# -> c -> Int#
1649 has_side_effects = True
1651 -- copyable# and noFollow# are yet to be implemented (for GpH)
1653 --primop CopyableOp "copyable#" GenPrimOp
1656 -- has_side_effects = True
1658 --primop NoFollowOp "noFollow#" GenPrimOp
1661 -- has_side_effects = True
1664 ------------------------------------------------------------------------
1665 section "Tag to enum stuff"
1666 {Convert back and forth between values of enumerated types
1667 and small integers.}
1668 ------------------------------------------------------------------------
1670 primop DataToTagOp "dataToTag#" GenPrimOp
1673 strictness = { \ _arity -> mkStrictSig (mkTopDmdType [seqDmd] TopRes) }
1674 -- dataToTag# must have an evaluated argument
1676 primop TagToEnumOp "tagToEnum#" GenPrimOp
1679 ------------------------------------------------------------------------
1680 section "Bytecode operations"
1681 {Support for the bytecode interpreter and linker.}
1682 ------------------------------------------------------------------------
1685 {Primitive bytecode type.}
1687 primop AddrToHValueOp "addrToHValue#" GenPrimOp
1689 {Convert an {\tt Addr\#} to a followable type.}
1691 primop MkApUpd0_Op "mkApUpd0#" GenPrimOp
1696 primop NewBCOOp "newBCO#" GenPrimOp
1697 ByteArray# -> ByteArray# -> Array# a -> Int# -> ByteArray# -> State# s -> (# State# s, BCO# #)
1699 has_side_effects = True
1702 primop UnpackClosureOp "unpackClosure#" GenPrimOp
1703 a -> (# Addr#, Array# b, ByteArray# #)
1707 primop GetApStackValOp "getApStackVal#" GenPrimOp
1708 a -> Int# -> (# Int#, b #)
1712 ------------------------------------------------------------------------
1714 {These aren't nearly as wired in as Etc...}
1715 ------------------------------------------------------------------------
1717 primop TraceCcsOp "traceCcs#" GenPrimOp
1720 has_side_effects = True
1723 ------------------------------------------------------------------------
1725 {Miscellaneous built-ins}
1726 ------------------------------------------------------------------------
1730 { Evaluates its first argument to head normal form, and then returns its second
1731 argument as the result. }
1735 { The call {\tt (inline f)} arranges that f is inlined, regardless of its size.
1736 More precisely, the call {\tt (inline f)} rewrites to the right-hand side of
1737 {\tt f}'s definition. This allows the programmer to control inlining from a
1738 particular call site rather than the definition site of the function (c.f.
1739 {\tt INLINE} pragmas in User's Guide, Section 7.10.3, "INLINE and NOINLINE
1742 This inlining occurs regardless of the argument to the call or the size of
1743 {\tt f}'s definition; it is unconditional. The main caveat is that {\tt f}'s
1744 definition must be visible to the compiler. That is, {\tt f} must be
1745 {\tt let}-bound in the current scope. If no inlining takes place, the
1746 {\tt inline} function expands to the identity function in Phase zero; so its
1747 use imposes no overhead.
1749 It is good practice to mark the function with an INLINABLE pragma at
1750 its definition, (a) so that GHC guarantees to expose its unfolding regardless
1751 of size, and (b) so that you have control over exactly what is inlined. }
1755 { The {\tt lazy} function restrains strictness analysis a little. The call
1756 {\tt (lazy e)} means the same as {\tt e}, but {\tt lazy} has a magical
1757 property so far as strictness analysis is concerned: it is lazy in its first
1758 argument, even though its semantics is strict. After strictness analysis has
1759 run, calls to {\tt lazy} are inlined to be the identity function.
1761 This behaviour is occasionally useful when controlling evaluation order.
1762 Notably, {\tt lazy} is used in the library definition of {\tt Control.Parallel.par}:
1764 {\tt par :: a -> b -> b}
1766 {\tt par x y = case (par\# x) of \_ -> lazy y}
1768 If {\tt lazy} were not lazy, {\tt par} would look strict in {\tt y} which
1769 would defeat the whole purpose of {\tt par}.
1771 Like {\tt seq}, the argument of {\tt lazy} can have an unboxed type. }
1774 { The type constructor {\tt Any} is type to which you can unsafely coerce any
1775 lifted type, and back.
1777 * It is lifted, and hence represented by a pointer
1779 * It does not claim to be a {\it data} type, and that's important for
1780 the code generator, because the code gen may {\it enter} a data value
1781 but never enters a function value.
1783 It's also used to instantiate un-constrained type variables after type
1784 checking. For example, {\tt length} has type
1786 {\tt length :: forall a. [a] -> Int}
1788 and the list datacon for the empty list has type
1790 {\tt [] :: forall a. [a]}
1792 In order to compose these two terms as {\tt length []} a type
1793 application is required, but there is no constraint on the
1794 choice. In this situation GHC uses {\tt Any}:
1796 {\tt length Any ([] Any)}
1798 Annoyingly, we sometimes need {\tt Any}s of other kinds, such as {\tt (* -> *)} etc.
1799 This is a bit like tuples. We define a couple of useful ones here,
1800 and make others up on the fly. If any of these others end up being exported
1801 into interface files, we'll get a crash; at least until we add interface-file
1802 syntax to support them. }
1804 pseudoop "unsafeCoerce#"
1806 { The function {\tt unsafeCoerce\#} allows you to side-step the typechecker entirely. That
1807 is, it allows you to coerce any type into any other type. If you use this function,
1808 you had better get it right, otherwise segmentation faults await. It is generally
1809 used when you want to write a program that you know is well-typed, but where Haskell's
1810 type system is not expressive enough to prove that it is well typed.
1812 The following uses of {\tt unsafeCoerce\#} are supposed to work (i.e. not lead to
1813 spurious compile-time or run-time crashes):
1815 * Casting any lifted type to {\tt Any}
1817 * Casting {\tt Any} back to the real type
1819 * Casting an unboxed type to another unboxed type of the same size
1820 (but not coercions between floating-point and integral types)
1822 * Casting between two types that have the same runtime representation. One case is when
1823 the two types differ only in "phantom" type parameters, for example
1824 {\tt Ptr Int} to {\tt Ptr Float}, or {\tt [Int]} to {\tt [Float]} when the list is
1825 known to be empty. Also, a {\tt newtype} of a type {\tt T} has the same representation
1826 at runtime as {\tt T}.
1828 Other uses of {\tt unsafeCoerce\#} are undefined. In particular, you should not use
1829 {\tt unsafeCoerce\#} to cast a T to an algebraic data type D, unless T is also
1830 an algebraic data type. For example, do not cast {\tt Int->Int} to {\tt Bool}, even if
1831 you later cast that {\tt Bool} back to {\tt Int->Int} before applying it. The reasons
1832 have to do with GHC's internal representation details (for the congnoscenti, data values
1833 can be entered but function closures cannot). If you want a safe type to cast things
1834 to, use {\tt Any}, which is not an algebraic data type.
1838 -- NB. It is tempting to think that casting a value to a type that it doesn't have is safe
1839 -- as long as you don't "do anything" with the value in its cast form, such as seq on it. This
1840 -- isn't the case: the compiler can insert seqs itself, and if these happen at the wrong type,
1841 -- Bad Things Might Happen. See bug #1616: in this case we cast a function of type (a,b) -> (a,b)
1842 -- to () -> () and back again. The strictness analyser saw that the function was strict, but
1843 -- the wrapper had type () -> (), and hence the wrapper de-constructed the (), the worker re-constructed
1844 -- a new (), with the result that the code ended up with "case () of (a,b) -> ...".
1846 primop TraceEventOp "traceEvent#" GenPrimOp
1847 Addr# -> State# s -> State# s
1848 { Emits an event via the RTS tracing framework. The contents
1849 of the event is the zero-terminated byte string passed as the first
1850 argument. The event will be emitted either to the .eventlog file,
1851 or to stderr, depending on the runtime RTS flags. }
1853 has_side_effects = True
1856 ------------------------------------------------------------------------
1858 ------------------------------------------------------------------------