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 of specified size (in bytes),
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 IndexArrayOp "indexArray#" GenPrimOp
604 Array# a -> Int# -> (# a #)
605 {Read from specified index of immutable array. Result is packaged into
606 an unboxed singleton; the result itself is not yet evaluated.}
608 primop UnsafeFreezeArrayOp "unsafeFreezeArray#" GenPrimOp
609 MutableArray# s a -> State# s -> (# State# s, Array# a #)
610 {Make a mutable array immutable, without copying.}
612 has_side_effects = True
614 primop UnsafeThawArrayOp "unsafeThawArray#" GenPrimOp
615 Array# a -> State# s -> (# State# s, MutableArray# s a #)
616 {Make an immutable array mutable, without copying.}
619 has_side_effects = True
621 ------------------------------------------------------------------------
622 section "Byte Arrays"
623 {Operations on {\tt ByteArray\#}. A {\tt ByteArray\#} is a just a region of
624 raw memory in the garbage-collected heap, which is not
625 scanned for pointers. It carries its own size (in bytes).
627 three sets of operations for accessing byte array contents:
628 index for reading from immutable byte arrays, and read/write
629 for mutable byte arrays. Each set contains operations for a
630 range of useful primitive data types. Each operation takes
631 an offset measured in terms of the size fo the primitive type
632 being read or written.}
634 ------------------------------------------------------------------------
638 primtype MutableByteArray# s
640 primop NewByteArrayOp_Char "newByteArray#" GenPrimOp
641 Int# -> State# s -> (# State# s, MutableByteArray# s #)
642 {Create a new mutable byte array of specified size (in bytes), in
643 the specified state thread.}
644 with out_of_line = True
645 has_side_effects = True
647 primop NewPinnedByteArrayOp_Char "newPinnedByteArray#" GenPrimOp
648 Int# -> State# s -> (# State# s, MutableByteArray# s #)
649 {Create a mutable byte array that the GC guarantees not to move.}
650 with out_of_line = True
651 has_side_effects = True
653 primop NewAlignedPinnedByteArrayOp_Char "newAlignedPinnedByteArray#" GenPrimOp
654 Int# -> Int# -> State# s -> (# State# s, MutableByteArray# s #)
655 {Create a mutable byte array, aligned by the specified amount, that the GC guarantees not to move.}
656 with out_of_line = True
657 has_side_effects = True
659 primop ByteArrayContents_Char "byteArrayContents#" GenPrimOp
661 {Intended for use with pinned arrays; otherwise very unsafe!}
663 primop SameMutableByteArrayOp "sameMutableByteArray#" GenPrimOp
664 MutableByteArray# s -> MutableByteArray# s -> Bool
666 primop UnsafeFreezeByteArrayOp "unsafeFreezeByteArray#" GenPrimOp
667 MutableByteArray# s -> State# s -> (# State# s, ByteArray# #)
668 {Make a mutable byte array immutable, without copying.}
670 has_side_effects = True
672 primop SizeofByteArrayOp "sizeofByteArray#" GenPrimOp
674 {Return the size of the array in bytes.}
676 primop SizeofMutableByteArrayOp "sizeofMutableByteArray#" GenPrimOp
677 MutableByteArray# s -> Int#
678 {Return the size of the array in bytes.}
680 primop IndexByteArrayOp_Char "indexCharArray#" GenPrimOp
681 ByteArray# -> Int# -> Char#
682 {Read 8-bit character; offset in bytes.}
684 primop IndexByteArrayOp_WideChar "indexWideCharArray#" GenPrimOp
685 ByteArray# -> Int# -> Char#
686 {Read 31-bit character; offset in 4-byte words.}
688 primop IndexByteArrayOp_Int "indexIntArray#" GenPrimOp
689 ByteArray# -> Int# -> Int#
691 primop IndexByteArrayOp_Word "indexWordArray#" GenPrimOp
692 ByteArray# -> Int# -> Word#
694 primop IndexByteArrayOp_Addr "indexAddrArray#" GenPrimOp
695 ByteArray# -> Int# -> Addr#
697 primop IndexByteArrayOp_Float "indexFloatArray#" GenPrimOp
698 ByteArray# -> Int# -> Float#
700 primop IndexByteArrayOp_Double "indexDoubleArray#" GenPrimOp
701 ByteArray# -> Int# -> Double#
703 primop IndexByteArrayOp_StablePtr "indexStablePtrArray#" GenPrimOp
704 ByteArray# -> Int# -> StablePtr# a
706 primop IndexByteArrayOp_Int8 "indexInt8Array#" GenPrimOp
707 ByteArray# -> Int# -> Int#
709 primop IndexByteArrayOp_Int16 "indexInt16Array#" GenPrimOp
710 ByteArray# -> Int# -> Int#
712 primop IndexByteArrayOp_Int32 "indexInt32Array#" GenPrimOp
713 ByteArray# -> Int# -> INT32
715 primop IndexByteArrayOp_Int64 "indexInt64Array#" GenPrimOp
716 ByteArray# -> Int# -> INT64
718 primop IndexByteArrayOp_Word8 "indexWord8Array#" GenPrimOp
719 ByteArray# -> Int# -> Word#
721 primop IndexByteArrayOp_Word16 "indexWord16Array#" GenPrimOp
722 ByteArray# -> Int# -> Word#
724 primop IndexByteArrayOp_Word32 "indexWord32Array#" GenPrimOp
725 ByteArray# -> Int# -> WORD32
727 primop IndexByteArrayOp_Word64 "indexWord64Array#" GenPrimOp
728 ByteArray# -> Int# -> WORD64
730 primop ReadByteArrayOp_Char "readCharArray#" GenPrimOp
731 MutableByteArray# s -> Int# -> State# s -> (# State# s, Char# #)
732 {Read 8-bit character; offset in bytes.}
733 with has_side_effects = True
735 primop ReadByteArrayOp_WideChar "readWideCharArray#" GenPrimOp
736 MutableByteArray# s -> Int# -> State# s -> (# State# s, Char# #)
737 {Read 31-bit character; offset in 4-byte words.}
738 with has_side_effects = True
740 primop ReadByteArrayOp_Int "readIntArray#" GenPrimOp
741 MutableByteArray# s -> Int# -> State# s -> (# State# s, Int# #)
742 with has_side_effects = True
744 primop ReadByteArrayOp_Word "readWordArray#" GenPrimOp
745 MutableByteArray# s -> Int# -> State# s -> (# State# s, Word# #)
746 with has_side_effects = True
748 primop ReadByteArrayOp_Addr "readAddrArray#" GenPrimOp
749 MutableByteArray# s -> Int# -> State# s -> (# State# s, Addr# #)
750 with has_side_effects = True
752 primop ReadByteArrayOp_Float "readFloatArray#" GenPrimOp
753 MutableByteArray# s -> Int# -> State# s -> (# State# s, Float# #)
754 with has_side_effects = True
756 primop ReadByteArrayOp_Double "readDoubleArray#" GenPrimOp
757 MutableByteArray# s -> Int# -> State# s -> (# State# s, Double# #)
758 with has_side_effects = True
760 primop ReadByteArrayOp_StablePtr "readStablePtrArray#" GenPrimOp
761 MutableByteArray# s -> Int# -> State# s -> (# State# s, StablePtr# a #)
762 with has_side_effects = True
764 primop ReadByteArrayOp_Int8 "readInt8Array#" GenPrimOp
765 MutableByteArray# s -> Int# -> State# s -> (# State# s, Int# #)
766 with has_side_effects = True
768 primop ReadByteArrayOp_Int16 "readInt16Array#" GenPrimOp
769 MutableByteArray# s -> Int# -> State# s -> (# State# s, Int# #)
770 with has_side_effects = True
772 primop ReadByteArrayOp_Int32 "readInt32Array#" GenPrimOp
773 MutableByteArray# s -> Int# -> State# s -> (# State# s, INT32 #)
774 with has_side_effects = True
776 primop ReadByteArrayOp_Int64 "readInt64Array#" GenPrimOp
777 MutableByteArray# s -> Int# -> State# s -> (# State# s, INT64 #)
778 with has_side_effects = True
780 primop ReadByteArrayOp_Word8 "readWord8Array#" GenPrimOp
781 MutableByteArray# s -> Int# -> State# s -> (# State# s, Word# #)
782 with has_side_effects = True
784 primop ReadByteArrayOp_Word16 "readWord16Array#" GenPrimOp
785 MutableByteArray# s -> Int# -> State# s -> (# State# s, Word# #)
786 with has_side_effects = True
788 primop ReadByteArrayOp_Word32 "readWord32Array#" GenPrimOp
789 MutableByteArray# s -> Int# -> State# s -> (# State# s, WORD32 #)
790 with has_side_effects = True
792 primop ReadByteArrayOp_Word64 "readWord64Array#" GenPrimOp
793 MutableByteArray# s -> Int# -> State# s -> (# State# s, WORD64 #)
794 with has_side_effects = True
796 primop WriteByteArrayOp_Char "writeCharArray#" GenPrimOp
797 MutableByteArray# s -> Int# -> Char# -> State# s -> State# s
798 {Write 8-bit character; offset in bytes.}
799 with has_side_effects = True
801 primop WriteByteArrayOp_WideChar "writeWideCharArray#" GenPrimOp
802 MutableByteArray# s -> Int# -> Char# -> State# s -> State# s
803 {Write 31-bit character; offset in 4-byte words.}
804 with has_side_effects = True
806 primop WriteByteArrayOp_Int "writeIntArray#" GenPrimOp
807 MutableByteArray# s -> Int# -> Int# -> State# s -> State# s
808 with has_side_effects = True
810 primop WriteByteArrayOp_Word "writeWordArray#" GenPrimOp
811 MutableByteArray# s -> Int# -> Word# -> State# s -> State# s
812 with has_side_effects = True
814 primop WriteByteArrayOp_Addr "writeAddrArray#" GenPrimOp
815 MutableByteArray# s -> Int# -> Addr# -> State# s -> State# s
816 with has_side_effects = True
818 primop WriteByteArrayOp_Float "writeFloatArray#" GenPrimOp
819 MutableByteArray# s -> Int# -> Float# -> State# s -> State# s
820 with has_side_effects = True
822 primop WriteByteArrayOp_Double "writeDoubleArray#" GenPrimOp
823 MutableByteArray# s -> Int# -> Double# -> State# s -> State# s
824 with has_side_effects = True
826 primop WriteByteArrayOp_StablePtr "writeStablePtrArray#" GenPrimOp
827 MutableByteArray# s -> Int# -> StablePtr# a -> State# s -> State# s
828 with has_side_effects = True
830 primop WriteByteArrayOp_Int8 "writeInt8Array#" GenPrimOp
831 MutableByteArray# s -> Int# -> Int# -> State# s -> State# s
832 with has_side_effects = True
834 primop WriteByteArrayOp_Int16 "writeInt16Array#" GenPrimOp
835 MutableByteArray# s -> Int# -> Int# -> State# s -> State# s
836 with has_side_effects = True
838 primop WriteByteArrayOp_Int32 "writeInt32Array#" GenPrimOp
839 MutableByteArray# s -> Int# -> INT32 -> State# s -> State# s
840 with has_side_effects = True
842 primop WriteByteArrayOp_Int64 "writeInt64Array#" GenPrimOp
843 MutableByteArray# s -> Int# -> INT64 -> State# s -> State# s
844 with has_side_effects = True
846 primop WriteByteArrayOp_Word8 "writeWord8Array#" GenPrimOp
847 MutableByteArray# s -> Int# -> Word# -> State# s -> State# s
848 with has_side_effects = True
850 primop WriteByteArrayOp_Word16 "writeWord16Array#" GenPrimOp
851 MutableByteArray# s -> Int# -> Word# -> State# s -> State# s
852 with has_side_effects = True
854 primop WriteByteArrayOp_Word32 "writeWord32Array#" GenPrimOp
855 MutableByteArray# s -> Int# -> WORD32 -> State# s -> State# s
856 with has_side_effects = True
858 primop WriteByteArrayOp_Word64 "writeWord64Array#" GenPrimOp
859 MutableByteArray# s -> Int# -> WORD64 -> State# s -> State# s
860 with has_side_effects = True
862 ------------------------------------------------------------------------
864 ------------------------------------------------------------------------
867 { An arbitrary machine address assumed to point outside
868 the garbage-collected heap. }
870 pseudoop "nullAddr#" Addr#
871 { The null address. }
873 primop AddrAddOp "plusAddr#" GenPrimOp Addr# -> Int# -> Addr#
874 primop AddrSubOp "minusAddr#" GenPrimOp Addr# -> Addr# -> Int#
875 {Result is meaningless if two {\tt Addr\#}s are so far apart that their
876 difference doesn't fit in an {\tt Int\#}.}
877 primop AddrRemOp "remAddr#" GenPrimOp Addr# -> Int# -> Int#
878 {Return the remainder when the {\tt Addr\#} arg, treated like an {\tt Int\#},
879 is divided by the {\tt Int\#} arg.}
880 #if (WORD_SIZE_IN_BITS == 32 || WORD_SIZE_IN_BITS == 64)
881 primop Addr2IntOp "addr2Int#" GenPrimOp Addr# -> Int#
882 {Coerce directly from address to int. Strongly deprecated.}
883 primop Int2AddrOp "int2Addr#" GenPrimOp Int# -> Addr#
884 {Coerce directly from int to address. Strongly deprecated.}
887 primop AddrGtOp "gtAddr#" Compare Addr# -> Addr# -> Bool
888 primop AddrGeOp "geAddr#" Compare Addr# -> Addr# -> Bool
889 primop AddrEqOp "eqAddr#" Compare Addr# -> Addr# -> Bool
890 primop AddrNeOp "neAddr#" Compare Addr# -> Addr# -> Bool
891 primop AddrLtOp "ltAddr#" Compare Addr# -> Addr# -> Bool
892 primop AddrLeOp "leAddr#" Compare Addr# -> Addr# -> Bool
894 primop IndexOffAddrOp_Char "indexCharOffAddr#" GenPrimOp
895 Addr# -> Int# -> Char#
896 {Reads 8-bit character; offset in bytes.}
898 primop IndexOffAddrOp_WideChar "indexWideCharOffAddr#" GenPrimOp
899 Addr# -> Int# -> Char#
900 {Reads 31-bit character; offset in 4-byte words.}
902 primop IndexOffAddrOp_Int "indexIntOffAddr#" GenPrimOp
903 Addr# -> Int# -> Int#
905 primop IndexOffAddrOp_Word "indexWordOffAddr#" GenPrimOp
906 Addr# -> Int# -> Word#
908 primop IndexOffAddrOp_Addr "indexAddrOffAddr#" GenPrimOp
909 Addr# -> Int# -> Addr#
911 primop IndexOffAddrOp_Float "indexFloatOffAddr#" GenPrimOp
912 Addr# -> Int# -> Float#
914 primop IndexOffAddrOp_Double "indexDoubleOffAddr#" GenPrimOp
915 Addr# -> Int# -> Double#
917 primop IndexOffAddrOp_StablePtr "indexStablePtrOffAddr#" GenPrimOp
918 Addr# -> Int# -> StablePtr# a
920 primop IndexOffAddrOp_Int8 "indexInt8OffAddr#" GenPrimOp
921 Addr# -> Int# -> Int#
923 primop IndexOffAddrOp_Int16 "indexInt16OffAddr#" GenPrimOp
924 Addr# -> Int# -> Int#
926 primop IndexOffAddrOp_Int32 "indexInt32OffAddr#" GenPrimOp
927 Addr# -> Int# -> INT32
929 primop IndexOffAddrOp_Int64 "indexInt64OffAddr#" GenPrimOp
930 Addr# -> Int# -> INT64
932 primop IndexOffAddrOp_Word8 "indexWord8OffAddr#" GenPrimOp
933 Addr# -> Int# -> Word#
935 primop IndexOffAddrOp_Word16 "indexWord16OffAddr#" GenPrimOp
936 Addr# -> Int# -> Word#
938 primop IndexOffAddrOp_Word32 "indexWord32OffAddr#" GenPrimOp
939 Addr# -> Int# -> WORD32
941 primop IndexOffAddrOp_Word64 "indexWord64OffAddr#" GenPrimOp
942 Addr# -> Int# -> WORD64
944 primop ReadOffAddrOp_Char "readCharOffAddr#" GenPrimOp
945 Addr# -> Int# -> State# s -> (# State# s, Char# #)
946 {Reads 8-bit character; offset in bytes.}
947 with has_side_effects = True
949 primop ReadOffAddrOp_WideChar "readWideCharOffAddr#" GenPrimOp
950 Addr# -> Int# -> State# s -> (# State# s, Char# #)
951 {Reads 31-bit character; offset in 4-byte words.}
952 with has_side_effects = True
954 primop ReadOffAddrOp_Int "readIntOffAddr#" GenPrimOp
955 Addr# -> Int# -> State# s -> (# State# s, Int# #)
956 with has_side_effects = True
958 primop ReadOffAddrOp_Word "readWordOffAddr#" GenPrimOp
959 Addr# -> Int# -> State# s -> (# State# s, Word# #)
960 with has_side_effects = True
962 primop ReadOffAddrOp_Addr "readAddrOffAddr#" GenPrimOp
963 Addr# -> Int# -> State# s -> (# State# s, Addr# #)
964 with has_side_effects = True
966 primop ReadOffAddrOp_Float "readFloatOffAddr#" GenPrimOp
967 Addr# -> Int# -> State# s -> (# State# s, Float# #)
968 with has_side_effects = True
970 primop ReadOffAddrOp_Double "readDoubleOffAddr#" GenPrimOp
971 Addr# -> Int# -> State# s -> (# State# s, Double# #)
972 with has_side_effects = True
974 primop ReadOffAddrOp_StablePtr "readStablePtrOffAddr#" GenPrimOp
975 Addr# -> Int# -> State# s -> (# State# s, StablePtr# a #)
976 with has_side_effects = True
978 primop ReadOffAddrOp_Int8 "readInt8OffAddr#" GenPrimOp
979 Addr# -> Int# -> State# s -> (# State# s, Int# #)
980 with has_side_effects = True
982 primop ReadOffAddrOp_Int16 "readInt16OffAddr#" GenPrimOp
983 Addr# -> Int# -> State# s -> (# State# s, Int# #)
984 with has_side_effects = True
986 primop ReadOffAddrOp_Int32 "readInt32OffAddr#" GenPrimOp
987 Addr# -> Int# -> State# s -> (# State# s, INT32 #)
988 with has_side_effects = True
990 primop ReadOffAddrOp_Int64 "readInt64OffAddr#" GenPrimOp
991 Addr# -> Int# -> State# s -> (# State# s, INT64 #)
992 with has_side_effects = True
994 primop ReadOffAddrOp_Word8 "readWord8OffAddr#" GenPrimOp
995 Addr# -> Int# -> State# s -> (# State# s, Word# #)
996 with has_side_effects = True
998 primop ReadOffAddrOp_Word16 "readWord16OffAddr#" GenPrimOp
999 Addr# -> Int# -> State# s -> (# State# s, Word# #)
1000 with has_side_effects = True
1002 primop ReadOffAddrOp_Word32 "readWord32OffAddr#" GenPrimOp
1003 Addr# -> Int# -> State# s -> (# State# s, WORD32 #)
1004 with has_side_effects = True
1006 primop ReadOffAddrOp_Word64 "readWord64OffAddr#" GenPrimOp
1007 Addr# -> Int# -> State# s -> (# State# s, WORD64 #)
1008 with has_side_effects = True
1011 primop WriteOffAddrOp_Char "writeCharOffAddr#" GenPrimOp
1012 Addr# -> Int# -> Char# -> State# s -> State# s
1013 with has_side_effects = True
1015 primop WriteOffAddrOp_WideChar "writeWideCharOffAddr#" GenPrimOp
1016 Addr# -> Int# -> Char# -> State# s -> State# s
1017 with has_side_effects = True
1019 primop WriteOffAddrOp_Int "writeIntOffAddr#" GenPrimOp
1020 Addr# -> Int# -> Int# -> State# s -> State# s
1021 with has_side_effects = True
1023 primop WriteOffAddrOp_Word "writeWordOffAddr#" GenPrimOp
1024 Addr# -> Int# -> Word# -> State# s -> State# s
1025 with has_side_effects = True
1027 primop WriteOffAddrOp_Addr "writeAddrOffAddr#" GenPrimOp
1028 Addr# -> Int# -> Addr# -> State# s -> State# s
1029 with has_side_effects = True
1031 primop WriteOffAddrOp_Float "writeFloatOffAddr#" GenPrimOp
1032 Addr# -> Int# -> Float# -> State# s -> State# s
1033 with has_side_effects = True
1035 primop WriteOffAddrOp_Double "writeDoubleOffAddr#" GenPrimOp
1036 Addr# -> Int# -> Double# -> State# s -> State# s
1037 with has_side_effects = True
1039 primop WriteOffAddrOp_StablePtr "writeStablePtrOffAddr#" GenPrimOp
1040 Addr# -> Int# -> StablePtr# a -> State# s -> State# s
1041 with has_side_effects = True
1043 primop WriteOffAddrOp_Int8 "writeInt8OffAddr#" GenPrimOp
1044 Addr# -> Int# -> Int# -> State# s -> State# s
1045 with has_side_effects = True
1047 primop WriteOffAddrOp_Int16 "writeInt16OffAddr#" GenPrimOp
1048 Addr# -> Int# -> Int# -> State# s -> State# s
1049 with has_side_effects = True
1051 primop WriteOffAddrOp_Int32 "writeInt32OffAddr#" GenPrimOp
1052 Addr# -> Int# -> INT32 -> State# s -> State# s
1053 with has_side_effects = True
1055 primop WriteOffAddrOp_Int64 "writeInt64OffAddr#" GenPrimOp
1056 Addr# -> Int# -> INT64 -> State# s -> State# s
1057 with has_side_effects = True
1059 primop WriteOffAddrOp_Word8 "writeWord8OffAddr#" GenPrimOp
1060 Addr# -> Int# -> Word# -> State# s -> State# s
1061 with has_side_effects = True
1063 primop WriteOffAddrOp_Word16 "writeWord16OffAddr#" GenPrimOp
1064 Addr# -> Int# -> Word# -> State# s -> State# s
1065 with has_side_effects = True
1067 primop WriteOffAddrOp_Word32 "writeWord32OffAddr#" GenPrimOp
1068 Addr# -> Int# -> WORD32 -> State# s -> State# s
1069 with has_side_effects = True
1071 primop WriteOffAddrOp_Word64 "writeWord64OffAddr#" GenPrimOp
1072 Addr# -> Int# -> WORD64 -> State# s -> State# s
1073 with has_side_effects = True
1075 ------------------------------------------------------------------------
1076 section "Mutable variables"
1077 {Operations on MutVar\#s.}
1078 ------------------------------------------------------------------------
1080 primtype MutVar# s a
1081 {A {\tt MutVar\#} behaves like a single-element mutable array.}
1083 primop NewMutVarOp "newMutVar#" GenPrimOp
1084 a -> State# s -> (# State# s, MutVar# s a #)
1085 {Create {\tt MutVar\#} with specified initial value in specified state thread.}
1088 has_side_effects = True
1090 primop ReadMutVarOp "readMutVar#" GenPrimOp
1091 MutVar# s a -> State# s -> (# State# s, a #)
1092 {Read contents of {\tt MutVar\#}. Result is not yet evaluated.}
1094 has_side_effects = True
1096 primop WriteMutVarOp "writeMutVar#" GenPrimOp
1097 MutVar# s a -> a -> State# s -> State# s
1098 {Write contents of {\tt MutVar\#}.}
1100 has_side_effects = True
1102 primop SameMutVarOp "sameMutVar#" GenPrimOp
1103 MutVar# s a -> MutVar# s a -> Bool
1105 -- not really the right type, but we don't know about pairs here. The
1108 -- MutVar# s a -> (a -> (a,b)) -> State# s -> (# State# s, b #)
1110 primop AtomicModifyMutVarOp "atomicModifyMutVar#" GenPrimOp
1111 MutVar# s a -> (a -> b) -> State# s -> (# State# s, c #)
1114 has_side_effects = True
1116 ------------------------------------------------------------------------
1117 section "Exceptions"
1118 ------------------------------------------------------------------------
1120 primop CatchOp "catch#" GenPrimOp
1121 (State# RealWorld -> (# State# RealWorld, a #) )
1122 -> (b -> State# RealWorld -> (# State# RealWorld, a #) )
1124 -> (# State# RealWorld, a #)
1126 -- Catch is actually strict in its first argument
1127 -- but we don't want to tell the strictness
1128 -- analyser about that!
1129 -- might use caught action multiply
1131 has_side_effects = True
1133 primop RaiseOp "raise#" GenPrimOp
1136 strictness = { \ _arity -> mkStrictSig (mkTopDmdType [lazyDmd] BotRes) }
1137 -- NB: result is bottom
1140 -- raiseIO# needs to be a primop, because exceptions in the IO monad
1141 -- must be *precise* - we don't want the strictness analyser turning
1142 -- one kind of bottom into another, as it is allowed to do in pure code.
1144 primop RaiseIOOp "raiseIO#" GenPrimOp
1145 a -> State# RealWorld -> (# State# RealWorld, b #)
1148 has_side_effects = True
1150 primop BlockAsyncExceptionsOp "blockAsyncExceptions#" GenPrimOp
1151 (State# RealWorld -> (# State# RealWorld, a #))
1152 -> (State# RealWorld -> (# State# RealWorld, a #))
1155 has_side_effects = True
1157 primop UnblockAsyncExceptionsOp "unblockAsyncExceptions#" GenPrimOp
1158 (State# RealWorld -> (# State# RealWorld, a #))
1159 -> (State# RealWorld -> (# State# RealWorld, a #))
1162 has_side_effects = True
1164 primop AsyncExceptionsBlockedOp "asyncExceptionsBlocked#" GenPrimOp
1165 State# RealWorld -> (# State# RealWorld, Int# #)
1168 has_side_effects = True
1170 ------------------------------------------------------------------------
1171 section "STM-accessible Mutable Variables"
1172 ------------------------------------------------------------------------
1176 primop AtomicallyOp "atomically#" GenPrimOp
1177 (State# RealWorld -> (# State# RealWorld, a #) )
1178 -> State# RealWorld -> (# State# RealWorld, a #)
1181 has_side_effects = True
1183 primop RetryOp "retry#" GenPrimOp
1184 State# RealWorld -> (# State# RealWorld, a #)
1187 has_side_effects = True
1189 primop CatchRetryOp "catchRetry#" GenPrimOp
1190 (State# RealWorld -> (# State# RealWorld, a #) )
1191 -> (State# RealWorld -> (# State# RealWorld, a #) )
1192 -> (State# RealWorld -> (# State# RealWorld, a #) )
1195 has_side_effects = True
1197 primop CatchSTMOp "catchSTM#" GenPrimOp
1198 (State# RealWorld -> (# State# RealWorld, a #) )
1199 -> (b -> State# RealWorld -> (# State# RealWorld, a #) )
1200 -> (State# RealWorld -> (# State# RealWorld, a #) )
1203 has_side_effects = True
1205 primop Check "check#" GenPrimOp
1206 (State# RealWorld -> (# State# RealWorld, a #) )
1207 -> (State# RealWorld -> (# State# RealWorld, () #) )
1210 has_side_effects = True
1212 primop NewTVarOp "newTVar#" GenPrimOp
1214 -> State# s -> (# State# s, TVar# s a #)
1215 {Create a new {\tt TVar\#} holding a specified initial value.}
1218 has_side_effects = True
1220 primop ReadTVarOp "readTVar#" GenPrimOp
1222 -> State# s -> (# State# s, a #)
1223 {Read contents of {\tt TVar\#}. Result is not yet evaluated.}
1226 has_side_effects = True
1228 primop ReadTVarIOOp "readTVarIO#" GenPrimOp
1230 -> State# s -> (# State# s, a #)
1231 {Read contents of {\tt TVar\#} outside an STM transaction}
1234 has_side_effects = True
1236 primop WriteTVarOp "writeTVar#" GenPrimOp
1239 -> State# s -> State# s
1240 {Write contents of {\tt TVar\#}.}
1243 has_side_effects = True
1245 primop SameTVarOp "sameTVar#" GenPrimOp
1246 TVar# s a -> TVar# s a -> Bool
1249 ------------------------------------------------------------------------
1250 section "Synchronized Mutable Variables"
1251 {Operations on {\tt MVar\#}s. }
1252 ------------------------------------------------------------------------
1255 { A shared mutable variable ({\it not} the same as a {\tt MutVar\#}!).
1256 (Note: in a non-concurrent implementation, {\tt (MVar\# a)} can be
1257 represented by {\tt (MutVar\# (Maybe a))}.) }
1259 primop NewMVarOp "newMVar#" GenPrimOp
1260 State# s -> (# State# s, MVar# s a #)
1261 {Create new {\tt MVar\#}; initially empty.}
1264 has_side_effects = True
1266 primop TakeMVarOp "takeMVar#" GenPrimOp
1267 MVar# s a -> State# s -> (# State# s, a #)
1268 {If {\tt MVar\#} is empty, block until it becomes full.
1269 Then remove and return its contents, and set it empty.}
1272 has_side_effects = True
1274 primop TryTakeMVarOp "tryTakeMVar#" GenPrimOp
1275 MVar# s a -> State# s -> (# State# s, Int#, a #)
1276 {If {\tt MVar\#} is empty, immediately return with integer 0 and value undefined.
1277 Otherwise, return with integer 1 and contents of {\tt MVar\#}, and set {\tt MVar\#} empty.}
1280 has_side_effects = True
1282 primop PutMVarOp "putMVar#" GenPrimOp
1283 MVar# s a -> a -> State# s -> State# s
1284 {If {\tt MVar\#} is full, block until it becomes empty.
1285 Then store value arg as its new contents.}
1288 has_side_effects = True
1290 primop TryPutMVarOp "tryPutMVar#" GenPrimOp
1291 MVar# s a -> a -> State# s -> (# State# s, Int# #)
1292 {If {\tt MVar\#} is full, immediately return with integer 0.
1293 Otherwise, store value arg as {\tt MVar\#}'s new contents, and return with integer 1.}
1296 has_side_effects = True
1298 primop SameMVarOp "sameMVar#" GenPrimOp
1299 MVar# s a -> MVar# s a -> Bool
1301 primop IsEmptyMVarOp "isEmptyMVar#" GenPrimOp
1302 MVar# s a -> State# s -> (# State# s, Int# #)
1303 {Return 1 if {\tt MVar\#} is empty; 0 otherwise.}
1306 has_side_effects = True
1308 ------------------------------------------------------------------------
1309 section "Delay/wait operations"
1310 ------------------------------------------------------------------------
1312 primop DelayOp "delay#" GenPrimOp
1313 Int# -> State# s -> State# s
1314 {Sleep specified number of microseconds.}
1316 needs_wrapper = True
1317 has_side_effects = True
1320 primop WaitReadOp "waitRead#" GenPrimOp
1321 Int# -> State# s -> State# s
1322 {Block until input is available on specified file descriptor.}
1324 needs_wrapper = True
1325 has_side_effects = True
1328 primop WaitWriteOp "waitWrite#" GenPrimOp
1329 Int# -> State# s -> State# s
1330 {Block until output is possible on specified file descriptor.}
1332 needs_wrapper = True
1333 has_side_effects = True
1336 #ifdef mingw32_TARGET_OS
1337 primop AsyncReadOp "asyncRead#" GenPrimOp
1338 Int# -> Int# -> Int# -> Addr# -> State# RealWorld-> (# State# RealWorld, Int#, Int# #)
1339 {Asynchronously read bytes from specified file descriptor.}
1341 needs_wrapper = True
1342 has_side_effects = True
1345 primop AsyncWriteOp "asyncWrite#" GenPrimOp
1346 Int# -> Int# -> Int# -> Addr# -> State# RealWorld-> (# State# RealWorld, Int#, Int# #)
1347 {Asynchronously write bytes from specified file descriptor.}
1349 needs_wrapper = True
1350 has_side_effects = True
1353 primop AsyncDoProcOp "asyncDoProc#" GenPrimOp
1354 Addr# -> Addr# -> State# RealWorld-> (# State# RealWorld, Int#, Int# #)
1355 {Asynchronously perform procedure (first arg), passing it 2nd arg.}
1357 needs_wrapper = True
1358 has_side_effects = True
1363 ------------------------------------------------------------------------
1364 section "Concurrency primitives"
1365 ------------------------------------------------------------------------
1368 { {\tt State\#} is the primitive, unlifted type of states. It has
1369 one type parameter, thus {\tt State\# RealWorld}, or {\tt State\# s},
1370 where s is a type variable. The only purpose of the type parameter
1371 is to keep different state threads separate. It is represented by
1375 { {\tt RealWorld} is deeply magical. It is {\it primitive}, but it is not
1376 {\it unlifted} (hence {\tt ptrArg}). We never manipulate values of type
1377 {\tt RealWorld}; it's only used in the type system, to parameterise {\tt State\#}. }
1380 {(In a non-concurrent implementation, this can be a singleton
1381 type, whose (unique) value is returned by {\tt myThreadId\#}. The
1382 other operations can be omitted.)}
1384 primop ForkOp "fork#" GenPrimOp
1385 a -> State# RealWorld -> (# State# RealWorld, ThreadId# #)
1387 has_side_effects = True
1390 primop ForkOnOp "forkOn#" GenPrimOp
1391 Int# -> a -> State# RealWorld -> (# State# RealWorld, ThreadId# #)
1393 has_side_effects = True
1396 primop KillThreadOp "killThread#" GenPrimOp
1397 ThreadId# -> a -> State# RealWorld -> State# RealWorld
1399 has_side_effects = True
1402 primop YieldOp "yield#" GenPrimOp
1403 State# RealWorld -> State# RealWorld
1405 has_side_effects = True
1408 primop MyThreadIdOp "myThreadId#" GenPrimOp
1409 State# RealWorld -> (# State# RealWorld, ThreadId# #)
1412 has_side_effects = True
1414 primop LabelThreadOp "labelThread#" GenPrimOp
1415 ThreadId# -> Addr# -> State# RealWorld -> State# RealWorld
1417 has_side_effects = True
1420 primop IsCurrentThreadBoundOp "isCurrentThreadBound#" GenPrimOp
1421 State# RealWorld -> (# State# RealWorld, Int# #)
1424 has_side_effects = True
1426 primop NoDuplicateOp "noDuplicate#" GenPrimOp
1427 State# RealWorld -> State# RealWorld
1430 has_side_effects = True
1432 primop ThreadStatusOp "threadStatus#" GenPrimOp
1433 ThreadId# -> State# RealWorld -> (# State# RealWorld, Int# #)
1436 has_side_effects = True
1438 ------------------------------------------------------------------------
1439 section "Weak pointers"
1440 ------------------------------------------------------------------------
1444 -- note that tyvar "o" denotes openAlphaTyVar
1446 primop MkWeakOp "mkWeak#" GenPrimOp
1447 o -> b -> c -> State# RealWorld -> (# State# RealWorld, Weak# b #)
1449 has_side_effects = True
1452 primop MkWeakForeignEnvOp "mkWeakForeignEnv#" GenPrimOp
1453 o -> b -> Addr# -> Addr# -> Int# -> Addr# -> State# RealWorld -> (# State# RealWorld, Weak# b #)
1455 has_side_effects = True
1458 primop DeRefWeakOp "deRefWeak#" GenPrimOp
1459 Weak# a -> State# RealWorld -> (# State# RealWorld, Int#, a #)
1461 has_side_effects = True
1464 primop FinalizeWeakOp "finalizeWeak#" GenPrimOp
1465 Weak# a -> State# RealWorld -> (# State# RealWorld, Int#,
1466 (State# RealWorld -> (# State# RealWorld, () #)) #)
1468 has_side_effects = True
1471 primop TouchOp "touch#" GenPrimOp
1472 o -> State# RealWorld -> State# RealWorld
1474 has_side_effects = True
1476 ------------------------------------------------------------------------
1477 section "Stable pointers and names"
1478 ------------------------------------------------------------------------
1480 primtype StablePtr# a
1482 primtype StableName# a
1484 primop MakeStablePtrOp "makeStablePtr#" GenPrimOp
1485 a -> State# RealWorld -> (# State# RealWorld, StablePtr# a #)
1487 has_side_effects = True
1490 primop DeRefStablePtrOp "deRefStablePtr#" GenPrimOp
1491 StablePtr# a -> State# RealWorld -> (# State# RealWorld, a #)
1493 needs_wrapper = True
1494 has_side_effects = True
1497 primop EqStablePtrOp "eqStablePtr#" GenPrimOp
1498 StablePtr# a -> StablePtr# a -> Int#
1500 has_side_effects = True
1502 primop MakeStableNameOp "makeStableName#" GenPrimOp
1503 a -> State# RealWorld -> (# State# RealWorld, StableName# a #)
1505 needs_wrapper = True
1506 has_side_effects = True
1509 primop EqStableNameOp "eqStableName#" GenPrimOp
1510 StableName# a -> StableName# a -> Int#
1512 primop StableNameToIntOp "stableNameToInt#" GenPrimOp
1513 StableName# a -> Int#
1515 ------------------------------------------------------------------------
1516 section "Unsafe pointer equality"
1517 -- (#1 Bad Guy: Alistair Reid :)
1518 ------------------------------------------------------------------------
1520 primop ReallyUnsafePtrEqualityOp "reallyUnsafePtrEquality#" GenPrimOp
1523 ------------------------------------------------------------------------
1524 section "Parallelism"
1525 ------------------------------------------------------------------------
1527 primop ParOp "par#" GenPrimOp
1530 -- Note that Par is lazy to avoid that the sparked thing
1531 -- gets evaluted strictly, which it should *not* be
1532 has_side_effects = True
1534 primop GetSparkOp "getSpark#" GenPrimOp
1535 State# s -> (# State# s, Int#, a #)
1537 has_side_effects = True
1540 -- HWL: The first 4 Int# in all par... annotations denote:
1541 -- name, granularity info, size of result, degree of parallelism
1542 -- Same structure as _seq_ i.e. returns Int#
1543 -- KSW: v, the second arg in parAt# and parAtForNow#, is used only to determine
1544 -- `the processor containing the expression v'; it is not evaluated
1546 primop ParGlobalOp "parGlobal#" GenPrimOp
1547 a -> Int# -> Int# -> Int# -> Int# -> b -> Int#
1549 has_side_effects = True
1551 primop ParLocalOp "parLocal#" GenPrimOp
1552 a -> Int# -> Int# -> Int# -> Int# -> b -> Int#
1554 has_side_effects = True
1556 primop ParAtOp "parAt#" GenPrimOp
1557 b -> a -> Int# -> Int# -> Int# -> Int# -> c -> Int#
1559 has_side_effects = True
1561 primop ParAtAbsOp "parAtAbs#" GenPrimOp
1562 a -> Int# -> Int# -> Int# -> Int# -> Int# -> b -> Int#
1564 has_side_effects = True
1566 primop ParAtRelOp "parAtRel#" GenPrimOp
1567 a -> Int# -> Int# -> Int# -> Int# -> Int# -> b -> Int#
1569 has_side_effects = True
1571 primop ParAtForNowOp "parAtForNow#" GenPrimOp
1572 b -> a -> Int# -> Int# -> Int# -> Int# -> c -> Int#
1574 has_side_effects = True
1576 -- copyable# and noFollow# are yet to be implemented (for GpH)
1578 --primop CopyableOp "copyable#" GenPrimOp
1581 -- has_side_effects = True
1583 --primop NoFollowOp "noFollow#" GenPrimOp
1586 -- has_side_effects = True
1589 ------------------------------------------------------------------------
1590 section "Tag to enum stuff"
1591 {Convert back and forth between values of enumerated types
1592 and small integers.}
1593 ------------------------------------------------------------------------
1595 primop DataToTagOp "dataToTag#" GenPrimOp
1598 strictness = { \ _arity -> mkStrictSig (mkTopDmdType [seqDmd] TopRes) }
1599 -- dataToTag# must have an evaluated argument
1601 primop TagToEnumOp "tagToEnum#" GenPrimOp
1604 ------------------------------------------------------------------------
1605 section "Bytecode operations"
1606 {Support for the bytecode interpreter and linker.}
1607 ------------------------------------------------------------------------
1610 {Primitive bytecode type.}
1612 primop AddrToHValueOp "addrToHValue#" GenPrimOp
1614 {Convert an {\tt Addr\#} to a followable type.}
1616 primop MkApUpd0_Op "mkApUpd0#" GenPrimOp
1621 primop NewBCOOp "newBCO#" GenPrimOp
1622 ByteArray# -> ByteArray# -> Array# a -> Int# -> ByteArray# -> State# s -> (# State# s, BCO# #)
1624 has_side_effects = True
1627 primop UnpackClosureOp "unpackClosure#" GenPrimOp
1628 a -> (# Addr#, Array# b, ByteArray# #)
1632 primop GetApStackValOp "getApStackVal#" GenPrimOp
1633 a -> Int# -> (# Int#, b #)
1637 ------------------------------------------------------------------------
1639 {These aren't nearly as wired in as Etc...}
1640 ------------------------------------------------------------------------
1642 primop TraceCcsOp "traceCcs#" GenPrimOp
1645 has_side_effects = True
1648 ------------------------------------------------------------------------
1650 {Miscellaneous built-ins}
1651 ------------------------------------------------------------------------
1655 { Evaluates its first argument to head normal form, and then returns its second
1656 argument as the result. }
1660 { The call {\tt (inline f)} arranges that f is inlined, regardless of its size.
1661 More precisely, the call {\tt (inline f)} rewrites to the right-hand side of
1662 {\tt f}'s definition. This allows the programmer to control inlining from a
1663 particular call site rather than the definition site of the function (c.f.
1664 {\tt INLINE} pragmas in User's Guide, Section 7.10.3, "INLINE and NOINLINE
1667 This inlining occurs regardless of the argument to the call or the size of
1668 {\tt f}'s definition; it is unconditional. The main caveat is that {\tt f}'s
1669 definition must be visible to the compiler. That is, {\tt f} must be
1670 {\tt let}-bound in the current scope. If no inlining takes place, the
1671 {\tt inline} function expands to the identity function in Phase zero; so its
1672 use imposes no overhead.
1674 If the function is defined in another module, GHC only exposes its inlining
1675 in the interface file if the function is sufficiently small that it might be
1676 inlined by the automatic mechanism. There is currently no way to tell GHC to
1677 expose arbitrarily-large functions in the interface file. (This shortcoming
1678 is something that could be fixed, with some kind of pragma.) }
1682 { The {\tt lazy} function restrains strictness analysis a little. The call
1683 {\tt (lazy e)} means the same as {\tt e}, but {\tt lazy} has a magical
1684 property so far as strictness analysis is concerned: it is lazy in its first
1685 argument, even though its semantics is strict. After strictness analysis has
1686 run, calls to {\tt lazy} are inlined to be the identity function.
1688 This behaviour is occasionally useful when controlling evaluation order.
1689 Notably, {\tt lazy} is used in the library definition of {\tt Control.Parallel.par}:
1691 {\tt par :: a -> b -> b}
1693 {\tt par x y = case (par\# x) of \_ -> lazy y}
1695 If {\tt lazy} were not lazy, {\tt par} would look strict in {\tt y} which
1696 would defeat the whole purpose of {\tt par}.
1698 Like {\tt seq}, the argument of {\tt lazy} can have an unboxed type. }
1701 { The type constructor {\tt Any} is type to which you can unsafely coerce any
1702 lifted type, and back.
1704 * It is lifted, and hence represented by a pointer
1706 * It does not claim to be a {\it data} type, and that's important for
1707 the code generator, because the code gen may {\it enter} a data value
1708 but never enters a function value.
1710 It's also used to instantiate un-constrained type variables after type
1711 checking. For example
1715 Annoyingly, we sometimes need {\tt Any}s of other kinds, such as {\tt (* -> *)} etc.
1716 This is a bit like tuples. We define a couple of useful ones here,
1717 and make others up on the fly. If any of these others end up being exported
1718 into interface files, we'll get a crash; at least until we add interface-file
1719 syntax to support them. }
1721 pseudoop "unsafeCoerce#"
1723 { The function {\tt unsafeCoerce\#} allows you to side-step the typechecker entirely. That
1724 is, it allows you to coerce any type into any other type. If you use this function,
1725 you had better get it right, otherwise segmentation faults await. It is generally
1726 used when you want to write a program that you know is well-typed, but where Haskell's
1727 type system is not expressive enough to prove that it is well typed.
1729 The following uses of {\tt unsafeCoerce\#} are supposed to work (i.e. not lead to
1730 spurious compile-time or run-time crashes):
1732 * Casting any lifted type to {\tt Any}
1734 * Casting {\tt Any} back to the real type
1736 * Casting an unboxed type to another unboxed type of the same size
1737 (but not coercions between floating-point and integral types)
1739 * Casting between two types that have the same runtime representation. One case is when
1740 the two types differ only in "phantom" type parameters, for example
1741 {\tt Ptr Int} to {\tt Ptr Float}, or {\tt [Int]} to {\tt [Float]} when the list is
1742 known to be empty. Also, a {\tt newtype} of a type {\tt T} has the same representation
1743 at runtime as {\tt T}.
1745 Other uses of {\tt unsafeCoerce\#} are undefined. In particular, you should not use
1746 {\tt unsafeCoerce\#} to cast a T to an algebraic data type D, unless T is also
1747 an algebraic data type. For example, do not cast {\tt Int->Int} to {\tt Bool}, even if
1748 you later cast that {\tt Bool} back to {\tt Int->Int} before applying it. The reasons
1749 have to do with GHC's internal representation details (for the congnoscenti, data values
1750 can be entered but function closures cannot). If you want a safe type to cast things
1751 to, use {\tt Any}, which is not an algebraic data type.
1755 -- NB. It is tempting to think that casting a value to a type that it doesn't have is safe
1756 -- as long as you don't "do anything" with the value in its cast form, such as seq on it. This
1757 -- isn't the case: the compiler can insert seqs itself, and if these happen at the wrong type,
1758 -- Bad Things Might Happen. See bug #1616: in this case we cast a function of type (a,b) -> (a,b)
1759 -- to () -> () and back again. The strictness analyser saw that the function was strict, but
1760 -- the wrapper had type () -> (), and hence the wrapper de-constructed the (), the worker re-constructed
1761 -- a new (), with the result that the code ended up with "case () of (a,b) -> ...".
1763 primop TraceEventOp "traceEvent#" GenPrimOp
1764 Addr# -> State# s -> State# s
1765 { Emits an event via the RTS tracing framework. The contents
1766 of the event is the zero-terminated byte string passed as the first
1767 argument. The event will be emitted either to the .eventlog file,
1768 or to stderr, depending on the runtime RTS flags. }
1770 has_side_effects = True
1773 ------------------------------------------------------------------------
1775 ------------------------------------------------------------------------