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,
637 rounded up to the nearest multiple of a word). There are
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, rounded up to the nearest multiple
688 primop SizeofMutableByteArrayOp "sizeofMutableByteArray#" GenPrimOp
689 MutableByteArray# s -> Int#
690 {Return the size of the array in bytes, rounded up to the nearest multiple
693 primop IndexByteArrayOp_Char "indexCharArray#" GenPrimOp
694 ByteArray# -> Int# -> Char#
695 {Read 8-bit character; offset in bytes.}
697 primop IndexByteArrayOp_WideChar "indexWideCharArray#" GenPrimOp
698 ByteArray# -> Int# -> Char#
699 {Read 31-bit character; offset in 4-byte words.}
701 primop IndexByteArrayOp_Int "indexIntArray#" GenPrimOp
702 ByteArray# -> Int# -> Int#
704 primop IndexByteArrayOp_Word "indexWordArray#" GenPrimOp
705 ByteArray# -> Int# -> Word#
707 primop IndexByteArrayOp_Addr "indexAddrArray#" GenPrimOp
708 ByteArray# -> Int# -> Addr#
710 primop IndexByteArrayOp_Float "indexFloatArray#" GenPrimOp
711 ByteArray# -> Int# -> Float#
713 primop IndexByteArrayOp_Double "indexDoubleArray#" GenPrimOp
714 ByteArray# -> Int# -> Double#
716 primop IndexByteArrayOp_StablePtr "indexStablePtrArray#" GenPrimOp
717 ByteArray# -> Int# -> StablePtr# a
719 primop IndexByteArrayOp_Int8 "indexInt8Array#" GenPrimOp
720 ByteArray# -> Int# -> Int#
722 primop IndexByteArrayOp_Int16 "indexInt16Array#" GenPrimOp
723 ByteArray# -> Int# -> Int#
725 primop IndexByteArrayOp_Int32 "indexInt32Array#" GenPrimOp
726 ByteArray# -> Int# -> INT32
728 primop IndexByteArrayOp_Int64 "indexInt64Array#" GenPrimOp
729 ByteArray# -> Int# -> INT64
731 primop IndexByteArrayOp_Word8 "indexWord8Array#" GenPrimOp
732 ByteArray# -> Int# -> Word#
734 primop IndexByteArrayOp_Word16 "indexWord16Array#" GenPrimOp
735 ByteArray# -> Int# -> Word#
737 primop IndexByteArrayOp_Word32 "indexWord32Array#" GenPrimOp
738 ByteArray# -> Int# -> WORD32
740 primop IndexByteArrayOp_Word64 "indexWord64Array#" GenPrimOp
741 ByteArray# -> Int# -> WORD64
743 primop ReadByteArrayOp_Char "readCharArray#" GenPrimOp
744 MutableByteArray# s -> Int# -> State# s -> (# State# s, Char# #)
745 {Read 8-bit character; offset in bytes.}
746 with has_side_effects = True
748 primop ReadByteArrayOp_WideChar "readWideCharArray#" GenPrimOp
749 MutableByteArray# s -> Int# -> State# s -> (# State# s, Char# #)
750 {Read 31-bit character; offset in 4-byte words.}
751 with has_side_effects = True
753 primop ReadByteArrayOp_Int "readIntArray#" GenPrimOp
754 MutableByteArray# s -> Int# -> State# s -> (# State# s, Int# #)
755 with has_side_effects = True
757 primop ReadByteArrayOp_Word "readWordArray#" GenPrimOp
758 MutableByteArray# s -> Int# -> State# s -> (# State# s, Word# #)
759 with has_side_effects = True
761 primop ReadByteArrayOp_Addr "readAddrArray#" GenPrimOp
762 MutableByteArray# s -> Int# -> State# s -> (# State# s, Addr# #)
763 with has_side_effects = True
765 primop ReadByteArrayOp_Float "readFloatArray#" GenPrimOp
766 MutableByteArray# s -> Int# -> State# s -> (# State# s, Float# #)
767 with has_side_effects = True
769 primop ReadByteArrayOp_Double "readDoubleArray#" GenPrimOp
770 MutableByteArray# s -> Int# -> State# s -> (# State# s, Double# #)
771 with has_side_effects = True
773 primop ReadByteArrayOp_StablePtr "readStablePtrArray#" GenPrimOp
774 MutableByteArray# s -> Int# -> State# s -> (# State# s, StablePtr# a #)
775 with has_side_effects = True
777 primop ReadByteArrayOp_Int8 "readInt8Array#" GenPrimOp
778 MutableByteArray# s -> Int# -> State# s -> (# State# s, Int# #)
779 with has_side_effects = True
781 primop ReadByteArrayOp_Int16 "readInt16Array#" GenPrimOp
782 MutableByteArray# s -> Int# -> State# s -> (# State# s, Int# #)
783 with has_side_effects = True
785 primop ReadByteArrayOp_Int32 "readInt32Array#" GenPrimOp
786 MutableByteArray# s -> Int# -> State# s -> (# State# s, INT32 #)
787 with has_side_effects = True
789 primop ReadByteArrayOp_Int64 "readInt64Array#" GenPrimOp
790 MutableByteArray# s -> Int# -> State# s -> (# State# s, INT64 #)
791 with has_side_effects = True
793 primop ReadByteArrayOp_Word8 "readWord8Array#" GenPrimOp
794 MutableByteArray# s -> Int# -> State# s -> (# State# s, Word# #)
795 with has_side_effects = True
797 primop ReadByteArrayOp_Word16 "readWord16Array#" GenPrimOp
798 MutableByteArray# s -> Int# -> State# s -> (# State# s, Word# #)
799 with has_side_effects = True
801 primop ReadByteArrayOp_Word32 "readWord32Array#" GenPrimOp
802 MutableByteArray# s -> Int# -> State# s -> (# State# s, WORD32 #)
803 with has_side_effects = True
805 primop ReadByteArrayOp_Word64 "readWord64Array#" GenPrimOp
806 MutableByteArray# s -> Int# -> State# s -> (# State# s, WORD64 #)
807 with has_side_effects = True
809 primop WriteByteArrayOp_Char "writeCharArray#" GenPrimOp
810 MutableByteArray# s -> Int# -> Char# -> State# s -> State# s
811 {Write 8-bit character; offset in bytes.}
812 with has_side_effects = True
814 primop WriteByteArrayOp_WideChar "writeWideCharArray#" GenPrimOp
815 MutableByteArray# s -> Int# -> Char# -> State# s -> State# s
816 {Write 31-bit character; offset in 4-byte words.}
817 with has_side_effects = True
819 primop WriteByteArrayOp_Int "writeIntArray#" GenPrimOp
820 MutableByteArray# s -> Int# -> Int# -> State# s -> State# s
821 with has_side_effects = True
823 primop WriteByteArrayOp_Word "writeWordArray#" GenPrimOp
824 MutableByteArray# s -> Int# -> Word# -> State# s -> State# s
825 with has_side_effects = True
827 primop WriteByteArrayOp_Addr "writeAddrArray#" GenPrimOp
828 MutableByteArray# s -> Int# -> Addr# -> State# s -> State# s
829 with has_side_effects = True
831 primop WriteByteArrayOp_Float "writeFloatArray#" GenPrimOp
832 MutableByteArray# s -> Int# -> Float# -> State# s -> State# s
833 with has_side_effects = True
835 primop WriteByteArrayOp_Double "writeDoubleArray#" GenPrimOp
836 MutableByteArray# s -> Int# -> Double# -> State# s -> State# s
837 with has_side_effects = True
839 primop WriteByteArrayOp_StablePtr "writeStablePtrArray#" GenPrimOp
840 MutableByteArray# s -> Int# -> StablePtr# a -> State# s -> State# s
841 with has_side_effects = True
843 primop WriteByteArrayOp_Int8 "writeInt8Array#" GenPrimOp
844 MutableByteArray# s -> Int# -> Int# -> State# s -> State# s
845 with has_side_effects = True
847 primop WriteByteArrayOp_Int16 "writeInt16Array#" GenPrimOp
848 MutableByteArray# s -> Int# -> Int# -> State# s -> State# s
849 with has_side_effects = True
851 primop WriteByteArrayOp_Int32 "writeInt32Array#" GenPrimOp
852 MutableByteArray# s -> Int# -> INT32 -> State# s -> State# s
853 with has_side_effects = True
855 primop WriteByteArrayOp_Int64 "writeInt64Array#" GenPrimOp
856 MutableByteArray# s -> Int# -> INT64 -> State# s -> State# s
857 with has_side_effects = True
859 primop WriteByteArrayOp_Word8 "writeWord8Array#" GenPrimOp
860 MutableByteArray# s -> Int# -> Word# -> State# s -> State# s
861 with has_side_effects = True
863 primop WriteByteArrayOp_Word16 "writeWord16Array#" GenPrimOp
864 MutableByteArray# s -> Int# -> Word# -> State# s -> State# s
865 with has_side_effects = True
867 primop WriteByteArrayOp_Word32 "writeWord32Array#" GenPrimOp
868 MutableByteArray# s -> Int# -> WORD32 -> State# s -> State# s
869 with has_side_effects = True
871 primop WriteByteArrayOp_Word64 "writeWord64Array#" GenPrimOp
872 MutableByteArray# s -> Int# -> WORD64 -> State# s -> State# s
873 with has_side_effects = True
875 ------------------------------------------------------------------------
877 ------------------------------------------------------------------------
880 { An arbitrary machine address assumed to point outside
881 the garbage-collected heap. }
883 pseudoop "nullAddr#" Addr#
884 { The null address. }
886 primop AddrAddOp "plusAddr#" GenPrimOp Addr# -> Int# -> Addr#
887 primop AddrSubOp "minusAddr#" GenPrimOp Addr# -> Addr# -> Int#
888 {Result is meaningless if two {\tt Addr\#}s are so far apart that their
889 difference doesn't fit in an {\tt Int\#}.}
890 primop AddrRemOp "remAddr#" GenPrimOp Addr# -> Int# -> Int#
891 {Return the remainder when the {\tt Addr\#} arg, treated like an {\tt Int\#},
892 is divided by the {\tt Int\#} arg.}
893 #if (WORD_SIZE_IN_BITS == 32 || WORD_SIZE_IN_BITS == 64)
894 primop Addr2IntOp "addr2Int#" GenPrimOp Addr# -> Int#
895 {Coerce directly from address to int. Strongly deprecated.}
896 primop Int2AddrOp "int2Addr#" GenPrimOp Int# -> Addr#
897 {Coerce directly from int to address. Strongly deprecated.}
900 primop AddrGtOp "gtAddr#" Compare Addr# -> Addr# -> Bool
901 primop AddrGeOp "geAddr#" Compare Addr# -> Addr# -> Bool
902 primop AddrEqOp "eqAddr#" Compare Addr# -> Addr# -> Bool
903 primop AddrNeOp "neAddr#" Compare Addr# -> Addr# -> Bool
904 primop AddrLtOp "ltAddr#" Compare Addr# -> Addr# -> Bool
905 primop AddrLeOp "leAddr#" Compare Addr# -> Addr# -> Bool
907 primop IndexOffAddrOp_Char "indexCharOffAddr#" GenPrimOp
908 Addr# -> Int# -> Char#
909 {Reads 8-bit character; offset in bytes.}
911 primop IndexOffAddrOp_WideChar "indexWideCharOffAddr#" GenPrimOp
912 Addr# -> Int# -> Char#
913 {Reads 31-bit character; offset in 4-byte words.}
915 primop IndexOffAddrOp_Int "indexIntOffAddr#" GenPrimOp
916 Addr# -> Int# -> Int#
918 primop IndexOffAddrOp_Word "indexWordOffAddr#" GenPrimOp
919 Addr# -> Int# -> Word#
921 primop IndexOffAddrOp_Addr "indexAddrOffAddr#" GenPrimOp
922 Addr# -> Int# -> Addr#
924 primop IndexOffAddrOp_Float "indexFloatOffAddr#" GenPrimOp
925 Addr# -> Int# -> Float#
927 primop IndexOffAddrOp_Double "indexDoubleOffAddr#" GenPrimOp
928 Addr# -> Int# -> Double#
930 primop IndexOffAddrOp_StablePtr "indexStablePtrOffAddr#" GenPrimOp
931 Addr# -> Int# -> StablePtr# a
933 primop IndexOffAddrOp_Int8 "indexInt8OffAddr#" GenPrimOp
934 Addr# -> Int# -> Int#
936 primop IndexOffAddrOp_Int16 "indexInt16OffAddr#" GenPrimOp
937 Addr# -> Int# -> Int#
939 primop IndexOffAddrOp_Int32 "indexInt32OffAddr#" GenPrimOp
940 Addr# -> Int# -> INT32
942 primop IndexOffAddrOp_Int64 "indexInt64OffAddr#" GenPrimOp
943 Addr# -> Int# -> INT64
945 primop IndexOffAddrOp_Word8 "indexWord8OffAddr#" GenPrimOp
946 Addr# -> Int# -> Word#
948 primop IndexOffAddrOp_Word16 "indexWord16OffAddr#" GenPrimOp
949 Addr# -> Int# -> Word#
951 primop IndexOffAddrOp_Word32 "indexWord32OffAddr#" GenPrimOp
952 Addr# -> Int# -> WORD32
954 primop IndexOffAddrOp_Word64 "indexWord64OffAddr#" GenPrimOp
955 Addr# -> Int# -> WORD64
957 primop ReadOffAddrOp_Char "readCharOffAddr#" GenPrimOp
958 Addr# -> Int# -> State# s -> (# State# s, Char# #)
959 {Reads 8-bit character; offset in bytes.}
960 with has_side_effects = True
962 primop ReadOffAddrOp_WideChar "readWideCharOffAddr#" GenPrimOp
963 Addr# -> Int# -> State# s -> (# State# s, Char# #)
964 {Reads 31-bit character; offset in 4-byte words.}
965 with has_side_effects = True
967 primop ReadOffAddrOp_Int "readIntOffAddr#" GenPrimOp
968 Addr# -> Int# -> State# s -> (# State# s, Int# #)
969 with has_side_effects = True
971 primop ReadOffAddrOp_Word "readWordOffAddr#" GenPrimOp
972 Addr# -> Int# -> State# s -> (# State# s, Word# #)
973 with has_side_effects = True
975 primop ReadOffAddrOp_Addr "readAddrOffAddr#" GenPrimOp
976 Addr# -> Int# -> State# s -> (# State# s, Addr# #)
977 with has_side_effects = True
979 primop ReadOffAddrOp_Float "readFloatOffAddr#" GenPrimOp
980 Addr# -> Int# -> State# s -> (# State# s, Float# #)
981 with has_side_effects = True
983 primop ReadOffAddrOp_Double "readDoubleOffAddr#" GenPrimOp
984 Addr# -> Int# -> State# s -> (# State# s, Double# #)
985 with has_side_effects = True
987 primop ReadOffAddrOp_StablePtr "readStablePtrOffAddr#" GenPrimOp
988 Addr# -> Int# -> State# s -> (# State# s, StablePtr# a #)
989 with has_side_effects = True
991 primop ReadOffAddrOp_Int8 "readInt8OffAddr#" GenPrimOp
992 Addr# -> Int# -> State# s -> (# State# s, Int# #)
993 with has_side_effects = True
995 primop ReadOffAddrOp_Int16 "readInt16OffAddr#" GenPrimOp
996 Addr# -> Int# -> State# s -> (# State# s, Int# #)
997 with has_side_effects = True
999 primop ReadOffAddrOp_Int32 "readInt32OffAddr#" GenPrimOp
1000 Addr# -> Int# -> State# s -> (# State# s, INT32 #)
1001 with has_side_effects = True
1003 primop ReadOffAddrOp_Int64 "readInt64OffAddr#" GenPrimOp
1004 Addr# -> Int# -> State# s -> (# State# s, INT64 #)
1005 with has_side_effects = True
1007 primop ReadOffAddrOp_Word8 "readWord8OffAddr#" GenPrimOp
1008 Addr# -> Int# -> State# s -> (# State# s, Word# #)
1009 with has_side_effects = True
1011 primop ReadOffAddrOp_Word16 "readWord16OffAddr#" GenPrimOp
1012 Addr# -> Int# -> State# s -> (# State# s, Word# #)
1013 with has_side_effects = True
1015 primop ReadOffAddrOp_Word32 "readWord32OffAddr#" GenPrimOp
1016 Addr# -> Int# -> State# s -> (# State# s, WORD32 #)
1017 with has_side_effects = True
1019 primop ReadOffAddrOp_Word64 "readWord64OffAddr#" GenPrimOp
1020 Addr# -> Int# -> State# s -> (# State# s, WORD64 #)
1021 with has_side_effects = True
1024 primop WriteOffAddrOp_Char "writeCharOffAddr#" GenPrimOp
1025 Addr# -> Int# -> Char# -> State# s -> State# s
1026 with has_side_effects = True
1028 primop WriteOffAddrOp_WideChar "writeWideCharOffAddr#" GenPrimOp
1029 Addr# -> Int# -> Char# -> State# s -> State# s
1030 with has_side_effects = True
1032 primop WriteOffAddrOp_Int "writeIntOffAddr#" GenPrimOp
1033 Addr# -> Int# -> Int# -> State# s -> State# s
1034 with has_side_effects = True
1036 primop WriteOffAddrOp_Word "writeWordOffAddr#" GenPrimOp
1037 Addr# -> Int# -> Word# -> State# s -> State# s
1038 with has_side_effects = True
1040 primop WriteOffAddrOp_Addr "writeAddrOffAddr#" GenPrimOp
1041 Addr# -> Int# -> Addr# -> State# s -> State# s
1042 with has_side_effects = True
1044 primop WriteOffAddrOp_Float "writeFloatOffAddr#" GenPrimOp
1045 Addr# -> Int# -> Float# -> State# s -> State# s
1046 with has_side_effects = True
1048 primop WriteOffAddrOp_Double "writeDoubleOffAddr#" GenPrimOp
1049 Addr# -> Int# -> Double# -> State# s -> State# s
1050 with has_side_effects = True
1052 primop WriteOffAddrOp_StablePtr "writeStablePtrOffAddr#" GenPrimOp
1053 Addr# -> Int# -> StablePtr# a -> State# s -> State# s
1054 with has_side_effects = True
1056 primop WriteOffAddrOp_Int8 "writeInt8OffAddr#" GenPrimOp
1057 Addr# -> Int# -> Int# -> State# s -> State# s
1058 with has_side_effects = True
1060 primop WriteOffAddrOp_Int16 "writeInt16OffAddr#" GenPrimOp
1061 Addr# -> Int# -> Int# -> State# s -> State# s
1062 with has_side_effects = True
1064 primop WriteOffAddrOp_Int32 "writeInt32OffAddr#" GenPrimOp
1065 Addr# -> Int# -> INT32 -> State# s -> State# s
1066 with has_side_effects = True
1068 primop WriteOffAddrOp_Int64 "writeInt64OffAddr#" GenPrimOp
1069 Addr# -> Int# -> INT64 -> State# s -> State# s
1070 with has_side_effects = True
1072 primop WriteOffAddrOp_Word8 "writeWord8OffAddr#" GenPrimOp
1073 Addr# -> Int# -> Word# -> State# s -> State# s
1074 with has_side_effects = True
1076 primop WriteOffAddrOp_Word16 "writeWord16OffAddr#" GenPrimOp
1077 Addr# -> Int# -> Word# -> State# s -> State# s
1078 with has_side_effects = True
1080 primop WriteOffAddrOp_Word32 "writeWord32OffAddr#" GenPrimOp
1081 Addr# -> Int# -> WORD32 -> State# s -> State# s
1082 with has_side_effects = True
1084 primop WriteOffAddrOp_Word64 "writeWord64OffAddr#" GenPrimOp
1085 Addr# -> Int# -> WORD64 -> State# s -> State# s
1086 with has_side_effects = True
1088 ------------------------------------------------------------------------
1089 section "Mutable variables"
1090 {Operations on MutVar\#s.}
1091 ------------------------------------------------------------------------
1093 primtype MutVar# s a
1094 {A {\tt MutVar\#} behaves like a single-element mutable array.}
1096 primop NewMutVarOp "newMutVar#" GenPrimOp
1097 a -> State# s -> (# State# s, MutVar# s a #)
1098 {Create {\tt MutVar\#} with specified initial value in specified state thread.}
1101 has_side_effects = True
1103 primop ReadMutVarOp "readMutVar#" GenPrimOp
1104 MutVar# s a -> State# s -> (# State# s, a #)
1105 {Read contents of {\tt MutVar\#}. Result is not yet evaluated.}
1107 has_side_effects = True
1109 primop WriteMutVarOp "writeMutVar#" GenPrimOp
1110 MutVar# s a -> a -> State# s -> State# s
1111 {Write contents of {\tt MutVar\#}.}
1113 has_side_effects = True
1115 primop SameMutVarOp "sameMutVar#" GenPrimOp
1116 MutVar# s a -> MutVar# s a -> Bool
1118 -- not really the right type, but we don't know about pairs here. The
1121 -- MutVar# s a -> (a -> (a,b)) -> State# s -> (# State# s, b #)
1123 primop AtomicModifyMutVarOp "atomicModifyMutVar#" GenPrimOp
1124 MutVar# s a -> (a -> b) -> State# s -> (# State# s, c #)
1127 has_side_effects = True
1129 ------------------------------------------------------------------------
1130 section "Exceptions"
1131 ------------------------------------------------------------------------
1133 primop CatchOp "catch#" GenPrimOp
1134 (State# RealWorld -> (# State# RealWorld, a #) )
1135 -> (b -> State# RealWorld -> (# State# RealWorld, a #) )
1137 -> (# State# RealWorld, a #)
1139 -- Catch is actually strict in its first argument
1140 -- but we don't want to tell the strictness
1141 -- analyser about that!
1142 -- might use caught action multiply
1144 has_side_effects = True
1146 primop RaiseOp "raise#" GenPrimOp
1149 strictness = { \ _arity -> mkStrictSig (mkTopDmdType [lazyDmd] BotRes) }
1150 -- NB: result is bottom
1153 -- raiseIO# needs to be a primop, because exceptions in the IO monad
1154 -- must be *precise* - we don't want the strictness analyser turning
1155 -- one kind of bottom into another, as it is allowed to do in pure code.
1157 primop RaiseIOOp "raiseIO#" GenPrimOp
1158 a -> State# RealWorld -> (# State# RealWorld, b #)
1161 has_side_effects = True
1163 primop BlockAsyncExceptionsOp "blockAsyncExceptions#" GenPrimOp
1164 (State# RealWorld -> (# State# RealWorld, a #))
1165 -> (State# RealWorld -> (# State# RealWorld, a #))
1168 has_side_effects = True
1170 primop UnblockAsyncExceptionsOp "unblockAsyncExceptions#" GenPrimOp
1171 (State# RealWorld -> (# State# RealWorld, a #))
1172 -> (State# RealWorld -> (# State# RealWorld, a #))
1175 has_side_effects = True
1177 primop AsyncExceptionsBlockedOp "asyncExceptionsBlocked#" GenPrimOp
1178 State# RealWorld -> (# State# RealWorld, Int# #)
1181 has_side_effects = True
1183 ------------------------------------------------------------------------
1184 section "STM-accessible Mutable Variables"
1185 ------------------------------------------------------------------------
1189 primop AtomicallyOp "atomically#" GenPrimOp
1190 (State# RealWorld -> (# State# RealWorld, a #) )
1191 -> State# RealWorld -> (# State# RealWorld, a #)
1194 has_side_effects = True
1196 primop RetryOp "retry#" GenPrimOp
1197 State# RealWorld -> (# State# RealWorld, a #)
1200 has_side_effects = True
1202 primop CatchRetryOp "catchRetry#" GenPrimOp
1203 (State# RealWorld -> (# State# RealWorld, a #) )
1204 -> (State# RealWorld -> (# State# RealWorld, a #) )
1205 -> (State# RealWorld -> (# State# RealWorld, a #) )
1208 has_side_effects = True
1210 primop CatchSTMOp "catchSTM#" GenPrimOp
1211 (State# RealWorld -> (# State# RealWorld, a #) )
1212 -> (b -> State# RealWorld -> (# State# RealWorld, a #) )
1213 -> (State# RealWorld -> (# State# RealWorld, a #) )
1216 has_side_effects = True
1218 primop Check "check#" GenPrimOp
1219 (State# RealWorld -> (# State# RealWorld, a #) )
1220 -> (State# RealWorld -> (# State# RealWorld, () #) )
1223 has_side_effects = True
1225 primop NewTVarOp "newTVar#" GenPrimOp
1227 -> State# s -> (# State# s, TVar# s a #)
1228 {Create a new {\tt TVar\#} holding a specified initial value.}
1231 has_side_effects = True
1233 primop ReadTVarOp "readTVar#" GenPrimOp
1235 -> State# s -> (# State# s, a #)
1236 {Read contents of {\tt TVar\#}. Result is not yet evaluated.}
1239 has_side_effects = True
1241 primop ReadTVarIOOp "readTVarIO#" GenPrimOp
1243 -> State# s -> (# State# s, a #)
1244 {Read contents of {\tt TVar\#} outside an STM transaction}
1247 has_side_effects = True
1249 primop WriteTVarOp "writeTVar#" GenPrimOp
1252 -> State# s -> State# s
1253 {Write contents of {\tt TVar\#}.}
1256 has_side_effects = True
1258 primop SameTVarOp "sameTVar#" GenPrimOp
1259 TVar# s a -> TVar# s a -> Bool
1262 ------------------------------------------------------------------------
1263 section "Synchronized Mutable Variables"
1264 {Operations on {\tt MVar\#}s. }
1265 ------------------------------------------------------------------------
1268 { A shared mutable variable ({\it not} the same as a {\tt MutVar\#}!).
1269 (Note: in a non-concurrent implementation, {\tt (MVar\# a)} can be
1270 represented by {\tt (MutVar\# (Maybe a))}.) }
1272 primop NewMVarOp "newMVar#" GenPrimOp
1273 State# s -> (# State# s, MVar# s a #)
1274 {Create new {\tt MVar\#}; initially empty.}
1277 has_side_effects = True
1279 primop TakeMVarOp "takeMVar#" GenPrimOp
1280 MVar# s a -> State# s -> (# State# s, a #)
1281 {If {\tt MVar\#} is empty, block until it becomes full.
1282 Then remove and return its contents, and set it empty.}
1285 has_side_effects = True
1287 primop TryTakeMVarOp "tryTakeMVar#" GenPrimOp
1288 MVar# s a -> State# s -> (# State# s, Int#, a #)
1289 {If {\tt MVar\#} is empty, immediately return with integer 0 and value undefined.
1290 Otherwise, return with integer 1 and contents of {\tt MVar\#}, and set {\tt MVar\#} empty.}
1293 has_side_effects = True
1295 primop PutMVarOp "putMVar#" GenPrimOp
1296 MVar# s a -> a -> State# s -> State# s
1297 {If {\tt MVar\#} is full, block until it becomes empty.
1298 Then store value arg as its new contents.}
1301 has_side_effects = True
1303 primop TryPutMVarOp "tryPutMVar#" GenPrimOp
1304 MVar# s a -> a -> State# s -> (# State# s, Int# #)
1305 {If {\tt MVar\#} is full, immediately return with integer 0.
1306 Otherwise, store value arg as {\tt MVar\#}'s new contents, and return with integer 1.}
1309 has_side_effects = True
1311 primop SameMVarOp "sameMVar#" GenPrimOp
1312 MVar# s a -> MVar# s a -> Bool
1314 primop IsEmptyMVarOp "isEmptyMVar#" GenPrimOp
1315 MVar# s a -> State# s -> (# State# s, Int# #)
1316 {Return 1 if {\tt MVar\#} is empty; 0 otherwise.}
1319 has_side_effects = True
1321 ------------------------------------------------------------------------
1322 section "Delay/wait operations"
1323 ------------------------------------------------------------------------
1325 primop DelayOp "delay#" GenPrimOp
1326 Int# -> State# s -> State# s
1327 {Sleep specified number of microseconds.}
1329 needs_wrapper = True
1330 has_side_effects = True
1333 primop WaitReadOp "waitRead#" GenPrimOp
1334 Int# -> State# s -> State# s
1335 {Block until input is available on specified file descriptor.}
1337 needs_wrapper = True
1338 has_side_effects = True
1341 primop WaitWriteOp "waitWrite#" GenPrimOp
1342 Int# -> State# s -> State# s
1343 {Block until output is possible on specified file descriptor.}
1345 needs_wrapper = True
1346 has_side_effects = True
1349 #ifdef mingw32_TARGET_OS
1350 primop AsyncReadOp "asyncRead#" GenPrimOp
1351 Int# -> Int# -> Int# -> Addr# -> State# RealWorld-> (# State# RealWorld, Int#, Int# #)
1352 {Asynchronously read bytes from specified file descriptor.}
1354 needs_wrapper = True
1355 has_side_effects = True
1358 primop AsyncWriteOp "asyncWrite#" GenPrimOp
1359 Int# -> Int# -> Int# -> Addr# -> State# RealWorld-> (# State# RealWorld, Int#, Int# #)
1360 {Asynchronously write bytes from specified file descriptor.}
1362 needs_wrapper = True
1363 has_side_effects = True
1366 primop AsyncDoProcOp "asyncDoProc#" GenPrimOp
1367 Addr# -> Addr# -> State# RealWorld-> (# State# RealWorld, Int#, Int# #)
1368 {Asynchronously perform procedure (first arg), passing it 2nd arg.}
1370 needs_wrapper = True
1371 has_side_effects = True
1376 ------------------------------------------------------------------------
1377 section "Concurrency primitives"
1378 ------------------------------------------------------------------------
1381 { {\tt State\#} is the primitive, unlifted type of states. It has
1382 one type parameter, thus {\tt State\# RealWorld}, or {\tt State\# s},
1383 where s is a type variable. The only purpose of the type parameter
1384 is to keep different state threads separate. It is represented by
1388 { {\tt RealWorld} is deeply magical. It is {\it primitive}, but it is not
1389 {\it unlifted} (hence {\tt ptrArg}). We never manipulate values of type
1390 {\tt RealWorld}; it's only used in the type system, to parameterise {\tt State\#}. }
1393 {(In a non-concurrent implementation, this can be a singleton
1394 type, whose (unique) value is returned by {\tt myThreadId\#}. The
1395 other operations can be omitted.)}
1397 primop ForkOp "fork#" GenPrimOp
1398 a -> State# RealWorld -> (# State# RealWorld, ThreadId# #)
1400 has_side_effects = True
1403 primop ForkOnOp "forkOn#" GenPrimOp
1404 Int# -> a -> State# RealWorld -> (# State# RealWorld, ThreadId# #)
1406 has_side_effects = True
1409 primop KillThreadOp "killThread#" GenPrimOp
1410 ThreadId# -> a -> State# RealWorld -> State# RealWorld
1412 has_side_effects = True
1415 primop YieldOp "yield#" GenPrimOp
1416 State# RealWorld -> State# RealWorld
1418 has_side_effects = True
1421 primop MyThreadIdOp "myThreadId#" GenPrimOp
1422 State# RealWorld -> (# State# RealWorld, ThreadId# #)
1425 has_side_effects = True
1427 primop LabelThreadOp "labelThread#" GenPrimOp
1428 ThreadId# -> Addr# -> State# RealWorld -> State# RealWorld
1430 has_side_effects = True
1433 primop IsCurrentThreadBoundOp "isCurrentThreadBound#" GenPrimOp
1434 State# RealWorld -> (# State# RealWorld, Int# #)
1437 has_side_effects = True
1439 primop NoDuplicateOp "noDuplicate#" GenPrimOp
1440 State# RealWorld -> State# RealWorld
1443 has_side_effects = True
1445 primop ThreadStatusOp "threadStatus#" GenPrimOp
1446 ThreadId# -> State# RealWorld -> (# State# RealWorld, Int# #)
1449 has_side_effects = True
1451 ------------------------------------------------------------------------
1452 section "Weak pointers"
1453 ------------------------------------------------------------------------
1457 -- note that tyvar "o" denotes openAlphaTyVar
1459 primop MkWeakOp "mkWeak#" GenPrimOp
1460 o -> b -> c -> State# RealWorld -> (# State# RealWorld, Weak# b #)
1462 has_side_effects = True
1465 primop MkWeakForeignEnvOp "mkWeakForeignEnv#" GenPrimOp
1466 o -> b -> Addr# -> Addr# -> Int# -> Addr# -> State# RealWorld -> (# State# RealWorld, Weak# b #)
1468 has_side_effects = True
1471 primop DeRefWeakOp "deRefWeak#" GenPrimOp
1472 Weak# a -> State# RealWorld -> (# State# RealWorld, Int#, a #)
1474 has_side_effects = True
1477 primop FinalizeWeakOp "finalizeWeak#" GenPrimOp
1478 Weak# a -> State# RealWorld -> (# State# RealWorld, Int#,
1479 (State# RealWorld -> (# State# RealWorld, () #)) #)
1481 has_side_effects = True
1484 primop TouchOp "touch#" GenPrimOp
1485 o -> State# RealWorld -> State# RealWorld
1487 has_side_effects = True
1489 ------------------------------------------------------------------------
1490 section "Stable pointers and names"
1491 ------------------------------------------------------------------------
1493 primtype StablePtr# a
1495 primtype StableName# a
1497 primop MakeStablePtrOp "makeStablePtr#" GenPrimOp
1498 a -> State# RealWorld -> (# State# RealWorld, StablePtr# a #)
1500 has_side_effects = True
1503 primop DeRefStablePtrOp "deRefStablePtr#" GenPrimOp
1504 StablePtr# a -> State# RealWorld -> (# State# RealWorld, a #)
1506 needs_wrapper = True
1507 has_side_effects = True
1510 primop EqStablePtrOp "eqStablePtr#" GenPrimOp
1511 StablePtr# a -> StablePtr# a -> Int#
1513 has_side_effects = True
1515 primop MakeStableNameOp "makeStableName#" GenPrimOp
1516 a -> State# RealWorld -> (# State# RealWorld, StableName# a #)
1518 needs_wrapper = True
1519 has_side_effects = True
1522 primop EqStableNameOp "eqStableName#" GenPrimOp
1523 StableName# a -> StableName# a -> Int#
1525 primop StableNameToIntOp "stableNameToInt#" GenPrimOp
1526 StableName# a -> Int#
1528 ------------------------------------------------------------------------
1529 section "Unsafe pointer equality"
1530 -- (#1 Bad Guy: Alistair Reid :)
1531 ------------------------------------------------------------------------
1533 primop ReallyUnsafePtrEqualityOp "reallyUnsafePtrEquality#" GenPrimOp
1536 ------------------------------------------------------------------------
1537 section "Parallelism"
1538 ------------------------------------------------------------------------
1540 primop ParOp "par#" GenPrimOp
1543 -- Note that Par is lazy to avoid that the sparked thing
1544 -- gets evaluted strictly, which it should *not* be
1545 has_side_effects = True
1547 primop GetSparkOp "getSpark#" GenPrimOp
1548 State# s -> (# State# s, Int#, a #)
1550 has_side_effects = True
1553 -- HWL: The first 4 Int# in all par... annotations denote:
1554 -- name, granularity info, size of result, degree of parallelism
1555 -- Same structure as _seq_ i.e. returns Int#
1556 -- KSW: v, the second arg in parAt# and parAtForNow#, is used only to determine
1557 -- `the processor containing the expression v'; it is not evaluated
1559 primop ParGlobalOp "parGlobal#" GenPrimOp
1560 a -> Int# -> Int# -> Int# -> Int# -> b -> Int#
1562 has_side_effects = True
1564 primop ParLocalOp "parLocal#" GenPrimOp
1565 a -> Int# -> Int# -> Int# -> Int# -> b -> Int#
1567 has_side_effects = True
1569 primop ParAtOp "parAt#" GenPrimOp
1570 b -> a -> Int# -> Int# -> Int# -> Int# -> c -> Int#
1572 has_side_effects = True
1574 primop ParAtAbsOp "parAtAbs#" GenPrimOp
1575 a -> Int# -> Int# -> Int# -> Int# -> Int# -> b -> Int#
1577 has_side_effects = True
1579 primop ParAtRelOp "parAtRel#" GenPrimOp
1580 a -> Int# -> Int# -> Int# -> Int# -> Int# -> b -> Int#
1582 has_side_effects = True
1584 primop ParAtForNowOp "parAtForNow#" GenPrimOp
1585 b -> a -> Int# -> Int# -> Int# -> Int# -> c -> Int#
1587 has_side_effects = True
1589 -- copyable# and noFollow# are yet to be implemented (for GpH)
1591 --primop CopyableOp "copyable#" GenPrimOp
1594 -- has_side_effects = True
1596 --primop NoFollowOp "noFollow#" GenPrimOp
1599 -- has_side_effects = True
1602 ------------------------------------------------------------------------
1603 section "Tag to enum stuff"
1604 {Convert back and forth between values of enumerated types
1605 and small integers.}
1606 ------------------------------------------------------------------------
1608 primop DataToTagOp "dataToTag#" GenPrimOp
1611 strictness = { \ _arity -> mkStrictSig (mkTopDmdType [seqDmd] TopRes) }
1612 -- dataToTag# must have an evaluated argument
1614 primop TagToEnumOp "tagToEnum#" GenPrimOp
1617 ------------------------------------------------------------------------
1618 section "Bytecode operations"
1619 {Support for the bytecode interpreter and linker.}
1620 ------------------------------------------------------------------------
1623 {Primitive bytecode type.}
1625 primop AddrToHValueOp "addrToHValue#" GenPrimOp
1627 {Convert an {\tt Addr\#} to a followable type.}
1629 primop MkApUpd0_Op "mkApUpd0#" GenPrimOp
1634 primop NewBCOOp "newBCO#" GenPrimOp
1635 ByteArray# -> ByteArray# -> Array# a -> Int# -> ByteArray# -> State# s -> (# State# s, BCO# #)
1637 has_side_effects = True
1640 primop UnpackClosureOp "unpackClosure#" GenPrimOp
1641 a -> (# Addr#, Array# b, ByteArray# #)
1645 primop GetApStackValOp "getApStackVal#" GenPrimOp
1646 a -> Int# -> (# Int#, b #)
1650 ------------------------------------------------------------------------
1652 {These aren't nearly as wired in as Etc...}
1653 ------------------------------------------------------------------------
1655 primop TraceCcsOp "traceCcs#" GenPrimOp
1658 has_side_effects = True
1661 ------------------------------------------------------------------------
1663 {Miscellaneous built-ins}
1664 ------------------------------------------------------------------------
1668 { Evaluates its first argument to head normal form, and then returns its second
1669 argument as the result. }
1673 { The call {\tt (inline f)} arranges that f is inlined, regardless of its size.
1674 More precisely, the call {\tt (inline f)} rewrites to the right-hand side of
1675 {\tt f}'s definition. This allows the programmer to control inlining from a
1676 particular call site rather than the definition site of the function (c.f.
1677 {\tt INLINE} pragmas in User's Guide, Section 7.10.3, "INLINE and NOINLINE
1680 This inlining occurs regardless of the argument to the call or the size of
1681 {\tt f}'s definition; it is unconditional. The main caveat is that {\tt f}'s
1682 definition must be visible to the compiler. That is, {\tt f} must be
1683 {\tt let}-bound in the current scope. If no inlining takes place, the
1684 {\tt inline} function expands to the identity function in Phase zero; so its
1685 use imposes no overhead.
1687 If the function is defined in another module, GHC only exposes its inlining
1688 in the interface file if the function is sufficiently small that it might be
1689 inlined by the automatic mechanism. There is currently no way to tell GHC to
1690 expose arbitrarily-large functions in the interface file. (This shortcoming
1691 is something that could be fixed, with some kind of pragma.) }
1695 { The {\tt lazy} function restrains strictness analysis a little. The call
1696 {\tt (lazy e)} means the same as {\tt e}, but {\tt lazy} has a magical
1697 property so far as strictness analysis is concerned: it is lazy in its first
1698 argument, even though its semantics is strict. After strictness analysis has
1699 run, calls to {\tt lazy} are inlined to be the identity function.
1701 This behaviour is occasionally useful when controlling evaluation order.
1702 Notably, {\tt lazy} is used in the library definition of {\tt Control.Parallel.par}:
1704 {\tt par :: a -> b -> b}
1706 {\tt par x y = case (par\# x) of \_ -> lazy y}
1708 If {\tt lazy} were not lazy, {\tt par} would look strict in {\tt y} which
1709 would defeat the whole purpose of {\tt par}.
1711 Like {\tt seq}, the argument of {\tt lazy} can have an unboxed type. }
1714 { The type constructor {\tt Any} is type to which you can unsafely coerce any
1715 lifted type, and back.
1717 * It is lifted, and hence represented by a pointer
1719 * It does not claim to be a {\it data} type, and that's important for
1720 the code generator, because the code gen may {\it enter} a data value
1721 but never enters a function value.
1723 It's also used to instantiate un-constrained type variables after type
1724 checking. For example
1728 Annoyingly, we sometimes need {\tt Any}s of other kinds, such as {\tt (* -> *)} etc.
1729 This is a bit like tuples. We define a couple of useful ones here,
1730 and make others up on the fly. If any of these others end up being exported
1731 into interface files, we'll get a crash; at least until we add interface-file
1732 syntax to support them. }
1734 pseudoop "unsafeCoerce#"
1736 { The function {\tt unsafeCoerce\#} allows you to side-step the typechecker entirely. That
1737 is, it allows you to coerce any type into any other type. If you use this function,
1738 you had better get it right, otherwise segmentation faults await. It is generally
1739 used when you want to write a program that you know is well-typed, but where Haskell's
1740 type system is not expressive enough to prove that it is well typed.
1742 The following uses of {\tt unsafeCoerce\#} are supposed to work (i.e. not lead to
1743 spurious compile-time or run-time crashes):
1745 * Casting any lifted type to {\tt Any}
1747 * Casting {\tt Any} back to the real type
1749 * Casting an unboxed type to another unboxed type of the same size
1750 (but not coercions between floating-point and integral types)
1752 * Casting between two types that have the same runtime representation. One case is when
1753 the two types differ only in "phantom" type parameters, for example
1754 {\tt Ptr Int} to {\tt Ptr Float}, or {\tt [Int]} to {\tt [Float]} when the list is
1755 known to be empty. Also, a {\tt newtype} of a type {\tt T} has the same representation
1756 at runtime as {\tt T}.
1758 Other uses of {\tt unsafeCoerce\#} are undefined. In particular, you should not use
1759 {\tt unsafeCoerce\#} to cast a T to an algebraic data type D, unless T is also
1760 an algebraic data type. For example, do not cast {\tt Int->Int} to {\tt Bool}, even if
1761 you later cast that {\tt Bool} back to {\tt Int->Int} before applying it. The reasons
1762 have to do with GHC's internal representation details (for the congnoscenti, data values
1763 can be entered but function closures cannot). If you want a safe type to cast things
1764 to, use {\tt Any}, which is not an algebraic data type.
1768 -- NB. It is tempting to think that casting a value to a type that it doesn't have is safe
1769 -- as long as you don't "do anything" with the value in its cast form, such as seq on it. This
1770 -- isn't the case: the compiler can insert seqs itself, and if these happen at the wrong type,
1771 -- Bad Things Might Happen. See bug #1616: in this case we cast a function of type (a,b) -> (a,b)
1772 -- to () -> () and back again. The strictness analyser saw that the function was strict, but
1773 -- the wrapper had type () -> (), and hence the wrapper de-constructed the (), the worker re-constructed
1774 -- a new (), with the result that the code ended up with "case () of (a,b) -> ...".
1776 primop TraceEventOp "traceEvent#" GenPrimOp
1777 Addr# -> State# s -> State# s
1778 { Emits an event via the RTS tracing framework. The contents
1779 of the event is the zero-terminated byte string passed as the first
1780 argument. The event will be emitted either to the .eventlog file,
1781 or to stderr, depending on the runtime RTS flags. }
1783 has_side_effects = True
1786 ------------------------------------------------------------------------
1788 ------------------------------------------------------------------------