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 and usage info.
54 has_side_effects = False
59 strictness = { \ arity -> mkStrictSig (mkTopDmdType (replicate arity lazyDmd) TopRes) }
60 usage = { nomangle other }
62 -- Currently, documentation is produced using latex, so contents of
63 -- description fields should be legal latex. Descriptions can contain
64 -- matched pairs of embedded curly brackets.
68 -- We need platform defines (tests for mingw32 below). However, we only
69 -- test the TARGET platform, which doesn't vary between stages, so the
70 -- stage1 platform defines are fine:
71 #include "../stage1/ghc_boot_platform.h"
73 section "The word size story."
74 {Haskell98 specifies that signed integers (type {\tt Int})
75 must contain at least 30 bits. GHC always implements {\tt
76 Int} using the primitive type {\tt Int\#}, whose size equals
77 the {\tt MachDeps.h} constant {\tt WORD\_SIZE\_IN\_BITS}.
78 This is normally set based on the {\tt config.h} parameter
79 {\tt SIZEOF\_HSWORD}, i.e., 32 bits on 32-bit machines, 64
80 bits on 64-bit machines. However, it can also be explicitly
81 set to a smaller number, e.g., 31 bits, to allow the
82 possibility of using tag bits. Currently GHC itself has only
83 32-bit and 64-bit variants, but 30 or 31-bit code can be
84 exported as an external core file for use in other back ends.
86 GHC also implements a primitive unsigned integer type {\tt
87 Word\#} which always has the same number of bits as {\tt
90 In addition, GHC supports families of explicit-sized integers
91 and words at 8, 16, 32, and 64 bits, with the usual
92 arithmetic operations, comparisons, and a range of
93 conversions. The 8-bit and 16-bit sizes are always
94 represented as {\tt Int\#} and {\tt Word\#}, and the
95 operations implemented in terms of the the primops on these
96 types, with suitable range restrictions on the results (using
97 the {\tt narrow$n$Int\#} and {\tt narrow$n$Word\#} families
98 of primops. The 32-bit sizes are represented using {\tt
99 Int\#} and {\tt Word\#} when {\tt WORD\_SIZE\_IN\_BITS}
100 $\geq$ 32; otherwise, these are represented using distinct
101 primitive types {\tt Int32\#} and {\tt Word32\#}. These (when
102 needed) have a complete set of corresponding operations;
103 however, nearly all of these are implemented as external C
104 functions rather than as primops. Exactly the same story
105 applies to the 64-bit sizes. All of these details are hidden
106 under the {\tt PrelInt} and {\tt PrelWord} modules, which use
107 {\tt \#if}-defs to invoke the appropriate types and
110 Word size also matters for the families of primops for
111 indexing/reading/writing fixed-size quantities at offsets
112 from an array base, address, or foreign pointer. Here, a
113 slightly different approach is taken. The names of these
114 primops are fixed, but their {\it types} vary according to
115 the value of {\tt WORD\_SIZE\_IN\_BITS}. For example, if word
116 size is at least 32 bits then an operator like
117 \texttt{indexInt32Array\#} has type {\tt ByteArr\# -> Int\#
118 -> Int\#}; otherwise it has type {\tt ByteArr\# -> Int\# ->
119 Int32\#}. This approach confines the necessary {\tt
120 \#if}-defs to this file; no conditional compilation is needed
121 in the files that expose these primops.
123 Finally, there are strongly deprecated primops for coercing
124 between {\tt Addr\#}, the primitive type of machine
125 addresses, and {\tt Int\#}. These are pretty bogus anyway,
126 but will work on existing 32-bit and 64-bit GHC targets; they
127 are completely bogus when tag bits are used in {\tt Int\#},
128 so are not available in this case. }
130 -- Define synonyms for indexing ops.
132 #if WORD_SIZE_IN_BITS < 32
134 #define WORD32 Word32#
140 #if WORD_SIZE_IN_BITS < 64
142 #define WORD64 Word64#
148 ------------------------------------------------------------------------
150 {Operations on 31-bit characters.}
151 ------------------------------------------------------------------------
155 primop CharGtOp "gtChar#" Compare Char# -> Char# -> Bool
156 primop CharGeOp "geChar#" Compare Char# -> Char# -> Bool
158 primop CharEqOp "eqChar#" Compare
159 Char# -> Char# -> Bool
160 with commutable = True
162 primop CharNeOp "neChar#" Compare
163 Char# -> Char# -> Bool
164 with commutable = True
166 primop CharLtOp "ltChar#" Compare Char# -> Char# -> Bool
167 primop CharLeOp "leChar#" Compare Char# -> Char# -> Bool
169 primop OrdOp "ord#" GenPrimOp Char# -> Int#
171 ------------------------------------------------------------------------
173 {Operations on native-size integers (30+ bits).}
174 ------------------------------------------------------------------------
178 primop IntAddOp "+#" Dyadic
180 with commutable = True
182 primop IntSubOp "-#" Dyadic Int# -> Int# -> Int#
185 Dyadic Int# -> Int# -> Int#
186 {Low word of signed integer multiply.}
187 with commutable = True
189 primop IntMulMayOfloOp "mulIntMayOflo#"
190 Dyadic Int# -> Int# -> Int#
191 {Return non-zero if there is any possibility that the upper word of a
192 signed integer multiply might contain useful information. Return
193 zero only if you are completely sure that no overflow can occur.
194 On a 32-bit platform, the recommmended implementation is to do a
195 32 x 32 -> 64 signed multiply, and subtract result[63:32] from
196 (result[31] >>signed 31). If this is zero, meaning that the
197 upper word is merely a sign extension of the lower one, no
200 On a 64-bit platform it is not always possible to
201 acquire the top 64 bits of the result. Therefore, a recommended
202 implementation is to take the absolute value of both operands, and
203 return 0 iff bits[63:31] of them are zero, since that means that their
204 magnitudes fit within 31 bits, so the magnitude of the product must fit
207 If in doubt, return non-zero, but do make an effort to create the
208 correct answer for small args, since otherwise the performance of
209 \texttt{(*) :: Integer -> Integer -> Integer} will be poor.
211 with commutable = True
213 primop IntQuotOp "quotInt#" Dyadic
215 {Rounds towards zero.}
218 primop IntRemOp "remInt#" Dyadic
220 {Satisfies \texttt{(quotInt\# x y) *\# y +\# (remInt\# x y) == x}.}
223 primop IntGcdOp "gcdInt#" Dyadic Int# -> Int# -> Int#
224 with out_of_line = True
226 primop IntNegOp "negateInt#" Monadic Int# -> Int#
227 primop IntAddCOp "addIntC#" GenPrimOp Int# -> Int# -> (# Int#, Int# #)
228 {Add with carry. First member of result is (wrapped) sum;
229 second member is 0 iff no overflow occured.}
230 primop IntSubCOp "subIntC#" GenPrimOp Int# -> Int# -> (# Int#, Int# #)
231 {Subtract with carry. First member of result is (wrapped) difference;
232 second member is 0 iff no overflow occured.}
234 primop IntGtOp ">#" Compare Int# -> Int# -> Bool
235 primop IntGeOp ">=#" Compare Int# -> Int# -> Bool
237 primop IntEqOp "==#" Compare
239 with commutable = True
241 primop IntNeOp "/=#" Compare
243 with commutable = True
245 primop IntLtOp "<#" Compare Int# -> Int# -> Bool
246 primop IntLeOp "<=#" Compare Int# -> Int# -> Bool
248 primop ChrOp "chr#" GenPrimOp Int# -> Char#
250 primop Int2WordOp "int2Word#" GenPrimOp Int# -> Word#
251 primop Int2FloatOp "int2Float#" GenPrimOp Int# -> Float#
252 primop Int2DoubleOp "int2Double#" GenPrimOp Int# -> Double#
254 primop Int2IntegerOp "int2Integer#"
255 GenPrimOp Int# -> (# Int#, ByteArr# #)
256 with out_of_line = True
258 primop ISllOp "uncheckedIShiftL#" GenPrimOp Int# -> Int# -> Int#
259 {Shift left. Result undefined if shift amount is not
260 in the range 0 to word size - 1 inclusive.}
261 primop ISraOp "uncheckedIShiftRA#" GenPrimOp Int# -> Int# -> Int#
262 {Shift right arithmetic. Result undefined if shift amount is not
263 in the range 0 to word size - 1 inclusive.}
264 primop ISrlOp "uncheckedIShiftRL#" GenPrimOp Int# -> Int# -> Int#
265 {Shift right logical. Result undefined if shift amount is not
266 in the range 0 to word size - 1 inclusive.}
268 ------------------------------------------------------------------------
270 {Operations on native-sized unsigned words (30+ bits).}
271 ------------------------------------------------------------------------
275 primop WordAddOp "plusWord#" Dyadic Word# -> Word# -> Word#
276 with commutable = True
278 primop WordSubOp "minusWord#" Dyadic Word# -> Word# -> Word#
280 primop WordMulOp "timesWord#" Dyadic Word# -> Word# -> Word#
281 with commutable = True
283 primop WordQuotOp "quotWord#" Dyadic Word# -> Word# -> Word#
286 primop WordRemOp "remWord#" Dyadic Word# -> Word# -> Word#
289 primop AndOp "and#" Dyadic Word# -> Word# -> Word#
290 with commutable = True
292 primop OrOp "or#" Dyadic Word# -> Word# -> Word#
293 with commutable = True
295 primop XorOp "xor#" Dyadic Word# -> Word# -> Word#
296 with commutable = True
298 primop NotOp "not#" Monadic Word# -> Word#
300 primop SllOp "uncheckedShiftL#" GenPrimOp Word# -> Int# -> Word#
301 {Shift left logical. Result undefined if shift amount is not
302 in the range 0 to word size - 1 inclusive.}
303 primop SrlOp "uncheckedShiftRL#" GenPrimOp Word# -> Int# -> Word#
304 {Shift right logical. Result undefined if shift amount is not
305 in the range 0 to word size - 1 inclusive.}
307 primop Word2IntOp "word2Int#" GenPrimOp Word# -> Int#
309 primop Word2IntegerOp "word2Integer#" GenPrimOp
310 Word# -> (# Int#, ByteArr# #)
311 with out_of_line = True
313 primop WordGtOp "gtWord#" Compare Word# -> Word# -> Bool
314 primop WordGeOp "geWord#" Compare Word# -> Word# -> Bool
315 primop WordEqOp "eqWord#" Compare Word# -> Word# -> Bool
316 primop WordNeOp "neWord#" Compare Word# -> Word# -> Bool
317 primop WordLtOp "ltWord#" Compare Word# -> Word# -> Bool
318 primop WordLeOp "leWord#" Compare Word# -> Word# -> Bool
320 ------------------------------------------------------------------------
322 {Explicit narrowing of native-sized ints or words.}
323 ------------------------------------------------------------------------
325 primop Narrow8IntOp "narrow8Int#" Monadic Int# -> Int#
326 primop Narrow16IntOp "narrow16Int#" Monadic Int# -> Int#
327 primop Narrow32IntOp "narrow32Int#" Monadic Int# -> Int#
328 primop Narrow8WordOp "narrow8Word#" Monadic Word# -> Word#
329 primop Narrow16WordOp "narrow16Word#" Monadic Word# -> Word#
330 primop Narrow32WordOp "narrow32Word#" Monadic Word# -> Word#
333 #if WORD_SIZE_IN_BITS < 32
334 ------------------------------------------------------------------------
336 {Operations on 32-bit integers ({\tt Int32\#}). This type is only used
337 if plain {\tt Int\#} has less than 32 bits. In any case, the operations
338 are not primops; they are implemented (if needed) as ccalls instead.}
339 ------------------------------------------------------------------------
343 primop Int32ToIntegerOp "int32ToInteger#" GenPrimOp
344 Int32# -> (# Int#, ByteArr# #)
345 with out_of_line = True
348 ------------------------------------------------------------------------
350 {Operations on 32-bit unsigned words. This type is only used
351 if plain {\tt Word\#} has less than 32 bits. In any case, the operations
352 are not primops; they are implemented (if needed) as ccalls instead.}
353 ------------------------------------------------------------------------
357 primop Word32ToIntegerOp "word32ToInteger#" GenPrimOp
358 Word32# -> (# Int#, ByteArr# #)
359 with out_of_line = True
365 #if WORD_SIZE_IN_BITS < 64
366 ------------------------------------------------------------------------
368 {Operations on 64-bit unsigned words. This type is only used
369 if plain {\tt Int\#} has less than 64 bits. In any case, the operations
370 are not primops; they are implemented (if needed) as ccalls instead.}
371 ------------------------------------------------------------------------
375 primop Int64ToIntegerOp "int64ToInteger#" GenPrimOp
376 Int64# -> (# Int#, ByteArr# #)
377 with out_of_line = True
379 ------------------------------------------------------------------------
381 {Operations on 64-bit unsigned words. This type is only used
382 if plain {\tt Word\#} has less than 64 bits. In any case, the operations
383 are not primops; they are implemented (if needed) as ccalls instead.}
384 ------------------------------------------------------------------------
388 primop Word64ToIntegerOp "word64ToInteger#" GenPrimOp
389 Word64# -> (# Int#, ByteArr# #)
390 with out_of_line = True
394 ------------------------------------------------------------------------
396 {Operations on arbitrary-precision integers. These operations are
397 implemented via the GMP package. An integer is represented as a pair
398 consisting of an {\tt Int\#} representing the number of 'limbs' in use and
399 the sign, and a {\tt ByteArr\#} containing the 'limbs' themselves. Such pairs
400 are returned as unboxed pairs, but must be passed as separate
403 For .NET these operations are implemented by foreign imports, so the
404 primops are omitted.}
405 ------------------------------------------------------------------------
409 primop IntegerAddOp "plusInteger#" GenPrimOp
410 Int# -> ByteArr# -> Int# -> ByteArr# -> (# Int#, ByteArr# #)
411 with commutable = True
414 primop IntegerSubOp "minusInteger#" GenPrimOp
415 Int# -> ByteArr# -> Int# -> ByteArr# -> (# Int#, ByteArr# #)
416 with out_of_line = True
418 primop IntegerMulOp "timesInteger#" GenPrimOp
419 Int# -> ByteArr# -> Int# -> ByteArr# -> (# Int#, ByteArr# #)
420 with commutable = True
423 primop IntegerGcdOp "gcdInteger#" GenPrimOp
424 Int# -> ByteArr# -> Int# -> ByteArr# -> (# Int#, ByteArr# #)
425 {Greatest common divisor.}
426 with commutable = True
429 primop IntegerIntGcdOp "gcdIntegerInt#" GenPrimOp
430 Int# -> ByteArr# -> Int# -> Int#
431 {Greatest common divisor, where second argument is an ordinary {\tt Int\#}.}
432 with out_of_line = True
434 primop IntegerDivExactOp "divExactInteger#" GenPrimOp
435 Int# -> ByteArr# -> Int# -> ByteArr# -> (# Int#, ByteArr# #)
436 {Divisor is guaranteed to be a factor of dividend.}
437 with out_of_line = True
439 primop IntegerQuotOp "quotInteger#" GenPrimOp
440 Int# -> ByteArr# -> Int# -> ByteArr# -> (# Int#, ByteArr# #)
441 {Rounds towards zero.}
442 with out_of_line = True
444 primop IntegerRemOp "remInteger#" GenPrimOp
445 Int# -> ByteArr# -> Int# -> ByteArr# -> (# Int#, ByteArr# #)
446 {Satisfies \texttt{plusInteger\# (timesInteger\# (quotInteger\# x y) y) (remInteger\# x y) == x}.}
447 with out_of_line = True
449 primop IntegerCmpOp "cmpInteger#" GenPrimOp
450 Int# -> ByteArr# -> Int# -> ByteArr# -> Int#
451 {Returns -1,0,1 according as first argument is less than, equal to, or greater than second argument.}
452 with needs_wrapper = True
455 primop IntegerCmpIntOp "cmpIntegerInt#" GenPrimOp
456 Int# -> ByteArr# -> Int# -> Int#
457 {Returns -1,0,1 according as first argument is less than, equal to, or greater than second argument, which
458 is an ordinary Int\#.}
459 with needs_wrapper = True
462 primop IntegerQuotRemOp "quotRemInteger#" GenPrimOp
463 Int# -> ByteArr# -> Int# -> ByteArr# -> (# Int#, ByteArr#, Int#, ByteArr# #)
464 {Compute quot and rem simulaneously.}
468 primop IntegerDivModOp "divModInteger#" GenPrimOp
469 Int# -> ByteArr# -> Int# -> ByteArr# -> (# Int#, ByteArr#, Int#, ByteArr# #)
470 {Compute div and mod simultaneously, where div rounds towards negative infinity
471 and\texttt{(q,r) = divModInteger\#(x,y)} implies \texttt{plusInteger\# (timesInteger\# q y) r = x}.}
475 primop Integer2IntOp "integer2Int#" GenPrimOp
476 Int# -> ByteArr# -> Int#
477 with needs_wrapper = True
480 primop Integer2WordOp "integer2Word#" GenPrimOp
481 Int# -> ByteArr# -> Word#
482 with needs_wrapper = True
485 #if WORD_SIZE_IN_BITS < 32
486 primop IntegerToInt32Op "integerToInt32#" GenPrimOp
487 Int# -> ByteArr# -> Int32#
489 primop IntegerToWord32Op "integerToWord32#" GenPrimOp
490 Int# -> ByteArr# -> Word32#
493 primop IntegerAndOp "andInteger#" GenPrimOp
494 Int# -> ByteArr# -> Int# -> ByteArr# -> (# Int#, ByteArr# #)
495 with out_of_line = True
497 primop IntegerOrOp "orInteger#" GenPrimOp
498 Int# -> ByteArr# -> Int# -> ByteArr# -> (# Int#, ByteArr# #)
499 with out_of_line = True
501 primop IntegerXorOp "xorInteger#" GenPrimOp
502 Int# -> ByteArr# -> Int# -> ByteArr# -> (# Int#, ByteArr# #)
503 with out_of_line = True
505 primop IntegerComplementOp "complementInteger#" GenPrimOp
506 Int# -> ByteArr# -> (# Int#, ByteArr# #)
507 with out_of_line = True
509 #endif /* ndef ILX */
511 ------------------------------------------------------------------------
513 {Operations on double-precision (64 bit) floating-point numbers.}
514 ------------------------------------------------------------------------
518 primop DoubleGtOp ">##" Compare Double# -> Double# -> Bool
519 primop DoubleGeOp ">=##" Compare Double# -> Double# -> Bool
521 primop DoubleEqOp "==##" Compare
522 Double# -> Double# -> Bool
523 with commutable = True
525 primop DoubleNeOp "/=##" Compare
526 Double# -> Double# -> Bool
527 with commutable = True
529 primop DoubleLtOp "<##" Compare Double# -> Double# -> Bool
530 primop DoubleLeOp "<=##" Compare Double# -> Double# -> Bool
532 primop DoubleAddOp "+##" Dyadic
533 Double# -> Double# -> Double#
534 with commutable = True
536 primop DoubleSubOp "-##" Dyadic Double# -> Double# -> Double#
538 primop DoubleMulOp "*##" Dyadic
539 Double# -> Double# -> Double#
540 with commutable = True
542 primop DoubleDivOp "/##" Dyadic
543 Double# -> Double# -> Double#
546 primop DoubleNegOp "negateDouble#" Monadic Double# -> Double#
548 primop Double2IntOp "double2Int#" GenPrimOp Double# -> Int#
549 primop Double2FloatOp "double2Float#" GenPrimOp Double# -> Float#
551 primop DoubleExpOp "expDouble#" Monadic
553 with needs_wrapper = True
555 primop DoubleLogOp "logDouble#" Monadic
561 primop DoubleSqrtOp "sqrtDouble#" Monadic
563 with needs_wrapper = True
565 primop DoubleSinOp "sinDouble#" Monadic
567 with needs_wrapper = True
569 primop DoubleCosOp "cosDouble#" Monadic
571 with needs_wrapper = True
573 primop DoubleTanOp "tanDouble#" Monadic
575 with needs_wrapper = True
577 primop DoubleAsinOp "asinDouble#" Monadic
583 primop DoubleAcosOp "acosDouble#" Monadic
589 primop DoubleAtanOp "atanDouble#" Monadic
594 primop DoubleSinhOp "sinhDouble#" Monadic
596 with needs_wrapper = True
598 primop DoubleCoshOp "coshDouble#" Monadic
600 with needs_wrapper = True
602 primop DoubleTanhOp "tanhDouble#" Monadic
604 with needs_wrapper = True
606 primop DoublePowerOp "**##" Dyadic
607 Double# -> Double# -> Double#
609 with needs_wrapper = True
611 primop DoubleDecodeOp "decodeDouble#" GenPrimOp
612 Double# -> (# Int#, Int#, ByteArr# #)
613 {Convert to arbitrary-precision integer.
614 First {\tt Int\#} in result is the exponent; second {\tt Int\#} and {\tt ByteArr\#}
615 represent an {\tt Integer\#} holding the mantissa.}
616 with out_of_line = True
618 ------------------------------------------------------------------------
620 {Operations on single-precision (32-bit) floating-point numbers.}
621 ------------------------------------------------------------------------
625 primop FloatGtOp "gtFloat#" Compare Float# -> Float# -> Bool
626 primop FloatGeOp "geFloat#" Compare Float# -> Float# -> Bool
628 primop FloatEqOp "eqFloat#" Compare
629 Float# -> Float# -> Bool
630 with commutable = True
632 primop FloatNeOp "neFloat#" Compare
633 Float# -> Float# -> Bool
634 with commutable = True
636 primop FloatLtOp "ltFloat#" Compare Float# -> Float# -> Bool
637 primop FloatLeOp "leFloat#" Compare Float# -> Float# -> Bool
639 primop FloatAddOp "plusFloat#" Dyadic
640 Float# -> Float# -> Float#
641 with commutable = True
643 primop FloatSubOp "minusFloat#" Dyadic Float# -> Float# -> Float#
645 primop FloatMulOp "timesFloat#" Dyadic
646 Float# -> Float# -> Float#
647 with commutable = True
649 primop FloatDivOp "divideFloat#" Dyadic
650 Float# -> Float# -> Float#
653 primop FloatNegOp "negateFloat#" Monadic Float# -> Float#
655 primop Float2IntOp "float2Int#" GenPrimOp Float# -> Int#
657 primop FloatExpOp "expFloat#" Monadic
659 with needs_wrapper = True
661 primop FloatLogOp "logFloat#" Monadic
663 with needs_wrapper = True
666 primop FloatSqrtOp "sqrtFloat#" Monadic
668 with needs_wrapper = True
670 primop FloatSinOp "sinFloat#" Monadic
672 with needs_wrapper = True
674 primop FloatCosOp "cosFloat#" Monadic
676 with needs_wrapper = True
678 primop FloatTanOp "tanFloat#" Monadic
680 with needs_wrapper = True
682 primop FloatAsinOp "asinFloat#" Monadic
684 with needs_wrapper = True
687 primop FloatAcosOp "acosFloat#" Monadic
689 with needs_wrapper = True
692 primop FloatAtanOp "atanFloat#" Monadic
694 with needs_wrapper = True
696 primop FloatSinhOp "sinhFloat#" Monadic
698 with needs_wrapper = True
700 primop FloatCoshOp "coshFloat#" Monadic
702 with needs_wrapper = True
704 primop FloatTanhOp "tanhFloat#" Monadic
706 with needs_wrapper = True
708 primop FloatPowerOp "powerFloat#" Dyadic
709 Float# -> Float# -> Float#
710 with needs_wrapper = True
712 primop Float2DoubleOp "float2Double#" GenPrimOp Float# -> Double#
714 primop FloatDecodeOp "decodeFloat#" GenPrimOp
715 Float# -> (# Int#, Int#, ByteArr# #)
716 {Convert to arbitrary-precision integer.
717 First {\tt Int\#} in result is the exponent; second {\tt Int\#} and {\tt ByteArr\#}
718 represent an {\tt Integer\#} holding the mantissa.}
719 with out_of_line = True
721 ------------------------------------------------------------------------
723 {Operations on {\tt Array\#}.}
724 ------------------------------------------------------------------------
730 primop NewArrayOp "newArray#" GenPrimOp
731 Int# -> a -> State# s -> (# State# s, MutArr# s a #)
732 {Create a new mutable array of specified size (in bytes),
733 in the specified state thread,
734 with each element containing the specified initial value.}
736 usage = { mangle NewArrayOp [mkP, mkM, mkP] mkM }
739 primop SameMutableArrayOp "sameMutableArray#" GenPrimOp
740 MutArr# s a -> MutArr# s a -> Bool
742 usage = { mangle SameMutableArrayOp [mkP, mkP] mkM }
744 primop ReadArrayOp "readArray#" GenPrimOp
745 MutArr# s a -> Int# -> State# s -> (# State# s, a #)
746 {Read from specified index of mutable array. Result is not yet evaluated.}
748 usage = { mangle ReadArrayOp [mkM, mkP, mkP] mkM }
750 primop WriteArrayOp "writeArray#" GenPrimOp
751 MutArr# s a -> Int# -> a -> State# s -> State# s
752 {Write to specified index of mutable array.}
754 usage = { mangle WriteArrayOp [mkM, mkP, mkM, mkP] mkR }
755 has_side_effects = True
757 primop IndexArrayOp "indexArray#" GenPrimOp
758 Array# a -> Int# -> (# a #)
759 {Read from specified index of immutable array. Result is packaged into
760 an unboxed singleton; the result itself is not yet evaluated.}
762 usage = { mangle IndexArrayOp [mkM, mkP] mkM }
764 primop UnsafeFreezeArrayOp "unsafeFreezeArray#" GenPrimOp
765 MutArr# s a -> State# s -> (# State# s, Array# a #)
766 {Make a mutable array immutable, without copying.}
768 usage = { mangle UnsafeFreezeArrayOp [mkM, mkP] mkM }
769 has_side_effects = True
771 primop UnsafeThawArrayOp "unsafeThawArray#" GenPrimOp
772 Array# a -> State# s -> (# State# s, MutArr# s a #)
773 {Make an immutable array mutable, without copying.}
775 usage = { mangle UnsafeThawArrayOp [mkM, mkP] mkM }
778 ------------------------------------------------------------------------
779 section "Byte Arrays"
780 {Operations on {\tt ByteArray\#}. A {\tt ByteArray\#} is a just a region of
781 raw memory in the garbage-collected heap, which is not scanned
782 for pointers. It carries its own size (in bytes). There are
783 three sets of operations for accessing byte array contents:
784 index for reading from immutable byte arrays, and read/write
785 for mutable byte arrays. Each set contains operations for
786 a range of useful primitive data types. Each operation takes
787 an offset measured in terms of the size fo the primitive type
788 being read or written.}
790 ------------------------------------------------------------------------
794 primtype MutByteArr# s
796 primop NewByteArrayOp_Char "newByteArray#" GenPrimOp
797 Int# -> State# s -> (# State# s, MutByteArr# s #)
798 {Create a new mutable byte array of specified size (in bytes), in
799 the specified state thread.}
800 with out_of_line = True
802 primop NewPinnedByteArrayOp_Char "newPinnedByteArray#" GenPrimOp
803 Int# -> State# s -> (# State# s, MutByteArr# s #)
804 {Create a mutable byte array that the GC guarantees not to move.}
805 with out_of_line = True
807 primop ByteArrayContents_Char "byteArrayContents#" GenPrimOp
809 {Intended for use with pinned arrays; otherwise very unsafe!}
811 primop SameMutableByteArrayOp "sameMutableByteArray#" GenPrimOp
812 MutByteArr# s -> MutByteArr# s -> Bool
814 primop UnsafeFreezeByteArrayOp "unsafeFreezeByteArray#" GenPrimOp
815 MutByteArr# s -> State# s -> (# State# s, ByteArr# #)
816 {Make a mutable byte array immutable, without copying.}
818 has_side_effects = True
820 primop SizeofByteArrayOp "sizeofByteArray#" GenPrimOp
823 primop SizeofMutableByteArrayOp "sizeofMutableByteArray#" GenPrimOp
824 MutByteArr# s -> Int#
827 primop IndexByteArrayOp_Char "indexCharArray#" GenPrimOp
828 ByteArr# -> Int# -> Char#
829 {Read 8-bit character; offset in bytes.}
831 primop IndexByteArrayOp_WideChar "indexWideCharArray#" GenPrimOp
832 ByteArr# -> Int# -> Char#
833 {Read 31-bit character; offset in 4-byte words.}
835 primop IndexByteArrayOp_Int "indexIntArray#" GenPrimOp
836 ByteArr# -> Int# -> Int#
838 primop IndexByteArrayOp_Word "indexWordArray#" GenPrimOp
839 ByteArr# -> Int# -> Word#
841 primop IndexByteArrayOp_Addr "indexAddrArray#" GenPrimOp
842 ByteArr# -> Int# -> Addr#
844 primop IndexByteArrayOp_Float "indexFloatArray#" GenPrimOp
845 ByteArr# -> Int# -> Float#
847 primop IndexByteArrayOp_Double "indexDoubleArray#" GenPrimOp
848 ByteArr# -> Int# -> Double#
850 primop IndexByteArrayOp_StablePtr "indexStablePtrArray#" GenPrimOp
851 ByteArr# -> Int# -> StablePtr# a
853 primop IndexByteArrayOp_Int8 "indexInt8Array#" GenPrimOp
854 ByteArr# -> Int# -> Int#
856 primop IndexByteArrayOp_Int16 "indexInt16Array#" GenPrimOp
857 ByteArr# -> Int# -> Int#
859 primop IndexByteArrayOp_Int32 "indexInt32Array#" GenPrimOp
860 ByteArr# -> Int# -> INT32
862 primop IndexByteArrayOp_Int64 "indexInt64Array#" GenPrimOp
863 ByteArr# -> Int# -> INT64
865 primop IndexByteArrayOp_Word8 "indexWord8Array#" GenPrimOp
866 ByteArr# -> Int# -> Word#
868 primop IndexByteArrayOp_Word16 "indexWord16Array#" GenPrimOp
869 ByteArr# -> Int# -> Word#
871 primop IndexByteArrayOp_Word32 "indexWord32Array#" GenPrimOp
872 ByteArr# -> Int# -> WORD32
874 primop IndexByteArrayOp_Word64 "indexWord64Array#" GenPrimOp
875 ByteArr# -> Int# -> WORD64
877 primop ReadByteArrayOp_Char "readCharArray#" GenPrimOp
878 MutByteArr# s -> Int# -> State# s -> (# State# s, Char# #)
879 {Read 8-bit character; offset in bytes.}
881 primop ReadByteArrayOp_WideChar "readWideCharArray#" GenPrimOp
882 MutByteArr# s -> Int# -> State# s -> (# State# s, Char# #)
883 {Read 31-bit character; offset in 4-byte words.}
885 primop ReadByteArrayOp_Int "readIntArray#" GenPrimOp
886 MutByteArr# s -> Int# -> State# s -> (# State# s, Int# #)
888 primop ReadByteArrayOp_Word "readWordArray#" GenPrimOp
889 MutByteArr# s -> Int# -> State# s -> (# State# s, Word# #)
891 primop ReadByteArrayOp_Addr "readAddrArray#" GenPrimOp
892 MutByteArr# s -> Int# -> State# s -> (# State# s, Addr# #)
894 primop ReadByteArrayOp_Float "readFloatArray#" GenPrimOp
895 MutByteArr# s -> Int# -> State# s -> (# State# s, Float# #)
897 primop ReadByteArrayOp_Double "readDoubleArray#" GenPrimOp
898 MutByteArr# s -> Int# -> State# s -> (# State# s, Double# #)
900 primop ReadByteArrayOp_StablePtr "readStablePtrArray#" GenPrimOp
901 MutByteArr# s -> Int# -> State# s -> (# State# s, StablePtr# a #)
903 primop ReadByteArrayOp_Int8 "readInt8Array#" GenPrimOp
904 MutByteArr# s -> Int# -> State# s -> (# State# s, Int# #)
906 primop ReadByteArrayOp_Int16 "readInt16Array#" GenPrimOp
907 MutByteArr# s -> Int# -> State# s -> (# State# s, Int# #)
909 primop ReadByteArrayOp_Int32 "readInt32Array#" GenPrimOp
910 MutByteArr# s -> Int# -> State# s -> (# State# s, INT32 #)
912 primop ReadByteArrayOp_Int64 "readInt64Array#" GenPrimOp
913 MutByteArr# s -> Int# -> State# s -> (# State# s, INT64 #)
915 primop ReadByteArrayOp_Word8 "readWord8Array#" GenPrimOp
916 MutByteArr# s -> Int# -> State# s -> (# State# s, Word# #)
918 primop ReadByteArrayOp_Word16 "readWord16Array#" GenPrimOp
919 MutByteArr# s -> Int# -> State# s -> (# State# s, Word# #)
921 primop ReadByteArrayOp_Word32 "readWord32Array#" GenPrimOp
922 MutByteArr# s -> Int# -> State# s -> (# State# s, WORD32 #)
924 primop ReadByteArrayOp_Word64 "readWord64Array#" GenPrimOp
925 MutByteArr# s -> Int# -> State# s -> (# State# s, WORD64 #)
927 primop WriteByteArrayOp_Char "writeCharArray#" GenPrimOp
928 MutByteArr# s -> Int# -> Char# -> State# s -> State# s
929 {Write 8-bit character; offset in bytes.}
930 with has_side_effects = True
932 primop WriteByteArrayOp_WideChar "writeWideCharArray#" GenPrimOp
933 MutByteArr# s -> Int# -> Char# -> State# s -> State# s
934 {Write 31-bit character; offset in 4-byte words.}
935 with has_side_effects = True
937 primop WriteByteArrayOp_Int "writeIntArray#" GenPrimOp
938 MutByteArr# s -> Int# -> Int# -> State# s -> State# s
939 with has_side_effects = True
941 primop WriteByteArrayOp_Word "writeWordArray#" GenPrimOp
942 MutByteArr# s -> Int# -> Word# -> State# s -> State# s
943 with has_side_effects = True
945 primop WriteByteArrayOp_Addr "writeAddrArray#" GenPrimOp
946 MutByteArr# s -> Int# -> Addr# -> State# s -> State# s
947 with has_side_effects = True
949 primop WriteByteArrayOp_Float "writeFloatArray#" GenPrimOp
950 MutByteArr# s -> Int# -> Float# -> State# s -> State# s
951 with has_side_effects = True
953 primop WriteByteArrayOp_Double "writeDoubleArray#" GenPrimOp
954 MutByteArr# s -> Int# -> Double# -> State# s -> State# s
955 with has_side_effects = True
957 primop WriteByteArrayOp_StablePtr "writeStablePtrArray#" GenPrimOp
958 MutByteArr# s -> Int# -> StablePtr# a -> State# s -> State# s
959 with has_side_effects = True
961 primop WriteByteArrayOp_Int8 "writeInt8Array#" GenPrimOp
962 MutByteArr# s -> Int# -> Int# -> State# s -> State# s
963 with has_side_effects = True
965 primop WriteByteArrayOp_Int16 "writeInt16Array#" GenPrimOp
966 MutByteArr# s -> Int# -> Int# -> State# s -> State# s
967 with has_side_effects = True
969 primop WriteByteArrayOp_Int32 "writeInt32Array#" GenPrimOp
970 MutByteArr# s -> Int# -> INT32 -> State# s -> State# s
971 with has_side_effects = True
973 primop WriteByteArrayOp_Int64 "writeInt64Array#" GenPrimOp
974 MutByteArr# s -> Int# -> INT64 -> State# s -> State# s
975 with has_side_effects = True
977 primop WriteByteArrayOp_Word8 "writeWord8Array#" GenPrimOp
978 MutByteArr# s -> Int# -> Word# -> State# s -> State# s
979 with has_side_effects = True
981 primop WriteByteArrayOp_Word16 "writeWord16Array#" GenPrimOp
982 MutByteArr# s -> Int# -> Word# -> State# s -> State# s
983 with has_side_effects = True
985 primop WriteByteArrayOp_Word32 "writeWord32Array#" GenPrimOp
986 MutByteArr# s -> Int# -> WORD32 -> State# s -> State# s
987 with has_side_effects = True
989 primop WriteByteArrayOp_Word64 "writeWord64Array#" GenPrimOp
990 MutByteArr# s -> Int# -> WORD64 -> State# s -> State# s
991 with has_side_effects = True
993 ------------------------------------------------------------------------
995 ------------------------------------------------------------------------
998 { An arbitrary machine address assumed to point outside
999 the garbage-collected heap. }
1001 pseudoop "nullAddr#" Addr#
1002 { The null address. }
1004 primop AddrAddOp "plusAddr#" GenPrimOp Addr# -> Int# -> Addr#
1005 primop AddrSubOp "minusAddr#" GenPrimOp Addr# -> Addr# -> Int#
1006 {Result is meaningless if two {\tt Addr\#}s are so far apart that their
1007 difference doesn't fit in an {\tt Int\#}.}
1008 primop AddrRemOp "remAddr#" GenPrimOp Addr# -> Int# -> Int#
1009 {Return the remainder when the {\tt Addr\#} arg, treated like an {\tt Int\#},
1010 is divided by the {\tt Int\#} arg.}
1011 #if (WORD_SIZE_IN_BITS == 32 || WORD_SIZE_IN_BITS == 64)
1012 primop Addr2IntOp "addr2Int#" GenPrimOp Addr# -> Int#
1013 {Coerce directly from address to int. Strongly deprecated.}
1014 primop Int2AddrOp "int2Addr#" GenPrimOp Int# -> Addr#
1015 {Coerce directly from int to address. Strongly deprecated.}
1018 primop AddrGtOp "gtAddr#" Compare Addr# -> Addr# -> Bool
1019 primop AddrGeOp "geAddr#" Compare Addr# -> Addr# -> Bool
1020 primop AddrEqOp "eqAddr#" Compare Addr# -> Addr# -> Bool
1021 primop AddrNeOp "neAddr#" Compare Addr# -> Addr# -> Bool
1022 primop AddrLtOp "ltAddr#" Compare Addr# -> Addr# -> Bool
1023 primop AddrLeOp "leAddr#" Compare Addr# -> Addr# -> Bool
1025 primop IndexOffAddrOp_Char "indexCharOffAddr#" GenPrimOp
1026 Addr# -> Int# -> Char#
1027 {Reads 8-bit character; offset in bytes.}
1029 primop IndexOffAddrOp_WideChar "indexWideCharOffAddr#" GenPrimOp
1030 Addr# -> Int# -> Char#
1031 {Reads 31-bit character; offset in 4-byte words.}
1033 primop IndexOffAddrOp_Int "indexIntOffAddr#" GenPrimOp
1034 Addr# -> Int# -> Int#
1036 primop IndexOffAddrOp_Word "indexWordOffAddr#" GenPrimOp
1037 Addr# -> Int# -> Word#
1039 primop IndexOffAddrOp_Addr "indexAddrOffAddr#" GenPrimOp
1040 Addr# -> Int# -> Addr#
1042 primop IndexOffAddrOp_Float "indexFloatOffAddr#" GenPrimOp
1043 Addr# -> Int# -> Float#
1045 primop IndexOffAddrOp_Double "indexDoubleOffAddr#" GenPrimOp
1046 Addr# -> Int# -> Double#
1048 primop IndexOffAddrOp_StablePtr "indexStablePtrOffAddr#" GenPrimOp
1049 Addr# -> Int# -> StablePtr# a
1051 primop IndexOffAddrOp_Int8 "indexInt8OffAddr#" GenPrimOp
1052 Addr# -> Int# -> Int#
1054 primop IndexOffAddrOp_Int16 "indexInt16OffAddr#" GenPrimOp
1055 Addr# -> Int# -> Int#
1057 primop IndexOffAddrOp_Int32 "indexInt32OffAddr#" GenPrimOp
1058 Addr# -> Int# -> INT32
1060 primop IndexOffAddrOp_Int64 "indexInt64OffAddr#" GenPrimOp
1061 Addr# -> Int# -> INT64
1063 primop IndexOffAddrOp_Word8 "indexWord8OffAddr#" GenPrimOp
1064 Addr# -> Int# -> Word#
1066 primop IndexOffAddrOp_Word16 "indexWord16OffAddr#" GenPrimOp
1067 Addr# -> Int# -> Word#
1069 primop IndexOffAddrOp_Word32 "indexWord32OffAddr#" GenPrimOp
1070 Addr# -> Int# -> WORD32
1072 primop IndexOffAddrOp_Word64 "indexWord64OffAddr#" GenPrimOp
1073 Addr# -> Int# -> WORD64
1075 primop ReadOffAddrOp_Char "readCharOffAddr#" GenPrimOp
1076 Addr# -> Int# -> State# s -> (# State# s, Char# #)
1077 {Reads 8-bit character; offset in bytes.}
1079 primop ReadOffAddrOp_WideChar "readWideCharOffAddr#" GenPrimOp
1080 Addr# -> Int# -> State# s -> (# State# s, Char# #)
1081 {Reads 31-bit character; offset in 4-byte words.}
1083 primop ReadOffAddrOp_Int "readIntOffAddr#" GenPrimOp
1084 Addr# -> Int# -> State# s -> (# State# s, Int# #)
1086 primop ReadOffAddrOp_Word "readWordOffAddr#" GenPrimOp
1087 Addr# -> Int# -> State# s -> (# State# s, Word# #)
1089 primop ReadOffAddrOp_Addr "readAddrOffAddr#" GenPrimOp
1090 Addr# -> Int# -> State# s -> (# State# s, Addr# #)
1092 primop ReadOffAddrOp_Float "readFloatOffAddr#" GenPrimOp
1093 Addr# -> Int# -> State# s -> (# State# s, Float# #)
1095 primop ReadOffAddrOp_Double "readDoubleOffAddr#" GenPrimOp
1096 Addr# -> Int# -> State# s -> (# State# s, Double# #)
1098 primop ReadOffAddrOp_StablePtr "readStablePtrOffAddr#" GenPrimOp
1099 Addr# -> Int# -> State# s -> (# State# s, StablePtr# a #)
1101 primop ReadOffAddrOp_Int8 "readInt8OffAddr#" GenPrimOp
1102 Addr# -> Int# -> State# s -> (# State# s, Int# #)
1104 primop ReadOffAddrOp_Int16 "readInt16OffAddr#" GenPrimOp
1105 Addr# -> Int# -> State# s -> (# State# s, Int# #)
1107 primop ReadOffAddrOp_Int32 "readInt32OffAddr#" GenPrimOp
1108 Addr# -> Int# -> State# s -> (# State# s, INT32 #)
1110 primop ReadOffAddrOp_Int64 "readInt64OffAddr#" GenPrimOp
1111 Addr# -> Int# -> State# s -> (# State# s, INT64 #)
1113 primop ReadOffAddrOp_Word8 "readWord8OffAddr#" GenPrimOp
1114 Addr# -> Int# -> State# s -> (# State# s, Word# #)
1116 primop ReadOffAddrOp_Word16 "readWord16OffAddr#" GenPrimOp
1117 Addr# -> Int# -> State# s -> (# State# s, Word# #)
1119 primop ReadOffAddrOp_Word32 "readWord32OffAddr#" GenPrimOp
1120 Addr# -> Int# -> State# s -> (# State# s, WORD32 #)
1122 primop ReadOffAddrOp_Word64 "readWord64OffAddr#" GenPrimOp
1123 Addr# -> Int# -> State# s -> (# State# s, WORD64 #)
1126 primop WriteOffAddrOp_Char "writeCharOffAddr#" GenPrimOp
1127 Addr# -> Int# -> Char# -> State# s -> State# s
1128 with has_side_effects = True
1130 primop WriteOffAddrOp_WideChar "writeWideCharOffAddr#" GenPrimOp
1131 Addr# -> Int# -> Char# -> State# s -> State# s
1132 with has_side_effects = True
1134 primop WriteOffAddrOp_Int "writeIntOffAddr#" GenPrimOp
1135 Addr# -> Int# -> Int# -> State# s -> State# s
1136 with has_side_effects = True
1138 primop WriteOffAddrOp_Word "writeWordOffAddr#" GenPrimOp
1139 Addr# -> Int# -> Word# -> State# s -> State# s
1140 with has_side_effects = True
1142 primop WriteOffAddrOp_Addr "writeAddrOffAddr#" GenPrimOp
1143 Addr# -> Int# -> Addr# -> State# s -> State# s
1144 with has_side_effects = True
1146 primop WriteOffAddrOp_Float "writeFloatOffAddr#" GenPrimOp
1147 Addr# -> Int# -> Float# -> State# s -> State# s
1148 with has_side_effects = True
1150 primop WriteOffAddrOp_Double "writeDoubleOffAddr#" GenPrimOp
1151 Addr# -> Int# -> Double# -> State# s -> State# s
1152 with has_side_effects = True
1154 primop WriteOffAddrOp_StablePtr "writeStablePtrOffAddr#" GenPrimOp
1155 Addr# -> Int# -> StablePtr# a -> State# s -> State# s
1156 with has_side_effects = True
1158 primop WriteOffAddrOp_Int8 "writeInt8OffAddr#" GenPrimOp
1159 Addr# -> Int# -> Int# -> State# s -> State# s
1160 with has_side_effects = True
1162 primop WriteOffAddrOp_Int16 "writeInt16OffAddr#" GenPrimOp
1163 Addr# -> Int# -> Int# -> State# s -> State# s
1164 with has_side_effects = True
1166 primop WriteOffAddrOp_Int32 "writeInt32OffAddr#" GenPrimOp
1167 Addr# -> Int# -> INT32 -> State# s -> State# s
1168 with has_side_effects = True
1170 primop WriteOffAddrOp_Int64 "writeInt64OffAddr#" GenPrimOp
1171 Addr# -> Int# -> INT64 -> State# s -> State# s
1172 with has_side_effects = True
1174 primop WriteOffAddrOp_Word8 "writeWord8OffAddr#" GenPrimOp
1175 Addr# -> Int# -> Word# -> State# s -> State# s
1176 with has_side_effects = True
1178 primop WriteOffAddrOp_Word16 "writeWord16OffAddr#" GenPrimOp
1179 Addr# -> Int# -> Word# -> State# s -> State# s
1180 with has_side_effects = True
1182 primop WriteOffAddrOp_Word32 "writeWord32OffAddr#" GenPrimOp
1183 Addr# -> Int# -> WORD32 -> State# s -> State# s
1184 with has_side_effects = True
1186 primop WriteOffAddrOp_Word64 "writeWord64OffAddr#" GenPrimOp
1187 Addr# -> Int# -> WORD64 -> State# s -> State# s
1188 with has_side_effects = True
1190 ------------------------------------------------------------------------
1191 section "Mutable variables"
1192 {Operations on MutVar\#s.}
1193 ------------------------------------------------------------------------
1195 primtype MutVar# s a
1196 {A {\tt MutVar\#} behaves like a single-element mutable array.}
1198 primop NewMutVarOp "newMutVar#" GenPrimOp
1199 a -> State# s -> (# State# s, MutVar# s a #)
1200 {Create {\tt MutVar\#} with specified initial value in specified state thread.}
1202 usage = { mangle NewMutVarOp [mkM, mkP] mkM }
1205 primop ReadMutVarOp "readMutVar#" GenPrimOp
1206 MutVar# s a -> State# s -> (# State# s, a #)
1207 {Read contents of {\tt MutVar\#}. Result is not yet evaluated.}
1209 usage = { mangle ReadMutVarOp [mkM, mkP] mkM }
1211 primop WriteMutVarOp "writeMutVar#" GenPrimOp
1212 MutVar# s a -> a -> State# s -> State# s
1213 {Write contents of {\tt MutVar\#}.}
1215 usage = { mangle WriteMutVarOp [mkM, mkM, mkP] mkR }
1216 has_side_effects = True
1218 primop SameMutVarOp "sameMutVar#" GenPrimOp
1219 MutVar# s a -> MutVar# s a -> Bool
1221 usage = { mangle SameMutVarOp [mkP, mkP] mkM }
1223 -- not really the right type, but we don't know about pairs here. The
1226 -- MutVar# s a -> (a -> (a,b)) -> State# s -> (# State# s, b #)
1228 primop AtomicModifyMutVarOp "atomicModifyMutVar#" GenPrimOp
1229 MutVar# s a -> (a -> b) -> State# s -> (# State# s, c #)
1231 usage = { mangle AtomicModifyMutVarOp [mkP, mkM, mkP] mkM }
1232 has_side_effects = True
1235 ------------------------------------------------------------------------
1236 section "Exceptions"
1237 ------------------------------------------------------------------------
1239 primop CatchOp "catch#" GenPrimOp
1240 (State# RealWorld -> (# State# RealWorld, a #) )
1241 -> (b -> State# RealWorld -> (# State# RealWorld, a #) )
1243 -> (# State# RealWorld, a #)
1245 -- Catch is actually strict in its first argument
1246 -- but we don't want to tell the strictness
1247 -- analyser about that!
1248 usage = { mangle CatchOp [mkM, mkM . (inFun CatchOp mkM mkM), mkP] mkM }
1249 -- [mkO, mkO . (inFun mkM mkO)] mkO
1250 -- might use caught action multiply
1253 primop RaiseOp "raise#" GenPrimOp
1256 strictness = { \ arity -> mkStrictSig (mkTopDmdType [lazyDmd] BotRes) }
1257 -- NB: result is bottom
1258 usage = { mangle RaiseOp [mkM] mkM }
1261 -- raiseIO# needs to be a primop, because exceptions in the IO monad
1262 -- must be *precise* - we don't want the strictness analyser turning
1263 -- one kind of bottom into another, as it is allowed to do in pure code.
1265 primop RaiseIOOp "raiseIO#" GenPrimOp
1266 a -> State# RealWorld -> (# State# RealWorld, b #)
1270 primop BlockAsyncExceptionsOp "blockAsyncExceptions#" GenPrimOp
1271 (State# RealWorld -> (# State# RealWorld, a #))
1272 -> (State# RealWorld -> (# State# RealWorld, a #))
1276 primop UnblockAsyncExceptionsOp "unblockAsyncExceptions#" GenPrimOp
1277 (State# RealWorld -> (# State# RealWorld, a #))
1278 -> (State# RealWorld -> (# State# RealWorld, a #))
1282 ------------------------------------------------------------------------
1283 section "STM-accessible Mutable Variables"
1284 ------------------------------------------------------------------------
1288 primop AtomicallyOp "atomically#" GenPrimOp
1289 (State# RealWorld -> (# State# RealWorld, a #) )
1290 -> State# RealWorld -> (# State# RealWorld, a #)
1293 has_side_effects = True
1295 primop RetryOp "retry#" GenPrimOp
1296 State# RealWorld -> (# State# RealWorld, a #)
1299 has_side_effects = True
1301 primop CatchRetryOp "catchRetry#" GenPrimOp
1302 (State# RealWorld -> (# State# RealWorld, a #) )
1303 -> (State# RealWorld -> (# State# RealWorld, a #) )
1304 -> (State# RealWorld -> (# State# RealWorld, a #) )
1307 has_side_effects = True
1309 primop CatchSTMOp "catchSTM#" GenPrimOp
1310 (State# RealWorld -> (# State# RealWorld, a #) )
1311 -> (b -> State# RealWorld -> (# State# RealWorld, a #) )
1312 -> (State# RealWorld -> (# State# RealWorld, a #) )
1315 has_side_effects = True
1317 primop Check "check#" GenPrimOp
1318 (State# RealWorld -> (# State# RealWorld, a #) )
1319 -> (State# RealWorld -> (# State# RealWorld, () #) )
1322 has_side_effects = True
1324 primop NewTVarOp "newTVar#" GenPrimOp
1326 -> State# s -> (# State# s, TVar# s a #)
1327 {Create a new {\tt TVar\#} holding a specified initial value.}
1331 primop ReadTVarOp "readTVar#" GenPrimOp
1333 -> State# s -> (# State# s, a #)
1334 {Read contents of {\tt TVar\#}. Result is not yet evaluated.}
1338 primop WriteTVarOp "writeTVar#" GenPrimOp
1341 -> State# s -> State# s
1342 {Write contents of {\tt TVar\#}.}
1345 has_side_effects = True
1347 primop SameTVarOp "sameTVar#" GenPrimOp
1348 TVar# s a -> TVar# s a -> Bool
1351 ------------------------------------------------------------------------
1352 section "Synchronized Mutable Variables"
1353 {Operations on {\tt MVar\#}s. }
1354 ------------------------------------------------------------------------
1357 { A shared mutable variable ({\it not} the same as a {\tt MutVar\#}!).
1358 (Note: in a non-concurrent implementation, {\tt (MVar\# a)} can be
1359 represented by {\tt (MutVar\# (Maybe a))}.) }
1361 primop NewMVarOp "newMVar#" GenPrimOp
1362 State# s -> (# State# s, MVar# s a #)
1363 {Create new {\tt MVar\#}; initially empty.}
1365 usage = { mangle NewMVarOp [mkP] mkR }
1368 primop TakeMVarOp "takeMVar#" GenPrimOp
1369 MVar# s a -> State# s -> (# State# s, a #)
1370 {If {\tt MVar\#} is empty, block until it becomes full.
1371 Then remove and return its contents, and set it empty.}
1373 usage = { mangle TakeMVarOp [mkM, mkP] mkM }
1374 has_side_effects = True
1377 primop TryTakeMVarOp "tryTakeMVar#" GenPrimOp
1378 MVar# s a -> State# s -> (# State# s, Int#, a #)
1379 {If {\tt MVar\#} is empty, immediately return with integer 0 and value undefined.
1380 Otherwise, return with integer 1 and contents of {\tt MVar\#}, and set {\tt MVar\#} empty.}
1382 usage = { mangle TryTakeMVarOp [mkM, mkP] mkM }
1383 has_side_effects = True
1386 primop PutMVarOp "putMVar#" GenPrimOp
1387 MVar# s a -> a -> State# s -> State# s
1388 {If {\tt MVar\#} is full, block until it becomes empty.
1389 Then store value arg as its new contents.}
1391 usage = { mangle PutMVarOp [mkM, mkM, mkP] mkR }
1392 has_side_effects = True
1395 primop TryPutMVarOp "tryPutMVar#" GenPrimOp
1396 MVar# s a -> a -> State# s -> (# State# s, Int# #)
1397 {If {\tt MVar\#} is full, immediately return with integer 0.
1398 Otherwise, store value arg as {\tt MVar\#}'s new contents, and return with integer 1.}
1400 usage = { mangle TryPutMVarOp [mkM, mkM, mkP] mkR }
1401 has_side_effects = True
1404 primop SameMVarOp "sameMVar#" GenPrimOp
1405 MVar# s a -> MVar# s a -> Bool
1407 usage = { mangle SameMVarOp [mkP, mkP] mkM }
1409 primop IsEmptyMVarOp "isEmptyMVar#" GenPrimOp
1410 MVar# s a -> State# s -> (# State# s, Int# #)
1411 {Return 1 if {\tt MVar\#} is empty; 0 otherwise.}
1413 usage = { mangle IsEmptyMVarOp [mkP, mkP] mkM }
1416 ------------------------------------------------------------------------
1417 section "Delay/wait operations"
1418 ------------------------------------------------------------------------
1420 primop DelayOp "delay#" GenPrimOp
1421 Int# -> State# s -> State# s
1422 {Sleep specified number of microseconds.}
1424 needs_wrapper = True
1425 has_side_effects = True
1428 primop WaitReadOp "waitRead#" GenPrimOp
1429 Int# -> State# s -> State# s
1430 {Block until input is available on specified file descriptor.}
1432 needs_wrapper = True
1433 has_side_effects = True
1436 primop WaitWriteOp "waitWrite#" GenPrimOp
1437 Int# -> State# s -> State# s
1438 {Block until output is possible on specified file descriptor.}
1440 needs_wrapper = True
1441 has_side_effects = True
1444 #ifdef mingw32_TARGET_OS
1445 primop AsyncReadOp "asyncRead#" GenPrimOp
1446 Int# -> Int# -> Int# -> Addr# -> State# RealWorld-> (# State# RealWorld, Int#, Int# #)
1447 {Asynchronously read bytes from specified file descriptor.}
1449 needs_wrapper = True
1450 has_side_effects = True
1453 primop AsyncWriteOp "asyncWrite#" GenPrimOp
1454 Int# -> Int# -> Int# -> Addr# -> State# RealWorld-> (# State# RealWorld, Int#, Int# #)
1455 {Asynchronously write bytes from specified file descriptor.}
1457 needs_wrapper = True
1458 has_side_effects = True
1461 primop AsyncDoProcOp "asyncDoProc#" GenPrimOp
1462 Addr# -> Addr# -> State# RealWorld-> (# State# RealWorld, Int#, Int# #)
1463 {Asynchronously perform procedure (first arg), passing it 2nd arg.}
1465 needs_wrapper = True
1466 has_side_effects = True
1471 ------------------------------------------------------------------------
1472 section "Concurrency primitives"
1473 ------------------------------------------------------------------------
1476 { {\tt State\#} is the primitive, unlifted type of states. It has
1477 one type parameter, thus {\tt State\# RealWorld}, or {\tt State\# s},
1478 where s is a type variable. The only purpose of the type parameter
1479 is to keep different state threads separate. It is represented by
1483 { {\tt RealWorld} is deeply magical. It is {\it primitive}, but it is not
1484 {\it unlifted} (hence {\tt ptrArg}). We never manipulate values of type
1485 {\tt RealWorld}; it's only used in the type system, to parameterise {\tt State\#}. }
1488 {(In a non-concurrent implementation, this can be a singleton
1489 type, whose (unique) value is returned by {\tt myThreadId\#}. The
1490 other operations can be omitted.)}
1492 primop ForkOp "fork#" GenPrimOp
1493 a -> State# RealWorld -> (# State# RealWorld, ThreadId# #)
1495 usage = { mangle ForkOp [mkO, mkP] mkR }
1496 has_side_effects = True
1499 primop ForkOnOp "forkOn#" GenPrimOp
1500 Int# -> a -> State# RealWorld -> (# State# RealWorld, ThreadId# #)
1502 usage = { mangle ForkOnOp [mkO, mkP] mkR }
1503 has_side_effects = True
1506 primop KillThreadOp "killThread#" GenPrimOp
1507 ThreadId# -> a -> State# RealWorld -> State# RealWorld
1509 usage = { mangle KillThreadOp [mkP, mkM, mkP] mkR }
1510 has_side_effects = True
1513 primop YieldOp "yield#" GenPrimOp
1514 State# RealWorld -> State# RealWorld
1516 has_side_effects = True
1519 primop MyThreadIdOp "myThreadId#" GenPrimOp
1520 State# RealWorld -> (# State# RealWorld, ThreadId# #)
1524 primop LabelThreadOp "labelThread#" GenPrimOp
1525 ThreadId# -> Addr# -> State# RealWorld -> State# RealWorld
1527 has_side_effects = True
1530 primop IsCurrentThreadBoundOp "isCurrentThreadBound#" GenPrimOp
1531 State# RealWorld -> (# State# RealWorld, Int# #)
1535 primop NoDuplicateOp "noDuplicate#" GenPrimOp
1536 State# RealWorld -> State# RealWorld
1540 ------------------------------------------------------------------------
1541 section "Weak pointers"
1542 ------------------------------------------------------------------------
1546 -- note that tyvar "o" denotes openAlphaTyVar
1548 primop MkWeakOp "mkWeak#" GenPrimOp
1549 o -> b -> c -> State# RealWorld -> (# State# RealWorld, Weak# b #)
1551 usage = { mangle MkWeakOp [mkZ, mkM, mkM, mkP] mkM }
1552 has_side_effects = True
1555 primop DeRefWeakOp "deRefWeak#" GenPrimOp
1556 Weak# a -> State# RealWorld -> (# State# RealWorld, Int#, a #)
1558 usage = { mangle DeRefWeakOp [mkM, mkP] mkM }
1559 has_side_effects = True
1562 primop FinalizeWeakOp "finalizeWeak#" GenPrimOp
1563 Weak# a -> State# RealWorld -> (# State# RealWorld, Int#,
1564 (State# RealWorld -> (# State# RealWorld, () #)) #)
1566 usage = { mangle FinalizeWeakOp [mkM, mkP]
1567 (mkR . (inUB FinalizeWeakOp
1568 [id,id,inFun FinalizeWeakOp mkR mkM])) }
1569 has_side_effects = True
1572 primop TouchOp "touch#" GenPrimOp
1573 o -> State# RealWorld -> State# RealWorld
1575 has_side_effects = True
1577 ------------------------------------------------------------------------
1578 section "Stable pointers and names"
1579 ------------------------------------------------------------------------
1581 primtype StablePtr# a
1583 primtype StableName# a
1585 primop MakeStablePtrOp "makeStablePtr#" GenPrimOp
1586 a -> State# RealWorld -> (# State# RealWorld, StablePtr# a #)
1588 usage = { mangle MakeStablePtrOp [mkM, mkP] mkM }
1589 has_side_effects = True
1592 primop DeRefStablePtrOp "deRefStablePtr#" GenPrimOp
1593 StablePtr# a -> State# RealWorld -> (# State# RealWorld, a #)
1595 usage = { mangle DeRefStablePtrOp [mkM, mkP] mkM }
1596 needs_wrapper = True
1597 has_side_effects = True
1600 primop EqStablePtrOp "eqStablePtr#" GenPrimOp
1601 StablePtr# a -> StablePtr# a -> Int#
1603 usage = { mangle EqStablePtrOp [mkP, mkP] mkR }
1604 has_side_effects = True
1606 primop MakeStableNameOp "makeStableName#" GenPrimOp
1607 a -> State# RealWorld -> (# State# RealWorld, StableName# a #)
1609 usage = { mangle MakeStableNameOp [mkZ, mkP] mkR }
1610 needs_wrapper = True
1611 has_side_effects = True
1614 primop EqStableNameOp "eqStableName#" GenPrimOp
1615 StableName# a -> StableName# a -> Int#
1617 usage = { mangle EqStableNameOp [mkP, mkP] mkR }
1619 primop StableNameToIntOp "stableNameToInt#" GenPrimOp
1620 StableName# a -> Int#
1622 usage = { mangle StableNameToIntOp [mkP] mkR }
1624 ------------------------------------------------------------------------
1625 section "Unsafe pointer equality"
1626 -- (#1 Bad Guy: Alistair Reid :)
1627 ------------------------------------------------------------------------
1629 primop ReallyUnsafePtrEqualityOp "reallyUnsafePtrEquality#" GenPrimOp
1632 usage = { mangle ReallyUnsafePtrEqualityOp [mkZ, mkZ] mkR }
1634 ------------------------------------------------------------------------
1635 section "Parallelism"
1636 ------------------------------------------------------------------------
1638 primop ParOp "par#" GenPrimOp
1641 usage = { mangle ParOp [mkO] mkR }
1642 -- Note that Par is lazy to avoid that the sparked thing
1643 -- gets evaluted strictly, which it should *not* be
1644 has_side_effects = True
1646 -- HWL: The first 4 Int# in all par... annotations denote:
1647 -- name, granularity info, size of result, degree of parallelism
1648 -- Same structure as _seq_ i.e. returns Int#
1649 -- KSW: v, the second arg in parAt# and parAtForNow#, is used only to determine
1650 -- `the processor containing the expression v'; it is not evaluated
1652 primop ParGlobalOp "parGlobal#" GenPrimOp
1653 a -> Int# -> Int# -> Int# -> Int# -> b -> Int#
1655 usage = { mangle ParGlobalOp [mkO, mkP, mkP, mkP, mkP, mkM] mkM }
1656 has_side_effects = True
1658 primop ParLocalOp "parLocal#" GenPrimOp
1659 a -> Int# -> Int# -> Int# -> Int# -> b -> Int#
1661 usage = { mangle ParLocalOp [mkO, mkP, mkP, mkP, mkP, mkM] mkM }
1662 has_side_effects = True
1664 primop ParAtOp "parAt#" GenPrimOp
1665 b -> a -> Int# -> Int# -> Int# -> Int# -> c -> Int#
1667 usage = { mangle ParAtOp [mkO, mkZ, mkP, mkP, mkP, mkP, mkM] mkM }
1668 has_side_effects = True
1670 primop ParAtAbsOp "parAtAbs#" GenPrimOp
1671 a -> Int# -> Int# -> Int# -> Int# -> Int# -> b -> Int#
1673 usage = { mangle ParAtAbsOp [mkO, mkP, mkP, mkP, mkP, mkM] mkM }
1674 has_side_effects = True
1676 primop ParAtRelOp "parAtRel#" GenPrimOp
1677 a -> Int# -> Int# -> Int# -> Int# -> Int# -> b -> Int#
1679 usage = { mangle ParAtRelOp [mkO, mkP, mkP, mkP, mkP, mkM] mkM }
1680 has_side_effects = True
1682 primop ParAtForNowOp "parAtForNow#" GenPrimOp
1683 b -> a -> Int# -> Int# -> Int# -> Int# -> c -> Int#
1685 usage = { mangle ParAtForNowOp [mkO, mkZ, mkP, mkP, mkP, mkP, mkM] mkM }
1686 has_side_effects = True
1688 -- copyable# and noFollow# are yet to be implemented (for GpH)
1690 --primop CopyableOp "copyable#" GenPrimOp
1693 -- usage = { mangle CopyableOp [mkZ] mkR }
1694 -- has_side_effects = True
1696 --primop NoFollowOp "noFollow#" GenPrimOp
1699 -- usage = { mangle NoFollowOp [mkZ] mkR }
1700 -- has_side_effects = True
1703 ------------------------------------------------------------------------
1704 section "Tag to enum stuff"
1705 {Convert back and forth between values of enumerated types
1706 and small integers.}
1707 ------------------------------------------------------------------------
1709 primop DataToTagOp "dataToTag#" GenPrimOp
1712 strictness = { \ arity -> mkStrictSig (mkTopDmdType [seqDmd] TopRes) }
1713 -- dataToTag# must have an evaluated argument
1715 primop TagToEnumOp "tagToEnum#" GenPrimOp
1718 ------------------------------------------------------------------------
1719 section "Bytecode operations"
1720 {Support for the bytecode interpreter and linker.}
1721 ------------------------------------------------------------------------
1724 {Primitive bytecode type.}
1726 primop AddrToHValueOp "addrToHValue#" GenPrimOp
1728 {Convert an {\tt Addr\#} to a followable type.}
1730 primop MkApUpd0_Op "mkApUpd0#" GenPrimOp
1735 primop NewBCOOp "newBCO#" GenPrimOp
1736 ByteArr# -> ByteArr# -> Array# a -> Int# -> ByteArr# -> State# s -> (# State# s, BCO# #)
1738 has_side_effects = True
1741 primop UnpackClosureOp "unpackClosure#" GenPrimOp
1742 a -> (# Addr#, Array# b, ByteArr# #)
1747 ------------------------------------------------------------------------
1749 {Miscellaneous built-ins}
1750 ------------------------------------------------------------------------
1754 { Evaluates its first argument to head normal form, and then returns its second
1755 argument as the result. }
1759 { The call {\tt (inline f)} arranges that f is inlined, regardless of its size.
1760 More precisely, the call {\tt (inline f)} rewrites to the right-hand side of
1761 {\tt f}'s definition. This allows the programmer to control inlining from a
1762 particular call site rather than the definition site of the function (c.f.
1763 {\tt INLINE} pragmas in User's Guide, Section 7.10.3, "INLINE and NOINLINE
1766 This inlining occurs regardless of the argument to the call or the size of
1767 {\tt f}'s definition; it is unconditional. The main caveat is that {\tt f}'s
1768 definition must be visible to the compiler. That is, {\tt f} must be
1769 {\tt let}-bound in the current scope. If no inlining takes place, the
1770 {\tt inline} function expands to the identity function in Phase zero; so its
1771 use imposes no overhead.
1773 If the function is defined in another module, GHC only exposes its inlining
1774 in the interface file if the function is sufficiently small that it might be
1775 inlined by the automatic mechanism. There is currently no way to tell GHC to
1776 expose arbitrarily-large functions in the interface file. (This shortcoming
1777 is something that could be fixed, with some kind of pragma.) }
1781 { The {\tt lazy} function restrains strictness analysis a little. The call
1782 {\tt (lazy e)} means the same as {\tt e}, but {\tt lazy} has a magical
1783 property so far as strictness analysis is concerned: it is lazy in its first
1784 argument, even though its semantics is strict. After strictness analysis has
1785 run, calls to {\tt lazy} are inlined to be the identity function.
1787 This behaviour is occasionally useful when controlling evaluation order.
1788 Notably, {\tt lazy} is used in the library definition of {\tt Control.Parallel.par}:
1790 {\tt par :: a -> b -> b}
1792 {\tt par x y = case (par\# x) of \_ -> lazy y}
1794 If {\tt lazy} were not lazy, {\tt par} would look strict in {\tt y} which
1795 would defeat the whole purpose of {\tt par}.
1797 Like {\tt seq}, the argument of {\tt lazy} can have an unboxed type. }
1800 { The type constructor {\tt Any} is type to which you can unsafely coerce any
1801 lifted type, and back.
1803 * It is lifted, and hence represented by a pointer
1805 * It does not claim to be a {\it data} type, and that's important for
1806 the code generator, because the code gen may {\it enter} a data value
1807 but never enters a function value.
1809 It's also used to instantiate un-constrained type variables after type
1810 checking. For example
1814 Annoyingly, we sometimes need {\tt Any}s of other kinds, such as {\tt (* -> *)} etc.
1815 This is a bit like tuples. We define a couple of useful ones here,
1816 and make others up on the fly. If any of these others end up being exported
1817 into interface files, we'll get a crash; at least until we add interface-file
1818 syntax to support them. }
1820 pseudoop "unsafeCoerce#"
1822 { The function {\tt unsafeCoerce\#} allows you to side-step the typechecker entirely. That
1823 is, it allows you to coerce any type into any other type. If you use this function,
1824 you had better get it right, otherwise segmentation faults await. It is generally
1825 used when you want to write a program that you know is well-typed, but where Haskell's
1826 type system is not expressive enough to prove that it is well typed.
1828 The argument to {\tt unsafeCoerce\#} can have unboxed types, although extremely bad
1829 things will happen if you coerce a boxed type to an unboxed type. }
1832 ------------------------------------------------------------------------
1834 ------------------------------------------------------------------------