1 -----------------------------------------------------------------------
2 -- $Id: primops.txt.pp,v 1.37 2005/11/25 09:46:19 simonmar Exp $
4 -- Primitive Operations and Types
6 -----------------------------------------------------------------------
8 -- This file is processed by the utility program genprimopcode to produce
9 -- a number of include files within the compiler and optionally to produce
10 -- human-readable documentation.
12 -- It should first be preprocessed.
14 -- To add a new primop, you currently need to update the following files:
16 -- - this file (ghc/compiler/prelude/primops.txt.pp), which includes
17 -- the type of the primop, and various other properties (its
18 -- strictness attributes, whether it is defined as a macro
19 -- or as out-of-line code, etc.)
21 -- - if the primop is inline (i.e. a macro), then:
22 -- ghc/compiler/AbsCUtils.lhs (dscCOpStmt)
23 -- defines the translation of the primop into simpler
24 -- abstract C operations.
26 -- - or, for an out-of-line primop:
27 -- ghc/includes/StgMiscClosures.h (just add the declaration)
28 -- ghc/rts/PrimOps.cmm (define it here)
29 -- ghc/rts/Linker.c (declare the symbol for GHCi)
34 -- This file is divided into named sections, each containing or more
35 -- primop entries. Section headers have the format:
37 -- section "section-name" {description}
39 -- This information is used solely when producing documentation; it is
40 -- otherwise ignored. The description is optional.
42 -- The format of each primop entry is as follows:
44 -- primop internal-name "name-in-program-text" type category {description} attributes
46 -- The default attribute values which apply if you don't specify
47 -- other ones. Attribute values can be True, False, or arbitrary
48 -- text between curly brackets. This is a kludge to enable
49 -- processors of this file to easily get hold of simple info
50 -- (eg, out_of_line), whilst avoiding parsing complex expressions
51 -- needed for strictness info.
54 has_side_effects = False
59 strictness = { \ arity -> mkStrictSig (mkTopDmdType (replicate arity lazyDmd) TopRes) }
61 -- Currently, documentation is produced using latex, so contents of
62 -- description fields should be legal latex. Descriptions can contain
63 -- matched pairs of embedded curly brackets.
67 -- We need platform defines (tests for mingw32 below). However, we only
68 -- test the TARGET platform, which doesn't vary between stages, so the
69 -- stage1 platform defines are fine:
70 #include "../stage1/ghc_boot_platform.h"
72 section "The word size story."
73 {Haskell98 specifies that signed integers (type {\tt Int})
74 must contain at least 30 bits. GHC always implements {\tt
75 Int} using the primitive type {\tt Int\#}, whose size equals
76 the {\tt MachDeps.h} constant {\tt WORD\_SIZE\_IN\_BITS}.
77 This is normally set based on the {\tt config.h} parameter
78 {\tt SIZEOF\_HSWORD}, i.e., 32 bits on 32-bit machines, 64
79 bits on 64-bit machines. However, it can also be explicitly
80 set to a smaller number, e.g., 31 bits, to allow the
81 possibility of using tag bits. Currently GHC itself has only
82 32-bit and 64-bit variants, but 30 or 31-bit code can be
83 exported as an external core file for use in other back ends.
85 GHC also implements a primitive unsigned integer type {\tt
86 Word\#} which always has the same number of bits as {\tt
89 In addition, GHC supports families of explicit-sized integers
90 and words at 8, 16, 32, and 64 bits, with the usual
91 arithmetic operations, comparisons, and a range of
92 conversions. The 8-bit and 16-bit sizes are always
93 represented as {\tt Int\#} and {\tt Word\#}, and the
94 operations implemented in terms of the the primops on these
95 types, with suitable range restrictions on the results (using
96 the {\tt narrow$n$Int\#} and {\tt narrow$n$Word\#} families
97 of primops. The 32-bit sizes are represented using {\tt
98 Int\#} and {\tt Word\#} when {\tt WORD\_SIZE\_IN\_BITS}
99 $\geq$ 32; otherwise, these are represented using distinct
100 primitive types {\tt Int32\#} and {\tt Word32\#}. These (when
101 needed) have a complete set of corresponding operations;
102 however, nearly all of these are implemented as external C
103 functions rather than as primops. Exactly the same story
104 applies to the 64-bit sizes. All of these details are hidden
105 under the {\tt PrelInt} and {\tt PrelWord} modules, which use
106 {\tt \#if}-defs to invoke the appropriate types and
109 Word size also matters for the families of primops for
110 indexing/reading/writing fixed-size quantities at offsets
111 from an array base, address, or foreign pointer. Here, a
112 slightly different approach is taken. The names of these
113 primops are fixed, but their {\it types} vary according to
114 the value of {\tt WORD\_SIZE\_IN\_BITS}. For example, if word
115 size is at least 32 bits then an operator like
116 \texttt{indexInt32Array\#} has type {\tt ByteArray\# -> Int\#
117 -> Int\#}; otherwise it has type {\tt ByteArray\# -> Int\# ->
118 Int32\#}. This approach confines the necessary {\tt
119 \#if}-defs to this file; no conditional compilation is needed
120 in the files that expose these primops.
122 Finally, there are strongly deprecated primops for coercing
123 between {\tt Addr\#}, the primitive type of machine
124 addresses, and {\tt Int\#}. These are pretty bogus anyway,
125 but will work on existing 32-bit and 64-bit GHC targets; they
126 are completely bogus when tag bits are used in {\tt Int\#},
127 so are not available in this case. }
129 -- Define synonyms for indexing ops.
131 #if WORD_SIZE_IN_BITS < 32
133 #define WORD32 Word32#
139 #if WORD_SIZE_IN_BITS < 64
141 #define WORD64 Word64#
147 ------------------------------------------------------------------------
149 {Operations on 31-bit characters.}
150 ------------------------------------------------------------------------
154 primop CharGtOp "gtChar#" Compare Char# -> Char# -> Bool
155 primop CharGeOp "geChar#" Compare Char# -> Char# -> Bool
157 primop CharEqOp "eqChar#" Compare
158 Char# -> Char# -> Bool
159 with commutable = True
161 primop CharNeOp "neChar#" Compare
162 Char# -> Char# -> Bool
163 with commutable = True
165 primop CharLtOp "ltChar#" Compare Char# -> Char# -> Bool
166 primop CharLeOp "leChar#" Compare Char# -> Char# -> Bool
168 primop OrdOp "ord#" GenPrimOp Char# -> Int#
170 ------------------------------------------------------------------------
172 {Operations on native-size integers (30+ bits).}
173 ------------------------------------------------------------------------
177 primop IntAddOp "+#" Dyadic
179 with commutable = True
181 primop IntSubOp "-#" Dyadic Int# -> Int# -> Int#
184 Dyadic Int# -> Int# -> Int#
185 {Low word of signed integer multiply.}
186 with commutable = True
188 primop IntMulMayOfloOp "mulIntMayOflo#"
189 Dyadic Int# -> Int# -> Int#
190 {Return non-zero if there is any possibility that the upper word of a
191 signed integer multiply might contain useful information. Return
192 zero only if you are completely sure that no overflow can occur.
193 On a 32-bit platform, the recommmended implementation is to do a
194 32 x 32 -> 64 signed multiply, and subtract result[63:32] from
195 (result[31] >>signed 31). If this is zero, meaning that the
196 upper word is merely a sign extension of the lower one, no
199 On a 64-bit platform it is not always possible to
200 acquire the top 64 bits of the result. Therefore, a recommended
201 implementation is to take the absolute value of both operands, and
202 return 0 iff bits[63:31] of them are zero, since that means that their
203 magnitudes fit within 31 bits, so the magnitude of the product must fit
206 If in doubt, return non-zero, but do make an effort to create the
207 correct answer for small args, since otherwise the performance of
208 \texttt{(*) :: Integer -> Integer -> Integer} will be poor.
210 with commutable = True
212 primop IntQuotOp "quotInt#" Dyadic
214 {Rounds towards zero.}
217 primop IntRemOp "remInt#" Dyadic
219 {Satisfies \texttt{(quotInt\# x y) *\# y +\# (remInt\# x y) == x}.}
222 primop IntNegOp "negateInt#" Monadic Int# -> Int#
223 primop IntAddCOp "addIntC#" GenPrimOp Int# -> Int# -> (# Int#, Int# #)
224 {Add with carry. First member of result is (wrapped) sum;
225 second member is 0 iff no overflow occured.}
226 primop IntSubCOp "subIntC#" GenPrimOp Int# -> Int# -> (# Int#, Int# #)
227 {Subtract with carry. First member of result is (wrapped) difference;
228 second member is 0 iff no overflow occured.}
230 primop IntGtOp ">#" Compare Int# -> Int# -> Bool
231 primop IntGeOp ">=#" Compare Int# -> Int# -> Bool
233 primop IntEqOp "==#" Compare
235 with commutable = True
237 primop IntNeOp "/=#" Compare
239 with commutable = True
241 primop IntLtOp "<#" Compare Int# -> Int# -> Bool
242 primop IntLeOp "<=#" Compare Int# -> Int# -> Bool
244 primop ChrOp "chr#" GenPrimOp Int# -> Char#
246 primop Int2WordOp "int2Word#" GenPrimOp Int# -> Word#
247 primop Int2FloatOp "int2Float#" GenPrimOp Int# -> Float#
248 primop Int2DoubleOp "int2Double#" GenPrimOp Int# -> Double#
250 primop ISllOp "uncheckedIShiftL#" GenPrimOp Int# -> Int# -> Int#
251 {Shift left. Result undefined if shift amount is not
252 in the range 0 to word size - 1 inclusive.}
253 primop ISraOp "uncheckedIShiftRA#" GenPrimOp Int# -> Int# -> Int#
254 {Shift right arithmetic. Result undefined if shift amount is not
255 in the range 0 to word size - 1 inclusive.}
256 primop ISrlOp "uncheckedIShiftRL#" GenPrimOp Int# -> Int# -> Int#
257 {Shift right logical. Result undefined if shift amount is not
258 in the range 0 to word size - 1 inclusive.}
260 ------------------------------------------------------------------------
262 {Operations on native-sized unsigned words (30+ bits).}
263 ------------------------------------------------------------------------
267 primop WordAddOp "plusWord#" Dyadic Word# -> Word# -> Word#
268 with commutable = True
270 primop WordSubOp "minusWord#" Dyadic Word# -> Word# -> Word#
272 primop WordMulOp "timesWord#" Dyadic Word# -> Word# -> Word#
273 with commutable = True
275 primop WordQuotOp "quotWord#" Dyadic Word# -> Word# -> Word#
278 primop WordRemOp "remWord#" Dyadic Word# -> Word# -> Word#
281 primop AndOp "and#" Dyadic Word# -> Word# -> Word#
282 with commutable = True
284 primop OrOp "or#" Dyadic Word# -> Word# -> Word#
285 with commutable = True
287 primop XorOp "xor#" Dyadic Word# -> Word# -> Word#
288 with commutable = True
290 primop NotOp "not#" Monadic Word# -> Word#
292 primop SllOp "uncheckedShiftL#" GenPrimOp Word# -> Int# -> Word#
293 {Shift left logical. Result undefined if shift amount is not
294 in the range 0 to word size - 1 inclusive.}
295 primop SrlOp "uncheckedShiftRL#" GenPrimOp Word# -> Int# -> Word#
296 {Shift right logical. Result undefined if shift amount is not
297 in the range 0 to word size - 1 inclusive.}
299 primop Word2IntOp "word2Int#" GenPrimOp Word# -> Int#
301 primop WordGtOp "gtWord#" Compare Word# -> Word# -> Bool
302 primop WordGeOp "geWord#" Compare Word# -> Word# -> Bool
303 primop WordEqOp "eqWord#" Compare Word# -> Word# -> Bool
304 primop WordNeOp "neWord#" Compare Word# -> Word# -> Bool
305 primop WordLtOp "ltWord#" Compare Word# -> Word# -> Bool
306 primop WordLeOp "leWord#" Compare Word# -> Word# -> Bool
308 ------------------------------------------------------------------------
310 {Explicit narrowing of native-sized ints or words.}
311 ------------------------------------------------------------------------
313 primop Narrow8IntOp "narrow8Int#" Monadic Int# -> Int#
314 primop Narrow16IntOp "narrow16Int#" Monadic Int# -> Int#
315 primop Narrow32IntOp "narrow32Int#" Monadic Int# -> Int#
316 primop Narrow8WordOp "narrow8Word#" Monadic Word# -> Word#
317 primop Narrow16WordOp "narrow16Word#" Monadic Word# -> Word#
318 primop Narrow32WordOp "narrow32Word#" Monadic Word# -> Word#
321 #if WORD_SIZE_IN_BITS < 32
322 ------------------------------------------------------------------------
324 {Operations on 32-bit integers ({\tt Int32\#}). This type is only used
325 if plain {\tt Int\#} has less than 32 bits. In any case, the operations
326 are not primops; they are implemented (if needed) as ccalls instead.}
327 ------------------------------------------------------------------------
331 ------------------------------------------------------------------------
333 {Operations on 32-bit unsigned words. This type is only used
334 if plain {\tt Word\#} has less than 32 bits. In any case, the operations
335 are not primops; they are implemented (if needed) as ccalls instead.}
336 ------------------------------------------------------------------------
343 #if WORD_SIZE_IN_BITS < 64
344 ------------------------------------------------------------------------
346 {Operations on 64-bit unsigned words. This type is only used
347 if plain {\tt Int\#} has less than 64 bits. In any case, the operations
348 are not primops; they are implemented (if needed) as ccalls instead.}
349 ------------------------------------------------------------------------
353 ------------------------------------------------------------------------
355 {Operations on 64-bit unsigned words. This type is only used
356 if plain {\tt Word\#} has less than 64 bits. In any case, the operations
357 are not primops; they are implemented (if needed) as ccalls instead.}
358 ------------------------------------------------------------------------
364 ------------------------------------------------------------------------
366 {Operations on double-precision (64 bit) floating-point numbers.}
367 ------------------------------------------------------------------------
371 primop DoubleGtOp ">##" Compare Double# -> Double# -> Bool
372 primop DoubleGeOp ">=##" Compare Double# -> Double# -> Bool
374 primop DoubleEqOp "==##" Compare
375 Double# -> Double# -> Bool
376 with commutable = True
378 primop DoubleNeOp "/=##" Compare
379 Double# -> Double# -> Bool
380 with commutable = True
382 primop DoubleLtOp "<##" Compare Double# -> Double# -> Bool
383 primop DoubleLeOp "<=##" Compare Double# -> Double# -> Bool
385 primop DoubleAddOp "+##" Dyadic
386 Double# -> Double# -> Double#
387 with commutable = True
389 primop DoubleSubOp "-##" Dyadic Double# -> Double# -> Double#
391 primop DoubleMulOp "*##" Dyadic
392 Double# -> Double# -> Double#
393 with commutable = True
395 primop DoubleDivOp "/##" Dyadic
396 Double# -> Double# -> Double#
399 primop DoubleNegOp "negateDouble#" Monadic Double# -> Double#
401 primop Double2IntOp "double2Int#" GenPrimOp Double# -> Int#
402 {Truncates a {\tt Double#} value to the nearest {\tt Int#}.
403 Results are undefined if the truncation if truncation yields
404 a value outside the range of {\tt Int#}.}
406 primop Double2FloatOp "double2Float#" GenPrimOp Double# -> Float#
408 primop DoubleExpOp "expDouble#" Monadic
410 with needs_wrapper = True
412 primop DoubleLogOp "logDouble#" Monadic
418 primop DoubleSqrtOp "sqrtDouble#" Monadic
420 with needs_wrapper = True
422 primop DoubleSinOp "sinDouble#" Monadic
424 with needs_wrapper = True
426 primop DoubleCosOp "cosDouble#" Monadic
428 with needs_wrapper = True
430 primop DoubleTanOp "tanDouble#" Monadic
432 with needs_wrapper = True
434 primop DoubleAsinOp "asinDouble#" Monadic
440 primop DoubleAcosOp "acosDouble#" Monadic
446 primop DoubleAtanOp "atanDouble#" Monadic
451 primop DoubleSinhOp "sinhDouble#" Monadic
453 with needs_wrapper = True
455 primop DoubleCoshOp "coshDouble#" Monadic
457 with needs_wrapper = True
459 primop DoubleTanhOp "tanhDouble#" Monadic
461 with needs_wrapper = True
463 primop DoublePowerOp "**##" Dyadic
464 Double# -> Double# -> Double#
466 with needs_wrapper = True
468 primop DoubleDecode_2IntOp "decodeDouble_2Int#" GenPrimOp
469 Double# -> (# Int#, Word#, Word#, Int# #)
471 First component of the result is -1 or 1, indicating the sign of the
472 mantissa. The next two are the high and low 32 bits of the mantissa
473 respectively, and the last is the exponent.}
474 with out_of_line = True
476 ------------------------------------------------------------------------
478 {Operations on single-precision (32-bit) floating-point numbers.}
479 ------------------------------------------------------------------------
483 primop FloatGtOp "gtFloat#" Compare Float# -> Float# -> Bool
484 primop FloatGeOp "geFloat#" Compare Float# -> Float# -> Bool
486 primop FloatEqOp "eqFloat#" Compare
487 Float# -> Float# -> Bool
488 with commutable = True
490 primop FloatNeOp "neFloat#" Compare
491 Float# -> Float# -> Bool
492 with commutable = True
494 primop FloatLtOp "ltFloat#" Compare Float# -> Float# -> Bool
495 primop FloatLeOp "leFloat#" Compare Float# -> Float# -> Bool
497 primop FloatAddOp "plusFloat#" Dyadic
498 Float# -> Float# -> Float#
499 with commutable = True
501 primop FloatSubOp "minusFloat#" Dyadic Float# -> Float# -> Float#
503 primop FloatMulOp "timesFloat#" Dyadic
504 Float# -> Float# -> Float#
505 with commutable = True
507 primop FloatDivOp "divideFloat#" Dyadic
508 Float# -> Float# -> Float#
511 primop FloatNegOp "negateFloat#" Monadic Float# -> Float#
513 primop Float2IntOp "float2Int#" GenPrimOp Float# -> Int#
514 {Truncates a {\tt Float#} value to the nearest {\tt Int#}.
515 Results are undefined if the truncation if truncation yields
516 a value outside the range of {\tt Int#}.}
518 primop FloatExpOp "expFloat#" Monadic
520 with needs_wrapper = True
522 primop FloatLogOp "logFloat#" Monadic
524 with needs_wrapper = True
527 primop FloatSqrtOp "sqrtFloat#" Monadic
529 with needs_wrapper = True
531 primop FloatSinOp "sinFloat#" Monadic
533 with needs_wrapper = True
535 primop FloatCosOp "cosFloat#" Monadic
537 with needs_wrapper = True
539 primop FloatTanOp "tanFloat#" Monadic
541 with needs_wrapper = True
543 primop FloatAsinOp "asinFloat#" Monadic
545 with needs_wrapper = True
548 primop FloatAcosOp "acosFloat#" Monadic
550 with needs_wrapper = True
553 primop FloatAtanOp "atanFloat#" Monadic
555 with needs_wrapper = True
557 primop FloatSinhOp "sinhFloat#" Monadic
559 with needs_wrapper = True
561 primop FloatCoshOp "coshFloat#" Monadic
563 with needs_wrapper = True
565 primop FloatTanhOp "tanhFloat#" Monadic
567 with needs_wrapper = True
569 primop FloatPowerOp "powerFloat#" Dyadic
570 Float# -> Float# -> Float#
571 with needs_wrapper = True
573 primop Float2DoubleOp "float2Double#" GenPrimOp Float# -> Double#
575 primop FloatDecode_IntOp "decodeFloat_Int#" GenPrimOp
576 Float# -> (# Int#, Int# #)
577 {Convert to integers.
578 First {\tt Int\#} in result is the mantissa; second is the exponent.}
579 with out_of_line = True
581 ------------------------------------------------------------------------
583 {Operations on {\tt Array\#}.}
584 ------------------------------------------------------------------------
588 primtype MutableArray# s a
590 primop NewArrayOp "newArray#" GenPrimOp
591 Int# -> a -> State# s -> (# State# s, MutableArray# s a #)
592 {Create a new mutable array of specified size (in bytes),
593 in the specified state thread,
594 with each element containing the specified initial value.}
597 has_side_effects = True
599 primop SameMutableArrayOp "sameMutableArray#" GenPrimOp
600 MutableArray# s a -> MutableArray# s a -> Bool
602 primop ReadArrayOp "readArray#" GenPrimOp
603 MutableArray# s a -> Int# -> State# s -> (# State# s, a #)
604 {Read from specified index of mutable array. Result is not yet evaluated.}
606 has_side_effects = True
608 primop WriteArrayOp "writeArray#" GenPrimOp
609 MutableArray# s a -> Int# -> a -> State# s -> State# s
610 {Write to specified index of mutable array.}
612 has_side_effects = True
614 primop IndexArrayOp "indexArray#" GenPrimOp
615 Array# a -> Int# -> (# a #)
616 {Read from specified index of immutable array. Result is packaged into
617 an unboxed singleton; the result itself is not yet evaluated.}
619 primop UnsafeFreezeArrayOp "unsafeFreezeArray#" GenPrimOp
620 MutableArray# s a -> State# s -> (# State# s, Array# a #)
621 {Make a mutable array immutable, without copying.}
623 has_side_effects = True
625 primop UnsafeThawArrayOp "unsafeThawArray#" GenPrimOp
626 Array# a -> State# s -> (# State# s, MutableArray# s a #)
627 {Make an immutable array mutable, without copying.}
630 has_side_effects = True
632 ------------------------------------------------------------------------
633 section "Byte Arrays"
634 {Operations on {\tt ByteArray\#}. A {\tt ByteArray\#} is a just a region of
635 raw memory in the garbage-collected heap, which is not
636 scanned for pointers. It carries its own size (in bytes).
638 three sets of operations for accessing byte array contents:
639 index for reading from immutable byte arrays, and read/write
640 for mutable byte arrays. Each set contains operations for a
641 range of useful primitive data types. Each operation takes
642 an offset measured in terms of the size fo the primitive type
643 being read or written.}
645 ------------------------------------------------------------------------
649 primtype MutableByteArray# s
651 primop NewByteArrayOp_Char "newByteArray#" GenPrimOp
652 Int# -> State# s -> (# State# s, MutableByteArray# s #)
653 {Create a new mutable byte array of specified size (in bytes), in
654 the specified state thread.}
655 with out_of_line = True
656 has_side_effects = True
658 primop NewPinnedByteArrayOp_Char "newPinnedByteArray#" GenPrimOp
659 Int# -> State# s -> (# State# s, MutableByteArray# s #)
660 {Create a mutable byte array that the GC guarantees not to move.}
661 with out_of_line = True
662 has_side_effects = True
664 primop NewAlignedPinnedByteArrayOp_Char "newAlignedPinnedByteArray#" GenPrimOp
665 Int# -> Int# -> State# s -> (# State# s, MutableByteArray# s #)
666 {Create a mutable byte array, aligned by the specified amount, that the GC guarantees not to move.}
667 with out_of_line = True
668 has_side_effects = True
670 primop ByteArrayContents_Char "byteArrayContents#" GenPrimOp
672 {Intended for use with pinned arrays; otherwise very unsafe!}
674 primop SameMutableByteArrayOp "sameMutableByteArray#" GenPrimOp
675 MutableByteArray# s -> MutableByteArray# s -> Bool
677 primop UnsafeFreezeByteArrayOp "unsafeFreezeByteArray#" GenPrimOp
678 MutableByteArray# s -> State# s -> (# State# s, ByteArray# #)
679 {Make a mutable byte array immutable, without copying.}
681 has_side_effects = True
683 primop SizeofByteArrayOp "sizeofByteArray#" GenPrimOp
685 {Return the size of the array in bytes.}
687 primop SizeofMutableByteArrayOp "sizeofMutableByteArray#" GenPrimOp
688 MutableByteArray# s -> Int#
689 {Return the size of the array in bytes.}
691 primop IndexByteArrayOp_Char "indexCharArray#" GenPrimOp
692 ByteArray# -> Int# -> Char#
693 {Read 8-bit character; offset in bytes.}
695 primop IndexByteArrayOp_WideChar "indexWideCharArray#" GenPrimOp
696 ByteArray# -> Int# -> Char#
697 {Read 31-bit character; offset in 4-byte words.}
699 primop IndexByteArrayOp_Int "indexIntArray#" GenPrimOp
700 ByteArray# -> Int# -> Int#
702 primop IndexByteArrayOp_Word "indexWordArray#" GenPrimOp
703 ByteArray# -> Int# -> Word#
705 primop IndexByteArrayOp_Addr "indexAddrArray#" GenPrimOp
706 ByteArray# -> Int# -> Addr#
708 primop IndexByteArrayOp_Float "indexFloatArray#" GenPrimOp
709 ByteArray# -> Int# -> Float#
711 primop IndexByteArrayOp_Double "indexDoubleArray#" GenPrimOp
712 ByteArray# -> Int# -> Double#
714 primop IndexByteArrayOp_StablePtr "indexStablePtrArray#" GenPrimOp
715 ByteArray# -> Int# -> StablePtr# a
717 primop IndexByteArrayOp_Int8 "indexInt8Array#" GenPrimOp
718 ByteArray# -> Int# -> Int#
720 primop IndexByteArrayOp_Int16 "indexInt16Array#" GenPrimOp
721 ByteArray# -> Int# -> Int#
723 primop IndexByteArrayOp_Int32 "indexInt32Array#" GenPrimOp
724 ByteArray# -> Int# -> INT32
726 primop IndexByteArrayOp_Int64 "indexInt64Array#" GenPrimOp
727 ByteArray# -> Int# -> INT64
729 primop IndexByteArrayOp_Word8 "indexWord8Array#" GenPrimOp
730 ByteArray# -> Int# -> Word#
732 primop IndexByteArrayOp_Word16 "indexWord16Array#" GenPrimOp
733 ByteArray# -> Int# -> Word#
735 primop IndexByteArrayOp_Word32 "indexWord32Array#" GenPrimOp
736 ByteArray# -> Int# -> WORD32
738 primop IndexByteArrayOp_Word64 "indexWord64Array#" GenPrimOp
739 ByteArray# -> Int# -> WORD64
741 primop ReadByteArrayOp_Char "readCharArray#" GenPrimOp
742 MutableByteArray# s -> Int# -> State# s -> (# State# s, Char# #)
743 {Read 8-bit character; offset in bytes.}
744 with has_side_effects = True
746 primop ReadByteArrayOp_WideChar "readWideCharArray#" GenPrimOp
747 MutableByteArray# s -> Int# -> State# s -> (# State# s, Char# #)
748 {Read 31-bit character; offset in 4-byte words.}
749 with has_side_effects = True
751 primop ReadByteArrayOp_Int "readIntArray#" GenPrimOp
752 MutableByteArray# s -> Int# -> State# s -> (# State# s, Int# #)
753 with has_side_effects = True
755 primop ReadByteArrayOp_Word "readWordArray#" GenPrimOp
756 MutableByteArray# s -> Int# -> State# s -> (# State# s, Word# #)
757 with has_side_effects = True
759 primop ReadByteArrayOp_Addr "readAddrArray#" GenPrimOp
760 MutableByteArray# s -> Int# -> State# s -> (# State# s, Addr# #)
761 with has_side_effects = True
763 primop ReadByteArrayOp_Float "readFloatArray#" GenPrimOp
764 MutableByteArray# s -> Int# -> State# s -> (# State# s, Float# #)
765 with has_side_effects = True
767 primop ReadByteArrayOp_Double "readDoubleArray#" GenPrimOp
768 MutableByteArray# s -> Int# -> State# s -> (# State# s, Double# #)
769 with has_side_effects = True
771 primop ReadByteArrayOp_StablePtr "readStablePtrArray#" GenPrimOp
772 MutableByteArray# s -> Int# -> State# s -> (# State# s, StablePtr# a #)
773 with has_side_effects = True
775 primop ReadByteArrayOp_Int8 "readInt8Array#" GenPrimOp
776 MutableByteArray# s -> Int# -> State# s -> (# State# s, Int# #)
777 with has_side_effects = True
779 primop ReadByteArrayOp_Int16 "readInt16Array#" GenPrimOp
780 MutableByteArray# s -> Int# -> State# s -> (# State# s, Int# #)
781 with has_side_effects = True
783 primop ReadByteArrayOp_Int32 "readInt32Array#" GenPrimOp
784 MutableByteArray# s -> Int# -> State# s -> (# State# s, INT32 #)
785 with has_side_effects = True
787 primop ReadByteArrayOp_Int64 "readInt64Array#" GenPrimOp
788 MutableByteArray# s -> Int# -> State# s -> (# State# s, INT64 #)
789 with has_side_effects = True
791 primop ReadByteArrayOp_Word8 "readWord8Array#" GenPrimOp
792 MutableByteArray# s -> Int# -> State# s -> (# State# s, Word# #)
793 with has_side_effects = True
795 primop ReadByteArrayOp_Word16 "readWord16Array#" GenPrimOp
796 MutableByteArray# s -> Int# -> State# s -> (# State# s, Word# #)
797 with has_side_effects = True
799 primop ReadByteArrayOp_Word32 "readWord32Array#" GenPrimOp
800 MutableByteArray# s -> Int# -> State# s -> (# State# s, WORD32 #)
801 with has_side_effects = True
803 primop ReadByteArrayOp_Word64 "readWord64Array#" GenPrimOp
804 MutableByteArray# s -> Int# -> State# s -> (# State# s, WORD64 #)
805 with has_side_effects = True
807 primop WriteByteArrayOp_Char "writeCharArray#" GenPrimOp
808 MutableByteArray# s -> Int# -> Char# -> State# s -> State# s
809 {Write 8-bit character; offset in bytes.}
810 with has_side_effects = True
812 primop WriteByteArrayOp_WideChar "writeWideCharArray#" GenPrimOp
813 MutableByteArray# s -> Int# -> Char# -> State# s -> State# s
814 {Write 31-bit character; offset in 4-byte words.}
815 with has_side_effects = True
817 primop WriteByteArrayOp_Int "writeIntArray#" GenPrimOp
818 MutableByteArray# s -> Int# -> Int# -> State# s -> State# s
819 with has_side_effects = True
821 primop WriteByteArrayOp_Word "writeWordArray#" GenPrimOp
822 MutableByteArray# s -> Int# -> Word# -> State# s -> State# s
823 with has_side_effects = True
825 primop WriteByteArrayOp_Addr "writeAddrArray#" GenPrimOp
826 MutableByteArray# s -> Int# -> Addr# -> State# s -> State# s
827 with has_side_effects = True
829 primop WriteByteArrayOp_Float "writeFloatArray#" GenPrimOp
830 MutableByteArray# s -> Int# -> Float# -> State# s -> State# s
831 with has_side_effects = True
833 primop WriteByteArrayOp_Double "writeDoubleArray#" GenPrimOp
834 MutableByteArray# s -> Int# -> Double# -> State# s -> State# s
835 with has_side_effects = True
837 primop WriteByteArrayOp_StablePtr "writeStablePtrArray#" GenPrimOp
838 MutableByteArray# s -> Int# -> StablePtr# a -> State# s -> State# s
839 with has_side_effects = True
841 primop WriteByteArrayOp_Int8 "writeInt8Array#" GenPrimOp
842 MutableByteArray# s -> Int# -> Int# -> State# s -> State# s
843 with has_side_effects = True
845 primop WriteByteArrayOp_Int16 "writeInt16Array#" GenPrimOp
846 MutableByteArray# s -> Int# -> Int# -> State# s -> State# s
847 with has_side_effects = True
849 primop WriteByteArrayOp_Int32 "writeInt32Array#" GenPrimOp
850 MutableByteArray# s -> Int# -> INT32 -> State# s -> State# s
851 with has_side_effects = True
853 primop WriteByteArrayOp_Int64 "writeInt64Array#" GenPrimOp
854 MutableByteArray# s -> Int# -> INT64 -> State# s -> State# s
855 with has_side_effects = True
857 primop WriteByteArrayOp_Word8 "writeWord8Array#" GenPrimOp
858 MutableByteArray# s -> Int# -> Word# -> State# s -> State# s
859 with has_side_effects = True
861 primop WriteByteArrayOp_Word16 "writeWord16Array#" GenPrimOp
862 MutableByteArray# s -> Int# -> Word# -> State# s -> State# s
863 with has_side_effects = True
865 primop WriteByteArrayOp_Word32 "writeWord32Array#" GenPrimOp
866 MutableByteArray# s -> Int# -> WORD32 -> State# s -> State# s
867 with has_side_effects = True
869 primop WriteByteArrayOp_Word64 "writeWord64Array#" GenPrimOp
870 MutableByteArray# s -> Int# -> WORD64 -> State# s -> State# s
871 with has_side_effects = True
873 ------------------------------------------------------------------------
875 ------------------------------------------------------------------------
878 { An arbitrary machine address assumed to point outside
879 the garbage-collected heap. }
881 pseudoop "nullAddr#" Addr#
882 { The null address. }
884 primop AddrAddOp "plusAddr#" GenPrimOp Addr# -> Int# -> Addr#
885 primop AddrSubOp "minusAddr#" GenPrimOp Addr# -> Addr# -> Int#
886 {Result is meaningless if two {\tt Addr\#}s are so far apart that their
887 difference doesn't fit in an {\tt Int\#}.}
888 primop AddrRemOp "remAddr#" GenPrimOp Addr# -> Int# -> Int#
889 {Return the remainder when the {\tt Addr\#} arg, treated like an {\tt Int\#},
890 is divided by the {\tt Int\#} arg.}
891 #if (WORD_SIZE_IN_BITS == 32 || WORD_SIZE_IN_BITS == 64)
892 primop Addr2IntOp "addr2Int#" GenPrimOp Addr# -> Int#
893 {Coerce directly from address to int. Strongly deprecated.}
894 primop Int2AddrOp "int2Addr#" GenPrimOp Int# -> Addr#
895 {Coerce directly from int to address. Strongly deprecated.}
898 primop AddrGtOp "gtAddr#" Compare Addr# -> Addr# -> Bool
899 primop AddrGeOp "geAddr#" Compare Addr# -> Addr# -> Bool
900 primop AddrEqOp "eqAddr#" Compare Addr# -> Addr# -> Bool
901 primop AddrNeOp "neAddr#" Compare Addr# -> Addr# -> Bool
902 primop AddrLtOp "ltAddr#" Compare Addr# -> Addr# -> Bool
903 primop AddrLeOp "leAddr#" Compare Addr# -> Addr# -> Bool
905 primop IndexOffAddrOp_Char "indexCharOffAddr#" GenPrimOp
906 Addr# -> Int# -> Char#
907 {Reads 8-bit character; offset in bytes.}
909 primop IndexOffAddrOp_WideChar "indexWideCharOffAddr#" GenPrimOp
910 Addr# -> Int# -> Char#
911 {Reads 31-bit character; offset in 4-byte words.}
913 primop IndexOffAddrOp_Int "indexIntOffAddr#" GenPrimOp
914 Addr# -> Int# -> Int#
916 primop IndexOffAddrOp_Word "indexWordOffAddr#" GenPrimOp
917 Addr# -> Int# -> Word#
919 primop IndexOffAddrOp_Addr "indexAddrOffAddr#" GenPrimOp
920 Addr# -> Int# -> Addr#
922 primop IndexOffAddrOp_Float "indexFloatOffAddr#" GenPrimOp
923 Addr# -> Int# -> Float#
925 primop IndexOffAddrOp_Double "indexDoubleOffAddr#" GenPrimOp
926 Addr# -> Int# -> Double#
928 primop IndexOffAddrOp_StablePtr "indexStablePtrOffAddr#" GenPrimOp
929 Addr# -> Int# -> StablePtr# a
931 primop IndexOffAddrOp_Int8 "indexInt8OffAddr#" GenPrimOp
932 Addr# -> Int# -> Int#
934 primop IndexOffAddrOp_Int16 "indexInt16OffAddr#" GenPrimOp
935 Addr# -> Int# -> Int#
937 primop IndexOffAddrOp_Int32 "indexInt32OffAddr#" GenPrimOp
938 Addr# -> Int# -> INT32
940 primop IndexOffAddrOp_Int64 "indexInt64OffAddr#" GenPrimOp
941 Addr# -> Int# -> INT64
943 primop IndexOffAddrOp_Word8 "indexWord8OffAddr#" GenPrimOp
944 Addr# -> Int# -> Word#
946 primop IndexOffAddrOp_Word16 "indexWord16OffAddr#" GenPrimOp
947 Addr# -> Int# -> Word#
949 primop IndexOffAddrOp_Word32 "indexWord32OffAddr#" GenPrimOp
950 Addr# -> Int# -> WORD32
952 primop IndexOffAddrOp_Word64 "indexWord64OffAddr#" GenPrimOp
953 Addr# -> Int# -> WORD64
955 primop ReadOffAddrOp_Char "readCharOffAddr#" GenPrimOp
956 Addr# -> Int# -> State# s -> (# State# s, Char# #)
957 {Reads 8-bit character; offset in bytes.}
958 with has_side_effects = True
960 primop ReadOffAddrOp_WideChar "readWideCharOffAddr#" GenPrimOp
961 Addr# -> Int# -> State# s -> (# State# s, Char# #)
962 {Reads 31-bit character; offset in 4-byte words.}
963 with has_side_effects = True
965 primop ReadOffAddrOp_Int "readIntOffAddr#" GenPrimOp
966 Addr# -> Int# -> State# s -> (# State# s, Int# #)
967 with has_side_effects = True
969 primop ReadOffAddrOp_Word "readWordOffAddr#" GenPrimOp
970 Addr# -> Int# -> State# s -> (# State# s, Word# #)
971 with has_side_effects = True
973 primop ReadOffAddrOp_Addr "readAddrOffAddr#" GenPrimOp
974 Addr# -> Int# -> State# s -> (# State# s, Addr# #)
975 with has_side_effects = True
977 primop ReadOffAddrOp_Float "readFloatOffAddr#" GenPrimOp
978 Addr# -> Int# -> State# s -> (# State# s, Float# #)
979 with has_side_effects = True
981 primop ReadOffAddrOp_Double "readDoubleOffAddr#" GenPrimOp
982 Addr# -> Int# -> State# s -> (# State# s, Double# #)
983 with has_side_effects = True
985 primop ReadOffAddrOp_StablePtr "readStablePtrOffAddr#" GenPrimOp
986 Addr# -> Int# -> State# s -> (# State# s, StablePtr# a #)
987 with has_side_effects = True
989 primop ReadOffAddrOp_Int8 "readInt8OffAddr#" GenPrimOp
990 Addr# -> Int# -> State# s -> (# State# s, Int# #)
991 with has_side_effects = True
993 primop ReadOffAddrOp_Int16 "readInt16OffAddr#" GenPrimOp
994 Addr# -> Int# -> State# s -> (# State# s, Int# #)
995 with has_side_effects = True
997 primop ReadOffAddrOp_Int32 "readInt32OffAddr#" GenPrimOp
998 Addr# -> Int# -> State# s -> (# State# s, INT32 #)
999 with has_side_effects = True
1001 primop ReadOffAddrOp_Int64 "readInt64OffAddr#" GenPrimOp
1002 Addr# -> Int# -> State# s -> (# State# s, INT64 #)
1003 with has_side_effects = True
1005 primop ReadOffAddrOp_Word8 "readWord8OffAddr#" GenPrimOp
1006 Addr# -> Int# -> State# s -> (# State# s, Word# #)
1007 with has_side_effects = True
1009 primop ReadOffAddrOp_Word16 "readWord16OffAddr#" GenPrimOp
1010 Addr# -> Int# -> State# s -> (# State# s, Word# #)
1011 with has_side_effects = True
1013 primop ReadOffAddrOp_Word32 "readWord32OffAddr#" GenPrimOp
1014 Addr# -> Int# -> State# s -> (# State# s, WORD32 #)
1015 with has_side_effects = True
1017 primop ReadOffAddrOp_Word64 "readWord64OffAddr#" GenPrimOp
1018 Addr# -> Int# -> State# s -> (# State# s, WORD64 #)
1019 with has_side_effects = True
1022 primop WriteOffAddrOp_Char "writeCharOffAddr#" GenPrimOp
1023 Addr# -> Int# -> Char# -> State# s -> State# s
1024 with has_side_effects = True
1026 primop WriteOffAddrOp_WideChar "writeWideCharOffAddr#" GenPrimOp
1027 Addr# -> Int# -> Char# -> State# s -> State# s
1028 with has_side_effects = True
1030 primop WriteOffAddrOp_Int "writeIntOffAddr#" GenPrimOp
1031 Addr# -> Int# -> Int# -> State# s -> State# s
1032 with has_side_effects = True
1034 primop WriteOffAddrOp_Word "writeWordOffAddr#" GenPrimOp
1035 Addr# -> Int# -> Word# -> State# s -> State# s
1036 with has_side_effects = True
1038 primop WriteOffAddrOp_Addr "writeAddrOffAddr#" GenPrimOp
1039 Addr# -> Int# -> Addr# -> State# s -> State# s
1040 with has_side_effects = True
1042 primop WriteOffAddrOp_Float "writeFloatOffAddr#" GenPrimOp
1043 Addr# -> Int# -> Float# -> State# s -> State# s
1044 with has_side_effects = True
1046 primop WriteOffAddrOp_Double "writeDoubleOffAddr#" GenPrimOp
1047 Addr# -> Int# -> Double# -> State# s -> State# s
1048 with has_side_effects = True
1050 primop WriteOffAddrOp_StablePtr "writeStablePtrOffAddr#" GenPrimOp
1051 Addr# -> Int# -> StablePtr# a -> State# s -> State# s
1052 with has_side_effects = True
1054 primop WriteOffAddrOp_Int8 "writeInt8OffAddr#" GenPrimOp
1055 Addr# -> Int# -> Int# -> State# s -> State# s
1056 with has_side_effects = True
1058 primop WriteOffAddrOp_Int16 "writeInt16OffAddr#" GenPrimOp
1059 Addr# -> Int# -> Int# -> State# s -> State# s
1060 with has_side_effects = True
1062 primop WriteOffAddrOp_Int32 "writeInt32OffAddr#" GenPrimOp
1063 Addr# -> Int# -> INT32 -> State# s -> State# s
1064 with has_side_effects = True
1066 primop WriteOffAddrOp_Int64 "writeInt64OffAddr#" GenPrimOp
1067 Addr# -> Int# -> INT64 -> State# s -> State# s
1068 with has_side_effects = True
1070 primop WriteOffAddrOp_Word8 "writeWord8OffAddr#" GenPrimOp
1071 Addr# -> Int# -> Word# -> State# s -> State# s
1072 with has_side_effects = True
1074 primop WriteOffAddrOp_Word16 "writeWord16OffAddr#" GenPrimOp
1075 Addr# -> Int# -> Word# -> State# s -> State# s
1076 with has_side_effects = True
1078 primop WriteOffAddrOp_Word32 "writeWord32OffAddr#" GenPrimOp
1079 Addr# -> Int# -> WORD32 -> State# s -> State# s
1080 with has_side_effects = True
1082 primop WriteOffAddrOp_Word64 "writeWord64OffAddr#" GenPrimOp
1083 Addr# -> Int# -> WORD64 -> State# s -> State# s
1084 with has_side_effects = True
1086 ------------------------------------------------------------------------
1087 section "Mutable variables"
1088 {Operations on MutVar\#s.}
1089 ------------------------------------------------------------------------
1091 primtype MutVar# s a
1092 {A {\tt MutVar\#} behaves like a single-element mutable array.}
1094 primop NewMutVarOp "newMutVar#" GenPrimOp
1095 a -> State# s -> (# State# s, MutVar# s a #)
1096 {Create {\tt MutVar\#} with specified initial value in specified state thread.}
1099 has_side_effects = True
1101 primop ReadMutVarOp "readMutVar#" GenPrimOp
1102 MutVar# s a -> State# s -> (# State# s, a #)
1103 {Read contents of {\tt MutVar\#}. Result is not yet evaluated.}
1105 has_side_effects = True
1107 primop WriteMutVarOp "writeMutVar#" GenPrimOp
1108 MutVar# s a -> a -> State# s -> State# s
1109 {Write contents of {\tt MutVar\#}.}
1111 has_side_effects = True
1113 primop SameMutVarOp "sameMutVar#" GenPrimOp
1114 MutVar# s a -> MutVar# s a -> Bool
1116 -- not really the right type, but we don't know about pairs here. The
1119 -- MutVar# s a -> (a -> (a,b)) -> State# s -> (# State# s, b #)
1121 primop AtomicModifyMutVarOp "atomicModifyMutVar#" GenPrimOp
1122 MutVar# s a -> (a -> b) -> State# s -> (# State# s, c #)
1125 has_side_effects = True
1127 ------------------------------------------------------------------------
1128 section "Exceptions"
1129 ------------------------------------------------------------------------
1131 primop CatchOp "catch#" GenPrimOp
1132 (State# RealWorld -> (# State# RealWorld, a #) )
1133 -> (b -> State# RealWorld -> (# State# RealWorld, a #) )
1135 -> (# State# RealWorld, a #)
1137 -- Catch is actually strict in its first argument
1138 -- but we don't want to tell the strictness
1139 -- analyser about that!
1140 -- might use caught action multiply
1142 has_side_effects = True
1144 primop RaiseOp "raise#" GenPrimOp
1147 strictness = { \ _arity -> mkStrictSig (mkTopDmdType [lazyDmd] BotRes) }
1148 -- NB: result is bottom
1151 -- raiseIO# needs to be a primop, because exceptions in the IO monad
1152 -- must be *precise* - we don't want the strictness analyser turning
1153 -- one kind of bottom into another, as it is allowed to do in pure code.
1155 primop RaiseIOOp "raiseIO#" GenPrimOp
1156 a -> State# RealWorld -> (# State# RealWorld, b #)
1159 has_side_effects = True
1161 primop BlockAsyncExceptionsOp "blockAsyncExceptions#" GenPrimOp
1162 (State# RealWorld -> (# State# RealWorld, a #))
1163 -> (State# RealWorld -> (# State# RealWorld, a #))
1166 has_side_effects = True
1168 primop UnblockAsyncExceptionsOp "unblockAsyncExceptions#" GenPrimOp
1169 (State# RealWorld -> (# State# RealWorld, a #))
1170 -> (State# RealWorld -> (# State# RealWorld, a #))
1173 has_side_effects = True
1175 primop AsyncExceptionsBlockedOp "asyncExceptionsBlocked#" GenPrimOp
1176 State# RealWorld -> (# State# RealWorld, Int# #)
1179 has_side_effects = True
1181 ------------------------------------------------------------------------
1182 section "STM-accessible Mutable Variables"
1183 ------------------------------------------------------------------------
1187 primop AtomicallyOp "atomically#" GenPrimOp
1188 (State# RealWorld -> (# State# RealWorld, a #) )
1189 -> State# RealWorld -> (# State# RealWorld, a #)
1192 has_side_effects = True
1194 primop RetryOp "retry#" GenPrimOp
1195 State# RealWorld -> (# State# RealWorld, a #)
1198 has_side_effects = True
1200 primop CatchRetryOp "catchRetry#" GenPrimOp
1201 (State# RealWorld -> (# State# RealWorld, a #) )
1202 -> (State# RealWorld -> (# State# RealWorld, a #) )
1203 -> (State# RealWorld -> (# State# RealWorld, a #) )
1206 has_side_effects = True
1208 primop CatchSTMOp "catchSTM#" GenPrimOp
1209 (State# RealWorld -> (# State# RealWorld, a #) )
1210 -> (b -> State# RealWorld -> (# State# RealWorld, a #) )
1211 -> (State# RealWorld -> (# State# RealWorld, a #) )
1214 has_side_effects = True
1216 primop Check "check#" GenPrimOp
1217 (State# RealWorld -> (# State# RealWorld, a #) )
1218 -> (State# RealWorld -> (# State# RealWorld, () #) )
1221 has_side_effects = True
1223 primop NewTVarOp "newTVar#" GenPrimOp
1225 -> State# s -> (# State# s, TVar# s a #)
1226 {Create a new {\tt TVar\#} holding a specified initial value.}
1229 has_side_effects = True
1231 primop ReadTVarOp "readTVar#" GenPrimOp
1233 -> State# s -> (# State# s, a #)
1234 {Read contents of {\tt TVar\#}. Result is not yet evaluated.}
1237 has_side_effects = True
1239 primop ReadTVarIOOp "readTVarIO#" GenPrimOp
1241 -> State# s -> (# State# s, a #)
1242 {Read contents of {\tt TVar\#} outside an STM transaction}
1245 has_side_effects = True
1247 primop WriteTVarOp "writeTVar#" GenPrimOp
1250 -> State# s -> State# s
1251 {Write contents of {\tt TVar\#}.}
1254 has_side_effects = True
1256 primop SameTVarOp "sameTVar#" GenPrimOp
1257 TVar# s a -> TVar# s a -> Bool
1260 ------------------------------------------------------------------------
1261 section "Synchronized Mutable Variables"
1262 {Operations on {\tt MVar\#}s. }
1263 ------------------------------------------------------------------------
1266 { A shared mutable variable ({\it not} the same as a {\tt MutVar\#}!).
1267 (Note: in a non-concurrent implementation, {\tt (MVar\# a)} can be
1268 represented by {\tt (MutVar\# (Maybe a))}.) }
1270 primop NewMVarOp "newMVar#" GenPrimOp
1271 State# s -> (# State# s, MVar# s a #)
1272 {Create new {\tt MVar\#}; initially empty.}
1275 has_side_effects = True
1277 primop TakeMVarOp "takeMVar#" GenPrimOp
1278 MVar# s a -> State# s -> (# State# s, a #)
1279 {If {\tt MVar\#} is empty, block until it becomes full.
1280 Then remove and return its contents, and set it empty.}
1283 has_side_effects = True
1285 primop TryTakeMVarOp "tryTakeMVar#" GenPrimOp
1286 MVar# s a -> State# s -> (# State# s, Int#, a #)
1287 {If {\tt MVar\#} is empty, immediately return with integer 0 and value undefined.
1288 Otherwise, return with integer 1 and contents of {\tt MVar\#}, and set {\tt MVar\#} empty.}
1291 has_side_effects = True
1293 primop PutMVarOp "putMVar#" GenPrimOp
1294 MVar# s a -> a -> State# s -> State# s
1295 {If {\tt MVar\#} is full, block until it becomes empty.
1296 Then store value arg as its new contents.}
1299 has_side_effects = True
1301 primop TryPutMVarOp "tryPutMVar#" GenPrimOp
1302 MVar# s a -> a -> State# s -> (# State# s, Int# #)
1303 {If {\tt MVar\#} is full, immediately return with integer 0.
1304 Otherwise, store value arg as {\tt MVar\#}'s new contents, and return with integer 1.}
1307 has_side_effects = True
1309 primop SameMVarOp "sameMVar#" GenPrimOp
1310 MVar# s a -> MVar# s a -> Bool
1312 primop IsEmptyMVarOp "isEmptyMVar#" GenPrimOp
1313 MVar# s a -> State# s -> (# State# s, Int# #)
1314 {Return 1 if {\tt MVar\#} is empty; 0 otherwise.}
1317 has_side_effects = True
1319 ------------------------------------------------------------------------
1320 section "Delay/wait operations"
1321 ------------------------------------------------------------------------
1323 primop DelayOp "delay#" GenPrimOp
1324 Int# -> State# s -> State# s
1325 {Sleep specified number of microseconds.}
1327 needs_wrapper = True
1328 has_side_effects = True
1331 primop WaitReadOp "waitRead#" GenPrimOp
1332 Int# -> State# s -> State# s
1333 {Block until input is available on specified file descriptor.}
1335 needs_wrapper = True
1336 has_side_effects = True
1339 primop WaitWriteOp "waitWrite#" GenPrimOp
1340 Int# -> State# s -> State# s
1341 {Block until output is possible on specified file descriptor.}
1343 needs_wrapper = True
1344 has_side_effects = True
1347 #ifdef mingw32_TARGET_OS
1348 primop AsyncReadOp "asyncRead#" GenPrimOp
1349 Int# -> Int# -> Int# -> Addr# -> State# RealWorld-> (# State# RealWorld, Int#, Int# #)
1350 {Asynchronously read bytes from specified file descriptor.}
1352 needs_wrapper = True
1353 has_side_effects = True
1356 primop AsyncWriteOp "asyncWrite#" GenPrimOp
1357 Int# -> Int# -> Int# -> Addr# -> State# RealWorld-> (# State# RealWorld, Int#, Int# #)
1358 {Asynchronously write bytes from specified file descriptor.}
1360 needs_wrapper = True
1361 has_side_effects = True
1364 primop AsyncDoProcOp "asyncDoProc#" GenPrimOp
1365 Addr# -> Addr# -> State# RealWorld-> (# State# RealWorld, Int#, Int# #)
1366 {Asynchronously perform procedure (first arg), passing it 2nd arg.}
1368 needs_wrapper = True
1369 has_side_effects = True
1374 ------------------------------------------------------------------------
1375 section "Concurrency primitives"
1376 ------------------------------------------------------------------------
1379 { {\tt State\#} is the primitive, unlifted type of states. It has
1380 one type parameter, thus {\tt State\# RealWorld}, or {\tt State\# s},
1381 where s is a type variable. The only purpose of the type parameter
1382 is to keep different state threads separate. It is represented by
1386 { {\tt RealWorld} is deeply magical. It is {\it primitive}, but it is not
1387 {\it unlifted} (hence {\tt ptrArg}). We never manipulate values of type
1388 {\tt RealWorld}; it's only used in the type system, to parameterise {\tt State\#}. }
1391 {(In a non-concurrent implementation, this can be a singleton
1392 type, whose (unique) value is returned by {\tt myThreadId\#}. The
1393 other operations can be omitted.)}
1395 primop ForkOp "fork#" GenPrimOp
1396 a -> State# RealWorld -> (# State# RealWorld, ThreadId# #)
1398 has_side_effects = True
1401 primop ForkOnOp "forkOn#" GenPrimOp
1402 Int# -> a -> State# RealWorld -> (# State# RealWorld, ThreadId# #)
1404 has_side_effects = True
1407 primop KillThreadOp "killThread#" GenPrimOp
1408 ThreadId# -> a -> State# RealWorld -> State# RealWorld
1410 has_side_effects = True
1413 primop YieldOp "yield#" GenPrimOp
1414 State# RealWorld -> State# RealWorld
1416 has_side_effects = True
1419 primop MyThreadIdOp "myThreadId#" GenPrimOp
1420 State# RealWorld -> (# State# RealWorld, ThreadId# #)
1423 has_side_effects = True
1425 primop LabelThreadOp "labelThread#" GenPrimOp
1426 ThreadId# -> Addr# -> State# RealWorld -> State# RealWorld
1428 has_side_effects = True
1431 primop IsCurrentThreadBoundOp "isCurrentThreadBound#" GenPrimOp
1432 State# RealWorld -> (# State# RealWorld, Int# #)
1435 has_side_effects = True
1437 primop NoDuplicateOp "noDuplicate#" GenPrimOp
1438 State# RealWorld -> State# RealWorld
1441 has_side_effects = True
1443 primop ThreadStatusOp "threadStatus#" GenPrimOp
1444 ThreadId# -> State# RealWorld -> (# State# RealWorld, Int# #)
1447 has_side_effects = True
1449 ------------------------------------------------------------------------
1450 section "Weak pointers"
1451 ------------------------------------------------------------------------
1455 -- note that tyvar "o" denotes openAlphaTyVar
1457 primop MkWeakOp "mkWeak#" GenPrimOp
1458 o -> b -> c -> State# RealWorld -> (# State# RealWorld, Weak# b #)
1460 has_side_effects = True
1463 primop MkWeakForeignEnvOp "mkWeakForeignEnv#" GenPrimOp
1464 o -> b -> Addr# -> Addr# -> Int# -> Addr# -> State# RealWorld -> (# State# RealWorld, Weak# b #)
1466 has_side_effects = True
1469 primop DeRefWeakOp "deRefWeak#" GenPrimOp
1470 Weak# a -> State# RealWorld -> (# State# RealWorld, Int#, a #)
1472 has_side_effects = True
1475 primop FinalizeWeakOp "finalizeWeak#" GenPrimOp
1476 Weak# a -> State# RealWorld -> (# State# RealWorld, Int#,
1477 (State# RealWorld -> (# State# RealWorld, () #)) #)
1479 has_side_effects = True
1482 primop TouchOp "touch#" GenPrimOp
1483 o -> State# RealWorld -> State# RealWorld
1485 has_side_effects = True
1487 ------------------------------------------------------------------------
1488 section "Stable pointers and names"
1489 ------------------------------------------------------------------------
1491 primtype StablePtr# a
1493 primtype StableName# a
1495 primop MakeStablePtrOp "makeStablePtr#" GenPrimOp
1496 a -> State# RealWorld -> (# State# RealWorld, StablePtr# a #)
1498 has_side_effects = True
1501 primop DeRefStablePtrOp "deRefStablePtr#" GenPrimOp
1502 StablePtr# a -> State# RealWorld -> (# State# RealWorld, a #)
1504 needs_wrapper = True
1505 has_side_effects = True
1508 primop EqStablePtrOp "eqStablePtr#" GenPrimOp
1509 StablePtr# a -> StablePtr# a -> Int#
1511 has_side_effects = True
1513 primop MakeStableNameOp "makeStableName#" GenPrimOp
1514 a -> State# RealWorld -> (# State# RealWorld, StableName# a #)
1516 needs_wrapper = True
1517 has_side_effects = True
1520 primop EqStableNameOp "eqStableName#" GenPrimOp
1521 StableName# a -> StableName# a -> Int#
1523 primop StableNameToIntOp "stableNameToInt#" GenPrimOp
1524 StableName# a -> Int#
1526 ------------------------------------------------------------------------
1527 section "Unsafe pointer equality"
1528 -- (#1 Bad Guy: Alistair Reid :)
1529 ------------------------------------------------------------------------
1531 primop ReallyUnsafePtrEqualityOp "reallyUnsafePtrEquality#" GenPrimOp
1534 ------------------------------------------------------------------------
1535 section "Parallelism"
1536 ------------------------------------------------------------------------
1538 primop ParOp "par#" GenPrimOp
1541 -- Note that Par is lazy to avoid that the sparked thing
1542 -- gets evaluted strictly, which it should *not* be
1543 has_side_effects = True
1545 primop GetSparkOp "getSpark#" GenPrimOp
1546 State# s -> (# State# s, Int#, a #)
1548 has_side_effects = True
1551 -- HWL: The first 4 Int# in all par... annotations denote:
1552 -- name, granularity info, size of result, degree of parallelism
1553 -- Same structure as _seq_ i.e. returns Int#
1554 -- KSW: v, the second arg in parAt# and parAtForNow#, is used only to determine
1555 -- `the processor containing the expression v'; it is not evaluated
1557 primop ParGlobalOp "parGlobal#" GenPrimOp
1558 a -> Int# -> Int# -> Int# -> Int# -> b -> Int#
1560 has_side_effects = True
1562 primop ParLocalOp "parLocal#" GenPrimOp
1563 a -> Int# -> Int# -> Int# -> Int# -> b -> Int#
1565 has_side_effects = True
1567 primop ParAtOp "parAt#" GenPrimOp
1568 b -> a -> Int# -> Int# -> Int# -> Int# -> c -> Int#
1570 has_side_effects = True
1572 primop ParAtAbsOp "parAtAbs#" GenPrimOp
1573 a -> Int# -> Int# -> Int# -> Int# -> Int# -> b -> Int#
1575 has_side_effects = True
1577 primop ParAtRelOp "parAtRel#" GenPrimOp
1578 a -> Int# -> Int# -> Int# -> Int# -> Int# -> b -> Int#
1580 has_side_effects = True
1582 primop ParAtForNowOp "parAtForNow#" GenPrimOp
1583 b -> a -> Int# -> Int# -> Int# -> Int# -> c -> Int#
1585 has_side_effects = True
1587 -- copyable# and noFollow# are yet to be implemented (for GpH)
1589 --primop CopyableOp "copyable#" GenPrimOp
1592 -- has_side_effects = True
1594 --primop NoFollowOp "noFollow#" GenPrimOp
1597 -- has_side_effects = True
1600 ------------------------------------------------------------------------
1601 section "Tag to enum stuff"
1602 {Convert back and forth between values of enumerated types
1603 and small integers.}
1604 ------------------------------------------------------------------------
1606 primop DataToTagOp "dataToTag#" GenPrimOp
1609 strictness = { \ _arity -> mkStrictSig (mkTopDmdType [seqDmd] TopRes) }
1610 -- dataToTag# must have an evaluated argument
1612 primop TagToEnumOp "tagToEnum#" GenPrimOp
1615 ------------------------------------------------------------------------
1616 section "Bytecode operations"
1617 {Support for the bytecode interpreter and linker.}
1618 ------------------------------------------------------------------------
1621 {Primitive bytecode type.}
1623 primop AddrToHValueOp "addrToHValue#" GenPrimOp
1625 {Convert an {\tt Addr\#} to a followable type.}
1627 primop MkApUpd0_Op "mkApUpd0#" GenPrimOp
1632 primop NewBCOOp "newBCO#" GenPrimOp
1633 ByteArray# -> ByteArray# -> Array# a -> Int# -> ByteArray# -> State# s -> (# State# s, BCO# #)
1635 has_side_effects = True
1638 primop UnpackClosureOp "unpackClosure#" GenPrimOp
1639 a -> (# Addr#, Array# b, ByteArray# #)
1643 primop GetApStackValOp "getApStackVal#" GenPrimOp
1644 a -> Int# -> (# Int#, b #)
1648 ------------------------------------------------------------------------
1650 {These aren't nearly as wired in as Etc...}
1651 ------------------------------------------------------------------------
1653 primop TraceCcsOp "traceCcs#" GenPrimOp
1656 has_side_effects = True
1659 ------------------------------------------------------------------------
1661 {Miscellaneous built-ins}
1662 ------------------------------------------------------------------------
1666 { Evaluates its first argument to head normal form, and then returns its second
1667 argument as the result. }
1671 { The call {\tt (inline f)} arranges that f is inlined, regardless of its size.
1672 More precisely, the call {\tt (inline f)} rewrites to the right-hand side of
1673 {\tt f}'s definition. This allows the programmer to control inlining from a
1674 particular call site rather than the definition site of the function (c.f.
1675 {\tt INLINE} pragmas in User's Guide, Section 7.10.3, "INLINE and NOINLINE
1678 This inlining occurs regardless of the argument to the call or the size of
1679 {\tt f}'s definition; it is unconditional. The main caveat is that {\tt f}'s
1680 definition must be visible to the compiler. That is, {\tt f} must be
1681 {\tt let}-bound in the current scope. If no inlining takes place, the
1682 {\tt inline} function expands to the identity function in Phase zero; so its
1683 use imposes no overhead.
1685 If the function is defined in another module, GHC only exposes its inlining
1686 in the interface file if the function is sufficiently small that it might be
1687 inlined by the automatic mechanism. There is currently no way to tell GHC to
1688 expose arbitrarily-large functions in the interface file. (This shortcoming
1689 is something that could be fixed, with some kind of pragma.) }
1693 { The {\tt lazy} function restrains strictness analysis a little. The call
1694 {\tt (lazy e)} means the same as {\tt e}, but {\tt lazy} has a magical
1695 property so far as strictness analysis is concerned: it is lazy in its first
1696 argument, even though its semantics is strict. After strictness analysis has
1697 run, calls to {\tt lazy} are inlined to be the identity function.
1699 This behaviour is occasionally useful when controlling evaluation order.
1700 Notably, {\tt lazy} is used in the library definition of {\tt Control.Parallel.par}:
1702 {\tt par :: a -> b -> b}
1704 {\tt par x y = case (par\# x) of \_ -> lazy y}
1706 If {\tt lazy} were not lazy, {\tt par} would look strict in {\tt y} which
1707 would defeat the whole purpose of {\tt par}.
1709 Like {\tt seq}, the argument of {\tt lazy} can have an unboxed type. }
1712 { The type constructor {\tt Any} is type to which you can unsafely coerce any
1713 lifted type, and back.
1715 * It is lifted, and hence represented by a pointer
1717 * It does not claim to be a {\it data} type, and that's important for
1718 the code generator, because the code gen may {\it enter} a data value
1719 but never enters a function value.
1721 It's also used to instantiate un-constrained type variables after type
1722 checking. For example
1726 Annoyingly, we sometimes need {\tt Any}s of other kinds, such as {\tt (* -> *)} etc.
1727 This is a bit like tuples. We define a couple of useful ones here,
1728 and make others up on the fly. If any of these others end up being exported
1729 into interface files, we'll get a crash; at least until we add interface-file
1730 syntax to support them. }
1732 pseudoop "unsafeCoerce#"
1734 { The function {\tt unsafeCoerce\#} allows you to side-step the typechecker entirely. That
1735 is, it allows you to coerce any type into any other type. If you use this function,
1736 you had better get it right, otherwise segmentation faults await. It is generally
1737 used when you want to write a program that you know is well-typed, but where Haskell's
1738 type system is not expressive enough to prove that it is well typed.
1740 The following uses of {\tt unsafeCoerce\#} are supposed to work (i.e. not lead to
1741 spurious compile-time or run-time crashes):
1743 * Casting any lifted type to {\tt Any}
1745 * Casting {\tt Any} back to the real type
1747 * Casting an unboxed type to another unboxed type of the same size
1748 (but not coercions between floating-point and integral types)
1750 * Casting between two types that have the same runtime representation. One case is when
1751 the two types differ only in "phantom" type parameters, for example
1752 {\tt Ptr Int} to {\tt Ptr Float}, or {\tt [Int]} to {\tt [Float]} when the list is
1753 known to be empty. Also, a {\tt newtype} of a type {\tt T} has the same representation
1754 at runtime as {\tt T}.
1756 Other uses of {\tt unsafeCoerce\#} are undefined. In particular, you should not use
1757 {\tt unsafeCoerce\#} to cast a T to an algebraic data type D, unless T is also
1758 an algebraic data type. For example, do not cast {\tt Int->Int} to {\tt Bool}, even if
1759 you later cast that {\tt Bool} back to {\tt Int->Int} before applying it. The reasons
1760 have to do with GHC's internal representation details (for the congnoscenti, data values
1761 can be entered but function closures cannot). If you want a safe type to cast things
1762 to, use {\tt Any}, which is not an algebraic data type.
1766 -- NB. It is tempting to think that casting a value to a type that it doesn't have is safe
1767 -- as long as you don't "do anything" with the value in its cast form, such as seq on it. This
1768 -- isn't the case: the compiler can insert seqs itself, and if these happen at the wrong type,
1769 -- Bad Things Might Happen. See bug #1616: in this case we cast a function of type (a,b) -> (a,b)
1770 -- to () -> () and back again. The strictness analyser saw that the function was strict, but
1771 -- the wrapper had type () -> (), and hence the wrapper de-constructed the (), the worker re-constructed
1772 -- a new (), with the result that the code ended up with "case () of (a,b) -> ...".
1774 primop TraceEventOp "traceEvent#" GenPrimOp
1775 Addr# -> State# s -> State# s
1776 { Emits an event via the RTS tracing framework. The contents
1777 of the event is the zero-terminated byte string passed as the first
1778 argument. The event will be emitted either to the .eventlog file,
1779 or to stderr, depending on the runtime RTS flags. }
1781 has_side_effects = True
1784 ------------------------------------------------------------------------
1786 ------------------------------------------------------------------------