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 scanned
636 for pointers. It carries its own size (in bytes). There are
637 three sets of operations for accessing byte array contents:
638 index for reading from immutable byte arrays, and read/write
639 for mutable byte arrays. Each set contains operations for
640 a range of useful primitive data types. Each operation takes
641 an offset measured in terms of the size fo the primitive type
642 being read or written.}
644 ------------------------------------------------------------------------
648 primtype MutableByteArray# s
650 primop NewByteArrayOp_Char "newByteArray#" GenPrimOp
651 Int# -> State# s -> (# State# s, MutableByteArray# s #)
652 {Create a new mutable byte array of specified size (in bytes), in
653 the specified state thread.}
654 with out_of_line = True
655 has_side_effects = True
657 primop NewPinnedByteArrayOp_Char "newPinnedByteArray#" GenPrimOp
658 Int# -> State# s -> (# State# s, MutableByteArray# s #)
659 {Create a mutable byte array that the GC guarantees not to move.}
660 with out_of_line = True
661 has_side_effects = True
663 primop NewAlignedPinnedByteArrayOp_Char "newAlignedPinnedByteArray#" GenPrimOp
664 Int# -> Int# -> State# s -> (# State# s, MutableByteArray# s #)
665 {Create a mutable byte array, aligned by the specified amount, that the GC guarantees not to move.}
666 with out_of_line = True
667 has_side_effects = True
669 primop ByteArrayContents_Char "byteArrayContents#" GenPrimOp
671 {Intended for use with pinned arrays; otherwise very unsafe!}
673 primop SameMutableByteArrayOp "sameMutableByteArray#" GenPrimOp
674 MutableByteArray# s -> MutableByteArray# s -> Bool
676 primop UnsafeFreezeByteArrayOp "unsafeFreezeByteArray#" GenPrimOp
677 MutableByteArray# s -> State# s -> (# State# s, ByteArray# #)
678 {Make a mutable byte array immutable, without copying.}
680 has_side_effects = True
682 primop SizeofByteArrayOp "sizeofByteArray#" GenPrimOp
685 primop SizeofMutableByteArrayOp "sizeofMutableByteArray#" GenPrimOp
686 MutableByteArray# s -> Int#
689 primop IndexByteArrayOp_Char "indexCharArray#" GenPrimOp
690 ByteArray# -> Int# -> Char#
691 {Read 8-bit character; offset in bytes.}
693 primop IndexByteArrayOp_WideChar "indexWideCharArray#" GenPrimOp
694 ByteArray# -> Int# -> Char#
695 {Read 31-bit character; offset in 4-byte words.}
697 primop IndexByteArrayOp_Int "indexIntArray#" GenPrimOp
698 ByteArray# -> Int# -> Int#
700 primop IndexByteArrayOp_Word "indexWordArray#" GenPrimOp
701 ByteArray# -> Int# -> Word#
703 primop IndexByteArrayOp_Addr "indexAddrArray#" GenPrimOp
704 ByteArray# -> Int# -> Addr#
706 primop IndexByteArrayOp_Float "indexFloatArray#" GenPrimOp
707 ByteArray# -> Int# -> Float#
709 primop IndexByteArrayOp_Double "indexDoubleArray#" GenPrimOp
710 ByteArray# -> Int# -> Double#
712 primop IndexByteArrayOp_StablePtr "indexStablePtrArray#" GenPrimOp
713 ByteArray# -> Int# -> StablePtr# a
715 primop IndexByteArrayOp_Int8 "indexInt8Array#" GenPrimOp
716 ByteArray# -> Int# -> Int#
718 primop IndexByteArrayOp_Int16 "indexInt16Array#" GenPrimOp
719 ByteArray# -> Int# -> Int#
721 primop IndexByteArrayOp_Int32 "indexInt32Array#" GenPrimOp
722 ByteArray# -> Int# -> INT32
724 primop IndexByteArrayOp_Int64 "indexInt64Array#" GenPrimOp
725 ByteArray# -> Int# -> INT64
727 primop IndexByteArrayOp_Word8 "indexWord8Array#" GenPrimOp
728 ByteArray# -> Int# -> Word#
730 primop IndexByteArrayOp_Word16 "indexWord16Array#" GenPrimOp
731 ByteArray# -> Int# -> Word#
733 primop IndexByteArrayOp_Word32 "indexWord32Array#" GenPrimOp
734 ByteArray# -> Int# -> WORD32
736 primop IndexByteArrayOp_Word64 "indexWord64Array#" GenPrimOp
737 ByteArray# -> Int# -> WORD64
739 primop ReadByteArrayOp_Char "readCharArray#" GenPrimOp
740 MutableByteArray# s -> Int# -> State# s -> (# State# s, Char# #)
741 {Read 8-bit character; offset in bytes.}
742 with has_side_effects = True
744 primop ReadByteArrayOp_WideChar "readWideCharArray#" GenPrimOp
745 MutableByteArray# s -> Int# -> State# s -> (# State# s, Char# #)
746 {Read 31-bit character; offset in 4-byte words.}
747 with has_side_effects = True
749 primop ReadByteArrayOp_Int "readIntArray#" GenPrimOp
750 MutableByteArray# s -> Int# -> State# s -> (# State# s, Int# #)
751 with has_side_effects = True
753 primop ReadByteArrayOp_Word "readWordArray#" GenPrimOp
754 MutableByteArray# s -> Int# -> State# s -> (# State# s, Word# #)
755 with has_side_effects = True
757 primop ReadByteArrayOp_Addr "readAddrArray#" GenPrimOp
758 MutableByteArray# s -> Int# -> State# s -> (# State# s, Addr# #)
759 with has_side_effects = True
761 primop ReadByteArrayOp_Float "readFloatArray#" GenPrimOp
762 MutableByteArray# s -> Int# -> State# s -> (# State# s, Float# #)
763 with has_side_effects = True
765 primop ReadByteArrayOp_Double "readDoubleArray#" GenPrimOp
766 MutableByteArray# s -> Int# -> State# s -> (# State# s, Double# #)
767 with has_side_effects = True
769 primop ReadByteArrayOp_StablePtr "readStablePtrArray#" GenPrimOp
770 MutableByteArray# s -> Int# -> State# s -> (# State# s, StablePtr# a #)
771 with has_side_effects = True
773 primop ReadByteArrayOp_Int8 "readInt8Array#" GenPrimOp
774 MutableByteArray# s -> Int# -> State# s -> (# State# s, Int# #)
775 with has_side_effects = True
777 primop ReadByteArrayOp_Int16 "readInt16Array#" GenPrimOp
778 MutableByteArray# s -> Int# -> State# s -> (# State# s, Int# #)
779 with has_side_effects = True
781 primop ReadByteArrayOp_Int32 "readInt32Array#" GenPrimOp
782 MutableByteArray# s -> Int# -> State# s -> (# State# s, INT32 #)
783 with has_side_effects = True
785 primop ReadByteArrayOp_Int64 "readInt64Array#" GenPrimOp
786 MutableByteArray# s -> Int# -> State# s -> (# State# s, INT64 #)
787 with has_side_effects = True
789 primop ReadByteArrayOp_Word8 "readWord8Array#" GenPrimOp
790 MutableByteArray# s -> Int# -> State# s -> (# State# s, Word# #)
791 with has_side_effects = True
793 primop ReadByteArrayOp_Word16 "readWord16Array#" GenPrimOp
794 MutableByteArray# s -> Int# -> State# s -> (# State# s, Word# #)
795 with has_side_effects = True
797 primop ReadByteArrayOp_Word32 "readWord32Array#" GenPrimOp
798 MutableByteArray# s -> Int# -> State# s -> (# State# s, WORD32 #)
799 with has_side_effects = True
801 primop ReadByteArrayOp_Word64 "readWord64Array#" GenPrimOp
802 MutableByteArray# s -> Int# -> State# s -> (# State# s, WORD64 #)
803 with has_side_effects = True
805 primop WriteByteArrayOp_Char "writeCharArray#" GenPrimOp
806 MutableByteArray# s -> Int# -> Char# -> State# s -> State# s
807 {Write 8-bit character; offset in bytes.}
808 with has_side_effects = True
810 primop WriteByteArrayOp_WideChar "writeWideCharArray#" GenPrimOp
811 MutableByteArray# s -> Int# -> Char# -> State# s -> State# s
812 {Write 31-bit character; offset in 4-byte words.}
813 with has_side_effects = True
815 primop WriteByteArrayOp_Int "writeIntArray#" GenPrimOp
816 MutableByteArray# s -> Int# -> Int# -> State# s -> State# s
817 with has_side_effects = True
819 primop WriteByteArrayOp_Word "writeWordArray#" GenPrimOp
820 MutableByteArray# s -> Int# -> Word# -> State# s -> State# s
821 with has_side_effects = True
823 primop WriteByteArrayOp_Addr "writeAddrArray#" GenPrimOp
824 MutableByteArray# s -> Int# -> Addr# -> State# s -> State# s
825 with has_side_effects = True
827 primop WriteByteArrayOp_Float "writeFloatArray#" GenPrimOp
828 MutableByteArray# s -> Int# -> Float# -> State# s -> State# s
829 with has_side_effects = True
831 primop WriteByteArrayOp_Double "writeDoubleArray#" GenPrimOp
832 MutableByteArray# s -> Int# -> Double# -> State# s -> State# s
833 with has_side_effects = True
835 primop WriteByteArrayOp_StablePtr "writeStablePtrArray#" GenPrimOp
836 MutableByteArray# s -> Int# -> StablePtr# a -> State# s -> State# s
837 with has_side_effects = True
839 primop WriteByteArrayOp_Int8 "writeInt8Array#" GenPrimOp
840 MutableByteArray# s -> Int# -> Int# -> State# s -> State# s
841 with has_side_effects = True
843 primop WriteByteArrayOp_Int16 "writeInt16Array#" GenPrimOp
844 MutableByteArray# s -> Int# -> Int# -> State# s -> State# s
845 with has_side_effects = True
847 primop WriteByteArrayOp_Int32 "writeInt32Array#" GenPrimOp
848 MutableByteArray# s -> Int# -> INT32 -> State# s -> State# s
849 with has_side_effects = True
851 primop WriteByteArrayOp_Int64 "writeInt64Array#" GenPrimOp
852 MutableByteArray# s -> Int# -> INT64 -> State# s -> State# s
853 with has_side_effects = True
855 primop WriteByteArrayOp_Word8 "writeWord8Array#" GenPrimOp
856 MutableByteArray# s -> Int# -> Word# -> State# s -> State# s
857 with has_side_effects = True
859 primop WriteByteArrayOp_Word16 "writeWord16Array#" GenPrimOp
860 MutableByteArray# s -> Int# -> Word# -> State# s -> State# s
861 with has_side_effects = True
863 primop WriteByteArrayOp_Word32 "writeWord32Array#" GenPrimOp
864 MutableByteArray# s -> Int# -> WORD32 -> State# s -> State# s
865 with has_side_effects = True
867 primop WriteByteArrayOp_Word64 "writeWord64Array#" GenPrimOp
868 MutableByteArray# s -> Int# -> WORD64 -> State# s -> State# s
869 with has_side_effects = True
871 ------------------------------------------------------------------------
873 ------------------------------------------------------------------------
876 { An arbitrary machine address assumed to point outside
877 the garbage-collected heap. }
879 pseudoop "nullAddr#" Addr#
880 { The null address. }
882 primop AddrAddOp "plusAddr#" GenPrimOp Addr# -> Int# -> Addr#
883 primop AddrSubOp "minusAddr#" GenPrimOp Addr# -> Addr# -> Int#
884 {Result is meaningless if two {\tt Addr\#}s are so far apart that their
885 difference doesn't fit in an {\tt Int\#}.}
886 primop AddrRemOp "remAddr#" GenPrimOp Addr# -> Int# -> Int#
887 {Return the remainder when the {\tt Addr\#} arg, treated like an {\tt Int\#},
888 is divided by the {\tt Int\#} arg.}
889 #if (WORD_SIZE_IN_BITS == 32 || WORD_SIZE_IN_BITS == 64)
890 primop Addr2IntOp "addr2Int#" GenPrimOp Addr# -> Int#
891 {Coerce directly from address to int. Strongly deprecated.}
892 primop Int2AddrOp "int2Addr#" GenPrimOp Int# -> Addr#
893 {Coerce directly from int to address. Strongly deprecated.}
896 primop AddrGtOp "gtAddr#" Compare Addr# -> Addr# -> Bool
897 primop AddrGeOp "geAddr#" Compare Addr# -> Addr# -> Bool
898 primop AddrEqOp "eqAddr#" Compare Addr# -> Addr# -> Bool
899 primop AddrNeOp "neAddr#" Compare Addr# -> Addr# -> Bool
900 primop AddrLtOp "ltAddr#" Compare Addr# -> Addr# -> Bool
901 primop AddrLeOp "leAddr#" Compare Addr# -> Addr# -> Bool
903 primop IndexOffAddrOp_Char "indexCharOffAddr#" GenPrimOp
904 Addr# -> Int# -> Char#
905 {Reads 8-bit character; offset in bytes.}
907 primop IndexOffAddrOp_WideChar "indexWideCharOffAddr#" GenPrimOp
908 Addr# -> Int# -> Char#
909 {Reads 31-bit character; offset in 4-byte words.}
911 primop IndexOffAddrOp_Int "indexIntOffAddr#" GenPrimOp
912 Addr# -> Int# -> Int#
914 primop IndexOffAddrOp_Word "indexWordOffAddr#" GenPrimOp
915 Addr# -> Int# -> Word#
917 primop IndexOffAddrOp_Addr "indexAddrOffAddr#" GenPrimOp
918 Addr# -> Int# -> Addr#
920 primop IndexOffAddrOp_Float "indexFloatOffAddr#" GenPrimOp
921 Addr# -> Int# -> Float#
923 primop IndexOffAddrOp_Double "indexDoubleOffAddr#" GenPrimOp
924 Addr# -> Int# -> Double#
926 primop IndexOffAddrOp_StablePtr "indexStablePtrOffAddr#" GenPrimOp
927 Addr# -> Int# -> StablePtr# a
929 primop IndexOffAddrOp_Int8 "indexInt8OffAddr#" GenPrimOp
930 Addr# -> Int# -> Int#
932 primop IndexOffAddrOp_Int16 "indexInt16OffAddr#" GenPrimOp
933 Addr# -> Int# -> Int#
935 primop IndexOffAddrOp_Int32 "indexInt32OffAddr#" GenPrimOp
936 Addr# -> Int# -> INT32
938 primop IndexOffAddrOp_Int64 "indexInt64OffAddr#" GenPrimOp
939 Addr# -> Int# -> INT64
941 primop IndexOffAddrOp_Word8 "indexWord8OffAddr#" GenPrimOp
942 Addr# -> Int# -> Word#
944 primop IndexOffAddrOp_Word16 "indexWord16OffAddr#" GenPrimOp
945 Addr# -> Int# -> Word#
947 primop IndexOffAddrOp_Word32 "indexWord32OffAddr#" GenPrimOp
948 Addr# -> Int# -> WORD32
950 primop IndexOffAddrOp_Word64 "indexWord64OffAddr#" GenPrimOp
951 Addr# -> Int# -> WORD64
953 primop ReadOffAddrOp_Char "readCharOffAddr#" GenPrimOp
954 Addr# -> Int# -> State# s -> (# State# s, Char# #)
955 {Reads 8-bit character; offset in bytes.}
956 with has_side_effects = True
958 primop ReadOffAddrOp_WideChar "readWideCharOffAddr#" GenPrimOp
959 Addr# -> Int# -> State# s -> (# State# s, Char# #)
960 {Reads 31-bit character; offset in 4-byte words.}
961 with has_side_effects = True
963 primop ReadOffAddrOp_Int "readIntOffAddr#" GenPrimOp
964 Addr# -> Int# -> State# s -> (# State# s, Int# #)
965 with has_side_effects = True
967 primop ReadOffAddrOp_Word "readWordOffAddr#" GenPrimOp
968 Addr# -> Int# -> State# s -> (# State# s, Word# #)
969 with has_side_effects = True
971 primop ReadOffAddrOp_Addr "readAddrOffAddr#" GenPrimOp
972 Addr# -> Int# -> State# s -> (# State# s, Addr# #)
973 with has_side_effects = True
975 primop ReadOffAddrOp_Float "readFloatOffAddr#" GenPrimOp
976 Addr# -> Int# -> State# s -> (# State# s, Float# #)
977 with has_side_effects = True
979 primop ReadOffAddrOp_Double "readDoubleOffAddr#" GenPrimOp
980 Addr# -> Int# -> State# s -> (# State# s, Double# #)
981 with has_side_effects = True
983 primop ReadOffAddrOp_StablePtr "readStablePtrOffAddr#" GenPrimOp
984 Addr# -> Int# -> State# s -> (# State# s, StablePtr# a #)
985 with has_side_effects = True
987 primop ReadOffAddrOp_Int8 "readInt8OffAddr#" GenPrimOp
988 Addr# -> Int# -> State# s -> (# State# s, Int# #)
989 with has_side_effects = True
991 primop ReadOffAddrOp_Int16 "readInt16OffAddr#" GenPrimOp
992 Addr# -> Int# -> State# s -> (# State# s, Int# #)
993 with has_side_effects = True
995 primop ReadOffAddrOp_Int32 "readInt32OffAddr#" GenPrimOp
996 Addr# -> Int# -> State# s -> (# State# s, INT32 #)
997 with has_side_effects = True
999 primop ReadOffAddrOp_Int64 "readInt64OffAddr#" GenPrimOp
1000 Addr# -> Int# -> State# s -> (# State# s, INT64 #)
1001 with has_side_effects = True
1003 primop ReadOffAddrOp_Word8 "readWord8OffAddr#" GenPrimOp
1004 Addr# -> Int# -> State# s -> (# State# s, Word# #)
1005 with has_side_effects = True
1007 primop ReadOffAddrOp_Word16 "readWord16OffAddr#" GenPrimOp
1008 Addr# -> Int# -> State# s -> (# State# s, Word# #)
1009 with has_side_effects = True
1011 primop ReadOffAddrOp_Word32 "readWord32OffAddr#" GenPrimOp
1012 Addr# -> Int# -> State# s -> (# State# s, WORD32 #)
1013 with has_side_effects = True
1015 primop ReadOffAddrOp_Word64 "readWord64OffAddr#" GenPrimOp
1016 Addr# -> Int# -> State# s -> (# State# s, WORD64 #)
1017 with has_side_effects = True
1020 primop WriteOffAddrOp_Char "writeCharOffAddr#" GenPrimOp
1021 Addr# -> Int# -> Char# -> State# s -> State# s
1022 with has_side_effects = True
1024 primop WriteOffAddrOp_WideChar "writeWideCharOffAddr#" GenPrimOp
1025 Addr# -> Int# -> Char# -> State# s -> State# s
1026 with has_side_effects = True
1028 primop WriteOffAddrOp_Int "writeIntOffAddr#" GenPrimOp
1029 Addr# -> Int# -> Int# -> State# s -> State# s
1030 with has_side_effects = True
1032 primop WriteOffAddrOp_Word "writeWordOffAddr#" GenPrimOp
1033 Addr# -> Int# -> Word# -> State# s -> State# s
1034 with has_side_effects = True
1036 primop WriteOffAddrOp_Addr "writeAddrOffAddr#" GenPrimOp
1037 Addr# -> Int# -> Addr# -> State# s -> State# s
1038 with has_side_effects = True
1040 primop WriteOffAddrOp_Float "writeFloatOffAddr#" GenPrimOp
1041 Addr# -> Int# -> Float# -> State# s -> State# s
1042 with has_side_effects = True
1044 primop WriteOffAddrOp_Double "writeDoubleOffAddr#" GenPrimOp
1045 Addr# -> Int# -> Double# -> State# s -> State# s
1046 with has_side_effects = True
1048 primop WriteOffAddrOp_StablePtr "writeStablePtrOffAddr#" GenPrimOp
1049 Addr# -> Int# -> StablePtr# a -> State# s -> State# s
1050 with has_side_effects = True
1052 primop WriteOffAddrOp_Int8 "writeInt8OffAddr#" GenPrimOp
1053 Addr# -> Int# -> Int# -> State# s -> State# s
1054 with has_side_effects = True
1056 primop WriteOffAddrOp_Int16 "writeInt16OffAddr#" GenPrimOp
1057 Addr# -> Int# -> Int# -> State# s -> State# s
1058 with has_side_effects = True
1060 primop WriteOffAddrOp_Int32 "writeInt32OffAddr#" GenPrimOp
1061 Addr# -> Int# -> INT32 -> State# s -> State# s
1062 with has_side_effects = True
1064 primop WriteOffAddrOp_Int64 "writeInt64OffAddr#" GenPrimOp
1065 Addr# -> Int# -> INT64 -> State# s -> State# s
1066 with has_side_effects = True
1068 primop WriteOffAddrOp_Word8 "writeWord8OffAddr#" GenPrimOp
1069 Addr# -> Int# -> Word# -> State# s -> State# s
1070 with has_side_effects = True
1072 primop WriteOffAddrOp_Word16 "writeWord16OffAddr#" GenPrimOp
1073 Addr# -> Int# -> Word# -> State# s -> State# s
1074 with has_side_effects = True
1076 primop WriteOffAddrOp_Word32 "writeWord32OffAddr#" GenPrimOp
1077 Addr# -> Int# -> WORD32 -> State# s -> State# s
1078 with has_side_effects = True
1080 primop WriteOffAddrOp_Word64 "writeWord64OffAddr#" GenPrimOp
1081 Addr# -> Int# -> WORD64 -> State# s -> State# s
1082 with has_side_effects = True
1084 ------------------------------------------------------------------------
1085 section "Mutable variables"
1086 {Operations on MutVar\#s.}
1087 ------------------------------------------------------------------------
1089 primtype MutVar# s a
1090 {A {\tt MutVar\#} behaves like a single-element mutable array.}
1092 primop NewMutVarOp "newMutVar#" GenPrimOp
1093 a -> State# s -> (# State# s, MutVar# s a #)
1094 {Create {\tt MutVar\#} with specified initial value in specified state thread.}
1097 has_side_effects = True
1099 primop ReadMutVarOp "readMutVar#" GenPrimOp
1100 MutVar# s a -> State# s -> (# State# s, a #)
1101 {Read contents of {\tt MutVar\#}. Result is not yet evaluated.}
1103 has_side_effects = True
1105 primop WriteMutVarOp "writeMutVar#" GenPrimOp
1106 MutVar# s a -> a -> State# s -> State# s
1107 {Write contents of {\tt MutVar\#}.}
1109 has_side_effects = True
1111 primop SameMutVarOp "sameMutVar#" GenPrimOp
1112 MutVar# s a -> MutVar# s a -> Bool
1114 -- not really the right type, but we don't know about pairs here. The
1117 -- MutVar# s a -> (a -> (a,b)) -> State# s -> (# State# s, b #)
1119 primop AtomicModifyMutVarOp "atomicModifyMutVar#" GenPrimOp
1120 MutVar# s a -> (a -> b) -> State# s -> (# State# s, c #)
1123 has_side_effects = True
1125 ------------------------------------------------------------------------
1126 section "Exceptions"
1127 ------------------------------------------------------------------------
1129 primop CatchOp "catch#" GenPrimOp
1130 (State# RealWorld -> (# State# RealWorld, a #) )
1131 -> (b -> State# RealWorld -> (# State# RealWorld, a #) )
1133 -> (# State# RealWorld, a #)
1135 -- Catch is actually strict in its first argument
1136 -- but we don't want to tell the strictness
1137 -- analyser about that!
1138 -- might use caught action multiply
1140 has_side_effects = True
1142 primop RaiseOp "raise#" GenPrimOp
1145 strictness = { \ _arity -> mkStrictSig (mkTopDmdType [lazyDmd] BotRes) }
1146 -- NB: result is bottom
1149 -- raiseIO# needs to be a primop, because exceptions in the IO monad
1150 -- must be *precise* - we don't want the strictness analyser turning
1151 -- one kind of bottom into another, as it is allowed to do in pure code.
1153 primop RaiseIOOp "raiseIO#" GenPrimOp
1154 a -> State# RealWorld -> (# State# RealWorld, b #)
1157 has_side_effects = True
1159 primop BlockAsyncExceptionsOp "blockAsyncExceptions#" GenPrimOp
1160 (State# RealWorld -> (# State# RealWorld, a #))
1161 -> (State# RealWorld -> (# State# RealWorld, a #))
1164 has_side_effects = True
1166 primop UnblockAsyncExceptionsOp "unblockAsyncExceptions#" GenPrimOp
1167 (State# RealWorld -> (# State# RealWorld, a #))
1168 -> (State# RealWorld -> (# State# RealWorld, a #))
1171 has_side_effects = True
1173 primop AsyncExceptionsBlockedOp "asyncExceptionsBlocked#" GenPrimOp
1174 State# RealWorld -> (# State# RealWorld, Int# #)
1177 has_side_effects = True
1179 ------------------------------------------------------------------------
1180 section "STM-accessible Mutable Variables"
1181 ------------------------------------------------------------------------
1185 primop AtomicallyOp "atomically#" GenPrimOp
1186 (State# RealWorld -> (# State# RealWorld, a #) )
1187 -> State# RealWorld -> (# State# RealWorld, a #)
1190 has_side_effects = True
1192 primop RetryOp "retry#" GenPrimOp
1193 State# RealWorld -> (# State# RealWorld, a #)
1196 has_side_effects = True
1198 primop CatchRetryOp "catchRetry#" GenPrimOp
1199 (State# RealWorld -> (# State# RealWorld, a #) )
1200 -> (State# RealWorld -> (# State# RealWorld, a #) )
1201 -> (State# RealWorld -> (# State# RealWorld, a #) )
1204 has_side_effects = True
1206 primop CatchSTMOp "catchSTM#" GenPrimOp
1207 (State# RealWorld -> (# State# RealWorld, a #) )
1208 -> (b -> State# RealWorld -> (# State# RealWorld, a #) )
1209 -> (State# RealWorld -> (# State# RealWorld, a #) )
1212 has_side_effects = True
1214 primop Check "check#" GenPrimOp
1215 (State# RealWorld -> (# State# RealWorld, a #) )
1216 -> (State# RealWorld -> (# State# RealWorld, () #) )
1219 has_side_effects = True
1221 primop NewTVarOp "newTVar#" GenPrimOp
1223 -> State# s -> (# State# s, TVar# s a #)
1224 {Create a new {\tt TVar\#} holding a specified initial value.}
1227 has_side_effects = True
1229 primop ReadTVarOp "readTVar#" GenPrimOp
1231 -> State# s -> (# State# s, a #)
1232 {Read contents of {\tt TVar\#}. Result is not yet evaluated.}
1235 has_side_effects = True
1237 primop ReadTVarIOOp "readTVarIO#" GenPrimOp
1239 -> State# s -> (# State# s, a #)
1240 {Read contents of {\tt TVar\#} outside an STM transaction}
1243 has_side_effects = True
1245 primop WriteTVarOp "writeTVar#" GenPrimOp
1248 -> State# s -> State# s
1249 {Write contents of {\tt TVar\#}.}
1252 has_side_effects = True
1254 primop SameTVarOp "sameTVar#" GenPrimOp
1255 TVar# s a -> TVar# s a -> Bool
1258 ------------------------------------------------------------------------
1259 section "Synchronized Mutable Variables"
1260 {Operations on {\tt MVar\#}s. }
1261 ------------------------------------------------------------------------
1264 { A shared mutable variable ({\it not} the same as a {\tt MutVar\#}!).
1265 (Note: in a non-concurrent implementation, {\tt (MVar\# a)} can be
1266 represented by {\tt (MutVar\# (Maybe a))}.) }
1268 primop NewMVarOp "newMVar#" GenPrimOp
1269 State# s -> (# State# s, MVar# s a #)
1270 {Create new {\tt MVar\#}; initially empty.}
1273 has_side_effects = True
1275 primop TakeMVarOp "takeMVar#" GenPrimOp
1276 MVar# s a -> State# s -> (# State# s, a #)
1277 {If {\tt MVar\#} is empty, block until it becomes full.
1278 Then remove and return its contents, and set it empty.}
1281 has_side_effects = True
1283 primop TryTakeMVarOp "tryTakeMVar#" GenPrimOp
1284 MVar# s a -> State# s -> (# State# s, Int#, a #)
1285 {If {\tt MVar\#} is empty, immediately return with integer 0 and value undefined.
1286 Otherwise, return with integer 1 and contents of {\tt MVar\#}, and set {\tt MVar\#} empty.}
1289 has_side_effects = True
1291 primop PutMVarOp "putMVar#" GenPrimOp
1292 MVar# s a -> a -> State# s -> State# s
1293 {If {\tt MVar\#} is full, block until it becomes empty.
1294 Then store value arg as its new contents.}
1297 has_side_effects = True
1299 primop TryPutMVarOp "tryPutMVar#" GenPrimOp
1300 MVar# s a -> a -> State# s -> (# State# s, Int# #)
1301 {If {\tt MVar\#} is full, immediately return with integer 0.
1302 Otherwise, store value arg as {\tt MVar\#}'s new contents, and return with integer 1.}
1305 has_side_effects = True
1307 primop SameMVarOp "sameMVar#" GenPrimOp
1308 MVar# s a -> MVar# s a -> Bool
1310 primop IsEmptyMVarOp "isEmptyMVar#" GenPrimOp
1311 MVar# s a -> State# s -> (# State# s, Int# #)
1312 {Return 1 if {\tt MVar\#} is empty; 0 otherwise.}
1315 has_side_effects = True
1317 ------------------------------------------------------------------------
1318 section "Delay/wait operations"
1319 ------------------------------------------------------------------------
1321 primop DelayOp "delay#" GenPrimOp
1322 Int# -> State# s -> State# s
1323 {Sleep specified number of microseconds.}
1325 needs_wrapper = True
1326 has_side_effects = True
1329 primop WaitReadOp "waitRead#" GenPrimOp
1330 Int# -> State# s -> State# s
1331 {Block until input is available on specified file descriptor.}
1333 needs_wrapper = True
1334 has_side_effects = True
1337 primop WaitWriteOp "waitWrite#" GenPrimOp
1338 Int# -> State# s -> State# s
1339 {Block until output is possible on specified file descriptor.}
1341 needs_wrapper = True
1342 has_side_effects = True
1345 #ifdef mingw32_TARGET_OS
1346 primop AsyncReadOp "asyncRead#" GenPrimOp
1347 Int# -> Int# -> Int# -> Addr# -> State# RealWorld-> (# State# RealWorld, Int#, Int# #)
1348 {Asynchronously read bytes from specified file descriptor.}
1350 needs_wrapper = True
1351 has_side_effects = True
1354 primop AsyncWriteOp "asyncWrite#" GenPrimOp
1355 Int# -> Int# -> Int# -> Addr# -> State# RealWorld-> (# State# RealWorld, Int#, Int# #)
1356 {Asynchronously write bytes from specified file descriptor.}
1358 needs_wrapper = True
1359 has_side_effects = True
1362 primop AsyncDoProcOp "asyncDoProc#" GenPrimOp
1363 Addr# -> Addr# -> State# RealWorld-> (# State# RealWorld, Int#, Int# #)
1364 {Asynchronously perform procedure (first arg), passing it 2nd arg.}
1366 needs_wrapper = True
1367 has_side_effects = True
1372 ------------------------------------------------------------------------
1373 section "Concurrency primitives"
1374 ------------------------------------------------------------------------
1377 { {\tt State\#} is the primitive, unlifted type of states. It has
1378 one type parameter, thus {\tt State\# RealWorld}, or {\tt State\# s},
1379 where s is a type variable. The only purpose of the type parameter
1380 is to keep different state threads separate. It is represented by
1384 { {\tt RealWorld} is deeply magical. It is {\it primitive}, but it is not
1385 {\it unlifted} (hence {\tt ptrArg}). We never manipulate values of type
1386 {\tt RealWorld}; it's only used in the type system, to parameterise {\tt State\#}. }
1389 {(In a non-concurrent implementation, this can be a singleton
1390 type, whose (unique) value is returned by {\tt myThreadId\#}. The
1391 other operations can be omitted.)}
1393 primop ForkOp "fork#" GenPrimOp
1394 a -> State# RealWorld -> (# State# RealWorld, ThreadId# #)
1396 has_side_effects = True
1399 primop ForkOnOp "forkOn#" GenPrimOp
1400 Int# -> a -> State# RealWorld -> (# State# RealWorld, ThreadId# #)
1402 has_side_effects = True
1405 primop KillThreadOp "killThread#" GenPrimOp
1406 ThreadId# -> a -> State# RealWorld -> State# RealWorld
1408 has_side_effects = True
1411 primop YieldOp "yield#" GenPrimOp
1412 State# RealWorld -> State# RealWorld
1414 has_side_effects = True
1417 primop MyThreadIdOp "myThreadId#" GenPrimOp
1418 State# RealWorld -> (# State# RealWorld, ThreadId# #)
1421 has_side_effects = True
1423 primop LabelThreadOp "labelThread#" GenPrimOp
1424 ThreadId# -> Addr# -> State# RealWorld -> State# RealWorld
1426 has_side_effects = True
1429 primop IsCurrentThreadBoundOp "isCurrentThreadBound#" GenPrimOp
1430 State# RealWorld -> (# State# RealWorld, Int# #)
1433 has_side_effects = True
1435 primop NoDuplicateOp "noDuplicate#" GenPrimOp
1436 State# RealWorld -> State# RealWorld
1439 has_side_effects = True
1441 primop ThreadStatusOp "threadStatus#" GenPrimOp
1442 ThreadId# -> State# RealWorld -> (# State# RealWorld, Int# #)
1445 has_side_effects = True
1447 ------------------------------------------------------------------------
1448 section "Weak pointers"
1449 ------------------------------------------------------------------------
1453 -- note that tyvar "o" denotes openAlphaTyVar
1455 primop MkWeakOp "mkWeak#" GenPrimOp
1456 o -> b -> c -> State# RealWorld -> (# State# RealWorld, Weak# b #)
1458 has_side_effects = True
1461 primop MkWeakForeignEnvOp "mkWeakForeignEnv#" GenPrimOp
1462 o -> b -> Addr# -> Addr# -> Int# -> Addr# -> State# RealWorld -> (# State# RealWorld, Weak# b #)
1464 has_side_effects = True
1467 primop DeRefWeakOp "deRefWeak#" GenPrimOp
1468 Weak# a -> State# RealWorld -> (# State# RealWorld, Int#, a #)
1470 has_side_effects = True
1473 primop FinalizeWeakOp "finalizeWeak#" GenPrimOp
1474 Weak# a -> State# RealWorld -> (# State# RealWorld, Int#,
1475 (State# RealWorld -> (# State# RealWorld, () #)) #)
1477 has_side_effects = True
1480 primop TouchOp "touch#" GenPrimOp
1481 o -> State# RealWorld -> State# RealWorld
1483 has_side_effects = True
1485 ------------------------------------------------------------------------
1486 section "Stable pointers and names"
1487 ------------------------------------------------------------------------
1489 primtype StablePtr# a
1491 primtype StableName# a
1493 primop MakeStablePtrOp "makeStablePtr#" GenPrimOp
1494 a -> State# RealWorld -> (# State# RealWorld, StablePtr# a #)
1496 has_side_effects = True
1499 primop DeRefStablePtrOp "deRefStablePtr#" GenPrimOp
1500 StablePtr# a -> State# RealWorld -> (# State# RealWorld, a #)
1502 needs_wrapper = True
1503 has_side_effects = True
1506 primop EqStablePtrOp "eqStablePtr#" GenPrimOp
1507 StablePtr# a -> StablePtr# a -> Int#
1509 has_side_effects = True
1511 primop MakeStableNameOp "makeStableName#" GenPrimOp
1512 a -> State# RealWorld -> (# State# RealWorld, StableName# a #)
1514 needs_wrapper = True
1515 has_side_effects = True
1518 primop EqStableNameOp "eqStableName#" GenPrimOp
1519 StableName# a -> StableName# a -> Int#
1521 primop StableNameToIntOp "stableNameToInt#" GenPrimOp
1522 StableName# a -> Int#
1524 ------------------------------------------------------------------------
1525 section "Unsafe pointer equality"
1526 -- (#1 Bad Guy: Alistair Reid :)
1527 ------------------------------------------------------------------------
1529 primop ReallyUnsafePtrEqualityOp "reallyUnsafePtrEquality#" GenPrimOp
1532 ------------------------------------------------------------------------
1533 section "Parallelism"
1534 ------------------------------------------------------------------------
1536 primop ParOp "par#" GenPrimOp
1539 -- Note that Par is lazy to avoid that the sparked thing
1540 -- gets evaluted strictly, which it should *not* be
1541 has_side_effects = True
1543 primop GetSparkOp "getSpark#" GenPrimOp
1544 State# s -> (# State# s, Int#, a #)
1546 has_side_effects = True
1549 -- HWL: The first 4 Int# in all par... annotations denote:
1550 -- name, granularity info, size of result, degree of parallelism
1551 -- Same structure as _seq_ i.e. returns Int#
1552 -- KSW: v, the second arg in parAt# and parAtForNow#, is used only to determine
1553 -- `the processor containing the expression v'; it is not evaluated
1555 primop ParGlobalOp "parGlobal#" GenPrimOp
1556 a -> Int# -> Int# -> Int# -> Int# -> b -> Int#
1558 has_side_effects = True
1560 primop ParLocalOp "parLocal#" GenPrimOp
1561 a -> Int# -> Int# -> Int# -> Int# -> b -> Int#
1563 has_side_effects = True
1565 primop ParAtOp "parAt#" GenPrimOp
1566 b -> a -> Int# -> Int# -> Int# -> Int# -> c -> Int#
1568 has_side_effects = True
1570 primop ParAtAbsOp "parAtAbs#" GenPrimOp
1571 a -> Int# -> Int# -> Int# -> Int# -> Int# -> b -> Int#
1573 has_side_effects = True
1575 primop ParAtRelOp "parAtRel#" GenPrimOp
1576 a -> Int# -> Int# -> Int# -> Int# -> Int# -> b -> Int#
1578 has_side_effects = True
1580 primop ParAtForNowOp "parAtForNow#" GenPrimOp
1581 b -> a -> Int# -> Int# -> Int# -> Int# -> c -> Int#
1583 has_side_effects = True
1585 -- copyable# and noFollow# are yet to be implemented (for GpH)
1587 --primop CopyableOp "copyable#" GenPrimOp
1590 -- has_side_effects = True
1592 --primop NoFollowOp "noFollow#" GenPrimOp
1595 -- has_side_effects = True
1598 ------------------------------------------------------------------------
1599 section "Tag to enum stuff"
1600 {Convert back and forth between values of enumerated types
1601 and small integers.}
1602 ------------------------------------------------------------------------
1604 primop DataToTagOp "dataToTag#" GenPrimOp
1607 strictness = { \ _arity -> mkStrictSig (mkTopDmdType [seqDmd] TopRes) }
1608 -- dataToTag# must have an evaluated argument
1610 primop TagToEnumOp "tagToEnum#" GenPrimOp
1613 ------------------------------------------------------------------------
1614 section "Bytecode operations"
1615 {Support for the bytecode interpreter and linker.}
1616 ------------------------------------------------------------------------
1619 {Primitive bytecode type.}
1621 primop AddrToHValueOp "addrToHValue#" GenPrimOp
1623 {Convert an {\tt Addr\#} to a followable type.}
1625 primop MkApUpd0_Op "mkApUpd0#" GenPrimOp
1630 primop NewBCOOp "newBCO#" GenPrimOp
1631 ByteArray# -> ByteArray# -> Array# a -> Int# -> ByteArray# -> State# s -> (# State# s, BCO# #)
1633 has_side_effects = True
1636 primop UnpackClosureOp "unpackClosure#" GenPrimOp
1637 a -> (# Addr#, Array# b, ByteArray# #)
1641 primop GetApStackValOp "getApStackVal#" GenPrimOp
1642 a -> Int# -> (# Int#, b #)
1646 ------------------------------------------------------------------------
1648 {These aren't nearly as wired in as Etc...}
1649 ------------------------------------------------------------------------
1651 primop TraceCcsOp "traceCcs#" GenPrimOp
1654 has_side_effects = True
1657 ------------------------------------------------------------------------
1659 {Miscellaneous built-ins}
1660 ------------------------------------------------------------------------
1664 { Evaluates its first argument to head normal form, and then returns its second
1665 argument as the result. }
1669 { The call {\tt (inline f)} arranges that f is inlined, regardless of its size.
1670 More precisely, the call {\tt (inline f)} rewrites to the right-hand side of
1671 {\tt f}'s definition. This allows the programmer to control inlining from a
1672 particular call site rather than the definition site of the function (c.f.
1673 {\tt INLINE} pragmas in User's Guide, Section 7.10.3, "INLINE and NOINLINE
1676 This inlining occurs regardless of the argument to the call or the size of
1677 {\tt f}'s definition; it is unconditional. The main caveat is that {\tt f}'s
1678 definition must be visible to the compiler. That is, {\tt f} must be
1679 {\tt let}-bound in the current scope. If no inlining takes place, the
1680 {\tt inline} function expands to the identity function in Phase zero; so its
1681 use imposes no overhead.
1683 If the function is defined in another module, GHC only exposes its inlining
1684 in the interface file if the function is sufficiently small that it might be
1685 inlined by the automatic mechanism. There is currently no way to tell GHC to
1686 expose arbitrarily-large functions in the interface file. (This shortcoming
1687 is something that could be fixed, with some kind of pragma.) }
1691 { The {\tt lazy} function restrains strictness analysis a little. The call
1692 {\tt (lazy e)} means the same as {\tt e}, but {\tt lazy} has a magical
1693 property so far as strictness analysis is concerned: it is lazy in its first
1694 argument, even though its semantics is strict. After strictness analysis has
1695 run, calls to {\tt lazy} are inlined to be the identity function.
1697 This behaviour is occasionally useful when controlling evaluation order.
1698 Notably, {\tt lazy} is used in the library definition of {\tt Control.Parallel.par}:
1700 {\tt par :: a -> b -> b}
1702 {\tt par x y = case (par\# x) of \_ -> lazy y}
1704 If {\tt lazy} were not lazy, {\tt par} would look strict in {\tt y} which
1705 would defeat the whole purpose of {\tt par}.
1707 Like {\tt seq}, the argument of {\tt lazy} can have an unboxed type. }
1710 { The type constructor {\tt Any} is type to which you can unsafely coerce any
1711 lifted type, and back.
1713 * It is lifted, and hence represented by a pointer
1715 * It does not claim to be a {\it data} type, and that's important for
1716 the code generator, because the code gen may {\it enter} a data value
1717 but never enters a function value.
1719 It's also used to instantiate un-constrained type variables after type
1720 checking. For example
1724 Annoyingly, we sometimes need {\tt Any}s of other kinds, such as {\tt (* -> *)} etc.
1725 This is a bit like tuples. We define a couple of useful ones here,
1726 and make others up on the fly. If any of these others end up being exported
1727 into interface files, we'll get a crash; at least until we add interface-file
1728 syntax to support them. }
1730 pseudoop "unsafeCoerce#"
1732 { The function {\tt unsafeCoerce\#} allows you to side-step the typechecker entirely. That
1733 is, it allows you to coerce any type into any other type. If you use this function,
1734 you had better get it right, otherwise segmentation faults await. It is generally
1735 used when you want to write a program that you know is well-typed, but where Haskell's
1736 type system is not expressive enough to prove that it is well typed.
1738 The following uses of {\tt unsafeCoerce\#} are supposed to work (i.e. not lead to
1739 spurious compile-time or run-time crashes):
1741 * Casting any lifted type to {\tt Any}
1743 * Casting {\tt Any} back to the real type
1745 * Casting an unboxed type to another unboxed type of the same size
1746 (but not coercions between floating-point and integral types)
1748 * Casting between two types that have the same runtime representation. One case is when
1749 the two types differ only in "phantom" type parameters, for example
1750 {\tt Ptr Int} to {\tt Ptr Float}, or {\tt [Int]} to {\tt [Float]} when the list is
1751 known to be empty. Also, a {\tt newtype} of a type {\tt T} has the same representation
1752 at runtime as {\tt T}.
1754 Other uses of {\tt unsafeCoerce\#} are undefined. In particular, you should not use
1755 {\tt unsafeCoerce\#} to cast a T to an algebraic data type D, unless T is also
1756 an algebraic data type. For example, do not cast {\tt Int->Int} to {\tt Bool}, even if
1757 you later cast that {\tt Bool} back to {\tt Int->Int} before applying it. The reasons
1758 have to do with GHC's internal representation details (for the congnoscenti, data values
1759 can be entered but function closures cannot). If you want a safe type to cast things
1760 to, use {\tt Any}, which is not an algebraic data type.
1764 -- NB. It is tempting to think that casting a value to a type that it doesn't have is safe
1765 -- as long as you don't "do anything" with the value in its cast form, such as seq on it. This
1766 -- isn't the case: the compiler can insert seqs itself, and if these happen at the wrong type,
1767 -- Bad Things Might Happen. See bug #1616: in this case we cast a function of type (a,b) -> (a,b)
1768 -- to () -> () and back again. The strictness analyser saw that the function was strict, but
1769 -- the wrapper had type () -> (), and hence the wrapper de-constructed the (), the worker re-constructed
1770 -- a new (), with the result that the code ended up with "case () of (a,b) -> ...".
1772 ------------------------------------------------------------------------
1774 ------------------------------------------------------------------------