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 IntGcdOp "gcdInt#" Dyadic Int# -> Int# -> Int#
223 with out_of_line = True
225 primop IntNegOp "negateInt#" Monadic Int# -> Int#
226 primop IntAddCOp "addIntC#" GenPrimOp Int# -> Int# -> (# Int#, Int# #)
227 {Add with carry. First member of result is (wrapped) sum;
228 second member is 0 iff no overflow occured.}
229 primop IntSubCOp "subIntC#" GenPrimOp Int# -> Int# -> (# Int#, Int# #)
230 {Subtract with carry. First member of result is (wrapped) difference;
231 second member is 0 iff no overflow occured.}
233 primop IntGtOp ">#" Compare Int# -> Int# -> Bool
234 primop IntGeOp ">=#" Compare Int# -> Int# -> Bool
236 primop IntEqOp "==#" Compare
238 with commutable = True
240 primop IntNeOp "/=#" Compare
242 with commutable = True
244 primop IntLtOp "<#" Compare Int# -> Int# -> Bool
245 primop IntLeOp "<=#" Compare Int# -> Int# -> Bool
247 primop ChrOp "chr#" GenPrimOp Int# -> Char#
249 primop Int2WordOp "int2Word#" GenPrimOp Int# -> Word#
250 primop Int2FloatOp "int2Float#" GenPrimOp Int# -> Float#
251 primop Int2DoubleOp "int2Double#" GenPrimOp Int# -> Double#
253 primop Int2IntegerOp "int2Integer#"
254 GenPrimOp Int# -> (# Int#, ByteArray# #)
255 with out_of_line = True
257 primop ISllOp "uncheckedIShiftL#" GenPrimOp Int# -> Int# -> Int#
258 {Shift left. Result undefined if shift amount is not
259 in the range 0 to word size - 1 inclusive.}
260 primop ISraOp "uncheckedIShiftRA#" GenPrimOp Int# -> Int# -> Int#
261 {Shift right arithmetic. Result undefined if shift amount is not
262 in the range 0 to word size - 1 inclusive.}
263 primop ISrlOp "uncheckedIShiftRL#" GenPrimOp Int# -> Int# -> Int#
264 {Shift right logical. Result undefined if shift amount is not
265 in the range 0 to word size - 1 inclusive.}
267 ------------------------------------------------------------------------
269 {Operations on native-sized unsigned words (30+ bits).}
270 ------------------------------------------------------------------------
274 primop WordAddOp "plusWord#" Dyadic Word# -> Word# -> Word#
275 with commutable = True
277 primop WordSubOp "minusWord#" Dyadic Word# -> Word# -> Word#
279 primop WordMulOp "timesWord#" Dyadic Word# -> Word# -> Word#
280 with commutable = True
282 primop WordQuotOp "quotWord#" Dyadic Word# -> Word# -> Word#
285 primop WordRemOp "remWord#" Dyadic Word# -> Word# -> Word#
288 primop AndOp "and#" Dyadic Word# -> Word# -> Word#
289 with commutable = True
291 primop OrOp "or#" Dyadic Word# -> Word# -> Word#
292 with commutable = True
294 primop XorOp "xor#" Dyadic Word# -> Word# -> Word#
295 with commutable = True
297 primop NotOp "not#" Monadic Word# -> Word#
299 primop SllOp "uncheckedShiftL#" GenPrimOp Word# -> Int# -> Word#
300 {Shift left logical. Result undefined if shift amount is not
301 in the range 0 to word size - 1 inclusive.}
302 primop SrlOp "uncheckedShiftRL#" GenPrimOp Word# -> Int# -> Word#
303 {Shift right logical. Result undefined if shift amount is not
304 in the range 0 to word size - 1 inclusive.}
306 primop Word2IntOp "word2Int#" GenPrimOp Word# -> Int#
308 primop Word2IntegerOp "word2Integer#" GenPrimOp
309 Word# -> (# Int#, ByteArray# #)
310 with out_of_line = True
312 primop WordGtOp "gtWord#" Compare Word# -> Word# -> Bool
313 primop WordGeOp "geWord#" Compare Word# -> Word# -> Bool
314 primop WordEqOp "eqWord#" Compare Word# -> Word# -> Bool
315 primop WordNeOp "neWord#" Compare Word# -> Word# -> Bool
316 primop WordLtOp "ltWord#" Compare Word# -> Word# -> Bool
317 primop WordLeOp "leWord#" Compare Word# -> Word# -> Bool
319 ------------------------------------------------------------------------
321 {Explicit narrowing of native-sized ints or words.}
322 ------------------------------------------------------------------------
324 primop Narrow8IntOp "narrow8Int#" Monadic Int# -> Int#
325 primop Narrow16IntOp "narrow16Int#" Monadic Int# -> Int#
326 primop Narrow32IntOp "narrow32Int#" Monadic Int# -> Int#
327 primop Narrow8WordOp "narrow8Word#" Monadic Word# -> Word#
328 primop Narrow16WordOp "narrow16Word#" Monadic Word# -> Word#
329 primop Narrow32WordOp "narrow32Word#" Monadic Word# -> Word#
332 #if WORD_SIZE_IN_BITS < 32
333 ------------------------------------------------------------------------
335 {Operations on 32-bit integers ({\tt Int32\#}). This type is only used
336 if plain {\tt Int\#} has less than 32 bits. In any case, the operations
337 are not primops; they are implemented (if needed) as ccalls instead.}
338 ------------------------------------------------------------------------
342 primop Int32ToIntegerOp "int32ToInteger#" GenPrimOp
343 Int32# -> (# Int#, ByteArray# #)
344 with out_of_line = True
347 ------------------------------------------------------------------------
349 {Operations on 32-bit unsigned words. This type is only used
350 if plain {\tt Word\#} has less than 32 bits. In any case, the operations
351 are not primops; they are implemented (if needed) as ccalls instead.}
352 ------------------------------------------------------------------------
356 primop Word32ToIntegerOp "word32ToInteger#" GenPrimOp
357 Word32# -> (# Int#, ByteArray# #)
358 with out_of_line = True
364 #if WORD_SIZE_IN_BITS < 64
365 ------------------------------------------------------------------------
367 {Operations on 64-bit unsigned words. This type is only used
368 if plain {\tt Int\#} has less than 64 bits. In any case, the operations
369 are not primops; they are implemented (if needed) as ccalls instead.}
370 ------------------------------------------------------------------------
374 primop Int64ToIntegerOp "int64ToInteger#" GenPrimOp
375 Int64# -> (# Int#, ByteArray# #)
376 with out_of_line = True
378 ------------------------------------------------------------------------
380 {Operations on 64-bit unsigned words. This type is only used
381 if plain {\tt Word\#} has less than 64 bits. In any case, the operations
382 are not primops; they are implemented (if needed) as ccalls instead.}
383 ------------------------------------------------------------------------
387 primop Word64ToIntegerOp "word64ToInteger#" GenPrimOp
388 Word64# -> (# Int#, ByteArray# #)
389 with out_of_line = True
393 ------------------------------------------------------------------------
395 {Operations on arbitrary-precision integers. These operations are
396 implemented via the GMP package. An integer is represented as a pair
397 consisting of an {\tt Int\#} representing the number of 'limbs' in use and
398 the sign, and a {\tt ByteArray\#} containing the 'limbs' themselves. Such pairs
399 are returned as unboxed pairs, but must be passed as separate
402 For .NET these operations are implemented by foreign imports, so the
403 primops are omitted.}
404 ------------------------------------------------------------------------
408 primop IntegerAddOp "plusInteger#" GenPrimOp
409 Int# -> ByteArray# -> Int# -> ByteArray# -> (# Int#, ByteArray# #)
410 with commutable = True
413 primop IntegerSubOp "minusInteger#" GenPrimOp
414 Int# -> ByteArray# -> Int# -> ByteArray# -> (# Int#, ByteArray# #)
415 with out_of_line = True
417 primop IntegerMulOp "timesInteger#" GenPrimOp
418 Int# -> ByteArray# -> Int# -> ByteArray# -> (# Int#, ByteArray# #)
419 with commutable = True
422 primop IntegerGcdOp "gcdInteger#" GenPrimOp
423 Int# -> ByteArray# -> Int# -> ByteArray# -> (# Int#, ByteArray# #)
424 {Greatest common divisor.}
425 with commutable = True
428 primop IntegerIntGcdOp "gcdIntegerInt#" GenPrimOp
429 Int# -> ByteArray# -> Int# -> Int#
430 {Greatest common divisor, where second argument is an ordinary {\tt Int\#}.}
431 with out_of_line = True
433 primop IntegerDivExactOp "divExactInteger#" GenPrimOp
434 Int# -> ByteArray# -> Int# -> ByteArray# -> (# Int#, ByteArray# #)
435 {Divisor is guaranteed to be a factor of dividend.}
436 with out_of_line = True
438 primop IntegerQuotOp "quotInteger#" GenPrimOp
439 Int# -> ByteArray# -> Int# -> ByteArray# -> (# Int#, ByteArray# #)
440 {Rounds towards zero.}
441 with out_of_line = True
443 primop IntegerRemOp "remInteger#" GenPrimOp
444 Int# -> ByteArray# -> Int# -> ByteArray# -> (# Int#, ByteArray# #)
445 {Satisfies \texttt{plusInteger\# (timesInteger\# (quotInteger\# x y) y) (remInteger\# x y) == x}.}
446 with out_of_line = True
448 primop IntegerCmpOp "cmpInteger#" GenPrimOp
449 Int# -> ByteArray# -> Int# -> ByteArray# -> Int#
450 {Returns -1,0,1 according as first argument is less than, equal to, or greater than second argument.}
451 with needs_wrapper = True
454 primop IntegerCmpIntOp "cmpIntegerInt#" GenPrimOp
455 Int# -> ByteArray# -> Int# -> Int#
456 {Returns -1,0,1 according as first argument is less than, equal to, or greater than second argument, which
457 is an ordinary Int\#.}
458 with needs_wrapper = True
461 primop IntegerQuotRemOp "quotRemInteger#" GenPrimOp
462 Int# -> ByteArray# -> Int# -> ByteArray# -> (# Int#, ByteArray#, Int#, ByteArray# #)
463 {Compute quot and rem simulaneously.}
467 primop IntegerDivModOp "divModInteger#" GenPrimOp
468 Int# -> ByteArray# -> Int# -> ByteArray# -> (# Int#, ByteArray#, Int#, ByteArray# #)
469 {Compute div and mod simultaneously, where div rounds towards negative infinity
470 and\texttt{(q,r) = divModInteger\#(x,y)} implies \texttt{plusInteger\# (timesInteger\# q y) r = x}.}
474 primop Integer2IntOp "integer2Int#" GenPrimOp
475 Int# -> ByteArray# -> Int#
476 with needs_wrapper = True
479 primop Integer2WordOp "integer2Word#" GenPrimOp
480 Int# -> ByteArray# -> Word#
481 with needs_wrapper = True
484 #if WORD_SIZE_IN_BITS < 32
485 primop IntegerToInt32Op "integerToInt32#" GenPrimOp
486 Int# -> ByteArray# -> Int32#
488 primop IntegerToWord32Op "integerToWord32#" GenPrimOp
489 Int# -> ByteArray# -> Word32#
492 primop IntegerAndOp "andInteger#" GenPrimOp
493 Int# -> ByteArray# -> Int# -> ByteArray# -> (# Int#, ByteArray# #)
494 with out_of_line = True
496 primop IntegerOrOp "orInteger#" GenPrimOp
497 Int# -> ByteArray# -> Int# -> ByteArray# -> (# Int#, ByteArray# #)
498 with out_of_line = True
500 primop IntegerXorOp "xorInteger#" GenPrimOp
501 Int# -> ByteArray# -> Int# -> ByteArray# -> (# Int#, ByteArray# #)
502 with out_of_line = True
504 primop IntegerComplementOp "complementInteger#" GenPrimOp
505 Int# -> ByteArray# -> (# Int#, ByteArray# #)
506 with out_of_line = True
508 #endif /* ndef ILX */
510 ------------------------------------------------------------------------
512 {Operations on double-precision (64 bit) floating-point numbers.}
513 ------------------------------------------------------------------------
517 primop DoubleGtOp ">##" Compare Double# -> Double# -> Bool
518 primop DoubleGeOp ">=##" Compare Double# -> Double# -> Bool
520 primop DoubleEqOp "==##" Compare
521 Double# -> Double# -> Bool
522 with commutable = True
524 primop DoubleNeOp "/=##" Compare
525 Double# -> Double# -> Bool
526 with commutable = True
528 primop DoubleLtOp "<##" Compare Double# -> Double# -> Bool
529 primop DoubleLeOp "<=##" Compare Double# -> Double# -> Bool
531 primop DoubleAddOp "+##" Dyadic
532 Double# -> Double# -> Double#
533 with commutable = True
535 primop DoubleSubOp "-##" Dyadic Double# -> Double# -> Double#
537 primop DoubleMulOp "*##" Dyadic
538 Double# -> Double# -> Double#
539 with commutable = True
541 primop DoubleDivOp "/##" Dyadic
542 Double# -> Double# -> Double#
545 primop DoubleNegOp "negateDouble#" Monadic Double# -> Double#
547 primop Double2IntOp "double2Int#" GenPrimOp Double# -> Int#
548 {Truncates a {\tt Double#} value to the nearest {\tt Int#}.
549 Results are undefined if the truncation if truncation yields
550 a value outside the range of {\tt Int#}.}
552 primop Double2FloatOp "double2Float#" GenPrimOp Double# -> Float#
554 primop DoubleExpOp "expDouble#" Monadic
556 with needs_wrapper = True
558 primop DoubleLogOp "logDouble#" Monadic
564 primop DoubleSqrtOp "sqrtDouble#" Monadic
566 with needs_wrapper = True
568 primop DoubleSinOp "sinDouble#" Monadic
570 with needs_wrapper = True
572 primop DoubleCosOp "cosDouble#" Monadic
574 with needs_wrapper = True
576 primop DoubleTanOp "tanDouble#" Monadic
578 with needs_wrapper = True
580 primop DoubleAsinOp "asinDouble#" Monadic
586 primop DoubleAcosOp "acosDouble#" Monadic
592 primop DoubleAtanOp "atanDouble#" Monadic
597 primop DoubleSinhOp "sinhDouble#" Monadic
599 with needs_wrapper = True
601 primop DoubleCoshOp "coshDouble#" Monadic
603 with needs_wrapper = True
605 primop DoubleTanhOp "tanhDouble#" Monadic
607 with needs_wrapper = True
609 primop DoublePowerOp "**##" Dyadic
610 Double# -> Double# -> Double#
612 with needs_wrapper = True
614 primop DoubleDecodeOp "decodeDouble#" GenPrimOp
615 Double# -> (# Int#, Int#, ByteArray# #)
616 {Convert to arbitrary-precision integer.
617 First {\tt Int\#} in result is the exponent; second {\tt Int\#} and {\tt ByteArray\#}
618 represent an {\tt Integer\#} holding the mantissa.}
619 with out_of_line = True
621 primop DoubleDecode_2IntOp "decodeDouble_2Int#" GenPrimOp
622 Double# -> (# Int#, Word#, Word#, Int# #)
623 {Convert to arbitrary-precision integer.
624 First component of the result is -1 or 1, indicating the sign of the
625 mantissa. The next two are the high and low 32 bits of the mantissa
626 respectively, and the last is the exponent.}
627 with out_of_line = True
629 ------------------------------------------------------------------------
631 {Operations on single-precision (32-bit) floating-point numbers.}
632 ------------------------------------------------------------------------
636 primop FloatGtOp "gtFloat#" Compare Float# -> Float# -> Bool
637 primop FloatGeOp "geFloat#" Compare Float# -> Float# -> Bool
639 primop FloatEqOp "eqFloat#" Compare
640 Float# -> Float# -> Bool
641 with commutable = True
643 primop FloatNeOp "neFloat#" Compare
644 Float# -> Float# -> Bool
645 with commutable = True
647 primop FloatLtOp "ltFloat#" Compare Float# -> Float# -> Bool
648 primop FloatLeOp "leFloat#" Compare Float# -> Float# -> Bool
650 primop FloatAddOp "plusFloat#" Dyadic
651 Float# -> Float# -> Float#
652 with commutable = True
654 primop FloatSubOp "minusFloat#" Dyadic Float# -> Float# -> Float#
656 primop FloatMulOp "timesFloat#" Dyadic
657 Float# -> Float# -> Float#
658 with commutable = True
660 primop FloatDivOp "divideFloat#" Dyadic
661 Float# -> Float# -> Float#
664 primop FloatNegOp "negateFloat#" Monadic Float# -> Float#
666 primop Float2IntOp "float2Int#" GenPrimOp Float# -> Int#
667 {Truncates a {\tt Float#} value to the nearest {\tt Int#}.
668 Results are undefined if the truncation if truncation yields
669 a value outside the range of {\tt Int#}.}
671 primop FloatExpOp "expFloat#" Monadic
673 with needs_wrapper = True
675 primop FloatLogOp "logFloat#" Monadic
677 with needs_wrapper = True
680 primop FloatSqrtOp "sqrtFloat#" Monadic
682 with needs_wrapper = True
684 primop FloatSinOp "sinFloat#" Monadic
686 with needs_wrapper = True
688 primop FloatCosOp "cosFloat#" Monadic
690 with needs_wrapper = True
692 primop FloatTanOp "tanFloat#" Monadic
694 with needs_wrapper = True
696 primop FloatAsinOp "asinFloat#" Monadic
698 with needs_wrapper = True
701 primop FloatAcosOp "acosFloat#" Monadic
703 with needs_wrapper = True
706 primop FloatAtanOp "atanFloat#" Monadic
708 with needs_wrapper = True
710 primop FloatSinhOp "sinhFloat#" Monadic
712 with needs_wrapper = True
714 primop FloatCoshOp "coshFloat#" Monadic
716 with needs_wrapper = True
718 primop FloatTanhOp "tanhFloat#" Monadic
720 with needs_wrapper = True
722 primop FloatPowerOp "powerFloat#" Dyadic
723 Float# -> Float# -> Float#
724 with needs_wrapper = True
726 primop Float2DoubleOp "float2Double#" GenPrimOp Float# -> Double#
728 primop FloatDecodeOp "decodeFloat#" GenPrimOp
729 Float# -> (# Int#, Int#, ByteArray# #)
730 {Convert to arbitrary-precision integer.
731 First {\tt Int\#} in result is the exponent; second {\tt Int\#} and {\tt ByteArray\#}
732 represent an {\tt Integer\#} holding the mantissa.}
733 with out_of_line = True
735 primop FloatDecode_IntOp "decodeFloat_Int#" GenPrimOp
736 Float# -> (# Int#, Int# #)
737 {Convert to arbitrary-precision integer.
738 First {\tt Int\#} in result is the mantissa; second is the exponent.}
739 with out_of_line = True
741 ------------------------------------------------------------------------
743 {Operations on {\tt Array\#}.}
744 ------------------------------------------------------------------------
748 primtype MutableArray# s a
750 primop NewArrayOp "newArray#" GenPrimOp
751 Int# -> a -> State# s -> (# State# s, MutableArray# s a #)
752 {Create a new mutable array of specified size (in bytes),
753 in the specified state thread,
754 with each element containing the specified initial value.}
757 has_side_effects = True
759 primop SameMutableArrayOp "sameMutableArray#" GenPrimOp
760 MutableArray# s a -> MutableArray# s a -> Bool
762 primop ReadArrayOp "readArray#" GenPrimOp
763 MutableArray# s a -> Int# -> State# s -> (# State# s, a #)
764 {Read from specified index of mutable array. Result is not yet evaluated.}
766 has_side_effects = True
768 primop WriteArrayOp "writeArray#" GenPrimOp
769 MutableArray# s a -> Int# -> a -> State# s -> State# s
770 {Write to specified index of mutable array.}
772 has_side_effects = True
774 primop IndexArrayOp "indexArray#" GenPrimOp
775 Array# a -> Int# -> (# a #)
776 {Read from specified index of immutable array. Result is packaged into
777 an unboxed singleton; the result itself is not yet evaluated.}
779 primop UnsafeFreezeArrayOp "unsafeFreezeArray#" GenPrimOp
780 MutableArray# s a -> State# s -> (# State# s, Array# a #)
781 {Make a mutable array immutable, without copying.}
783 has_side_effects = True
785 primop UnsafeThawArrayOp "unsafeThawArray#" GenPrimOp
786 Array# a -> State# s -> (# State# s, MutableArray# s a #)
787 {Make an immutable array mutable, without copying.}
790 has_side_effects = True
792 ------------------------------------------------------------------------
793 section "Byte Arrays"
794 {Operations on {\tt ByteArray\#}. A {\tt ByteArray\#} is a just a region of
795 raw memory in the garbage-collected heap, which is not scanned
796 for pointers. It carries its own size (in bytes). There are
797 three sets of operations for accessing byte array contents:
798 index for reading from immutable byte arrays, and read/write
799 for mutable byte arrays. Each set contains operations for
800 a range of useful primitive data types. Each operation takes
801 an offset measured in terms of the size fo the primitive type
802 being read or written.}
804 ------------------------------------------------------------------------
808 primtype MutableByteArray# s
810 primop NewByteArrayOp_Char "newByteArray#" GenPrimOp
811 Int# -> State# s -> (# State# s, MutableByteArray# s #)
812 {Create a new mutable byte array of specified size (in bytes), in
813 the specified state thread.}
814 with out_of_line = True
815 has_side_effects = True
817 primop NewPinnedByteArrayOp_Char "newPinnedByteArray#" GenPrimOp
818 Int# -> State# s -> (# State# s, MutableByteArray# s #)
819 {Create a mutable byte array that the GC guarantees not to move.}
820 with out_of_line = True
821 has_side_effects = True
823 primop NewAlignedPinnedByteArrayOp_Char "newAlignedPinnedByteArray#" GenPrimOp
824 Int# -> Int# -> State# s -> (# State# s, MutableByteArray# s #)
825 {Create a mutable byte array, aligned by the specified amount, that the GC guarantees not to move.}
826 with out_of_line = True
827 has_side_effects = True
829 primop ByteArrayContents_Char "byteArrayContents#" GenPrimOp
831 {Intended for use with pinned arrays; otherwise very unsafe!}
833 primop SameMutableByteArrayOp "sameMutableByteArray#" GenPrimOp
834 MutableByteArray# s -> MutableByteArray# s -> Bool
836 primop UnsafeFreezeByteArrayOp "unsafeFreezeByteArray#" GenPrimOp
837 MutableByteArray# s -> State# s -> (# State# s, ByteArray# #)
838 {Make a mutable byte array immutable, without copying.}
840 has_side_effects = True
842 primop SizeofByteArrayOp "sizeofByteArray#" GenPrimOp
845 primop SizeofMutableByteArrayOp "sizeofMutableByteArray#" GenPrimOp
846 MutableByteArray# s -> Int#
849 primop IndexByteArrayOp_Char "indexCharArray#" GenPrimOp
850 ByteArray# -> Int# -> Char#
851 {Read 8-bit character; offset in bytes.}
853 primop IndexByteArrayOp_WideChar "indexWideCharArray#" GenPrimOp
854 ByteArray# -> Int# -> Char#
855 {Read 31-bit character; offset in 4-byte words.}
857 primop IndexByteArrayOp_Int "indexIntArray#" GenPrimOp
858 ByteArray# -> Int# -> Int#
860 primop IndexByteArrayOp_Word "indexWordArray#" GenPrimOp
861 ByteArray# -> Int# -> Word#
863 primop IndexByteArrayOp_Addr "indexAddrArray#" GenPrimOp
864 ByteArray# -> Int# -> Addr#
866 primop IndexByteArrayOp_Float "indexFloatArray#" GenPrimOp
867 ByteArray# -> Int# -> Float#
869 primop IndexByteArrayOp_Double "indexDoubleArray#" GenPrimOp
870 ByteArray# -> Int# -> Double#
872 primop IndexByteArrayOp_StablePtr "indexStablePtrArray#" GenPrimOp
873 ByteArray# -> Int# -> StablePtr# a
875 primop IndexByteArrayOp_Int8 "indexInt8Array#" GenPrimOp
876 ByteArray# -> Int# -> Int#
878 primop IndexByteArrayOp_Int16 "indexInt16Array#" GenPrimOp
879 ByteArray# -> Int# -> Int#
881 primop IndexByteArrayOp_Int32 "indexInt32Array#" GenPrimOp
882 ByteArray# -> Int# -> INT32
884 primop IndexByteArrayOp_Int64 "indexInt64Array#" GenPrimOp
885 ByteArray# -> Int# -> INT64
887 primop IndexByteArrayOp_Word8 "indexWord8Array#" GenPrimOp
888 ByteArray# -> Int# -> Word#
890 primop IndexByteArrayOp_Word16 "indexWord16Array#" GenPrimOp
891 ByteArray# -> Int# -> Word#
893 primop IndexByteArrayOp_Word32 "indexWord32Array#" GenPrimOp
894 ByteArray# -> Int# -> WORD32
896 primop IndexByteArrayOp_Word64 "indexWord64Array#" GenPrimOp
897 ByteArray# -> Int# -> WORD64
899 primop ReadByteArrayOp_Char "readCharArray#" GenPrimOp
900 MutableByteArray# s -> Int# -> State# s -> (# State# s, Char# #)
901 {Read 8-bit character; offset in bytes.}
902 with has_side_effects = True
904 primop ReadByteArrayOp_WideChar "readWideCharArray#" GenPrimOp
905 MutableByteArray# s -> Int# -> State# s -> (# State# s, Char# #)
906 {Read 31-bit character; offset in 4-byte words.}
907 with has_side_effects = True
909 primop ReadByteArrayOp_Int "readIntArray#" GenPrimOp
910 MutableByteArray# s -> Int# -> State# s -> (# State# s, Int# #)
911 with has_side_effects = True
913 primop ReadByteArrayOp_Word "readWordArray#" GenPrimOp
914 MutableByteArray# s -> Int# -> State# s -> (# State# s, Word# #)
915 with has_side_effects = True
917 primop ReadByteArrayOp_Addr "readAddrArray#" GenPrimOp
918 MutableByteArray# s -> Int# -> State# s -> (# State# s, Addr# #)
919 with has_side_effects = True
921 primop ReadByteArrayOp_Float "readFloatArray#" GenPrimOp
922 MutableByteArray# s -> Int# -> State# s -> (# State# s, Float# #)
923 with has_side_effects = True
925 primop ReadByteArrayOp_Double "readDoubleArray#" GenPrimOp
926 MutableByteArray# s -> Int# -> State# s -> (# State# s, Double# #)
927 with has_side_effects = True
929 primop ReadByteArrayOp_StablePtr "readStablePtrArray#" GenPrimOp
930 MutableByteArray# s -> Int# -> State# s -> (# State# s, StablePtr# a #)
931 with has_side_effects = True
933 primop ReadByteArrayOp_Int8 "readInt8Array#" GenPrimOp
934 MutableByteArray# s -> Int# -> State# s -> (# State# s, Int# #)
935 with has_side_effects = True
937 primop ReadByteArrayOp_Int16 "readInt16Array#" GenPrimOp
938 MutableByteArray# s -> Int# -> State# s -> (# State# s, Int# #)
939 with has_side_effects = True
941 primop ReadByteArrayOp_Int32 "readInt32Array#" GenPrimOp
942 MutableByteArray# s -> Int# -> State# s -> (# State# s, INT32 #)
943 with has_side_effects = True
945 primop ReadByteArrayOp_Int64 "readInt64Array#" GenPrimOp
946 MutableByteArray# s -> Int# -> State# s -> (# State# s, INT64 #)
947 with has_side_effects = True
949 primop ReadByteArrayOp_Word8 "readWord8Array#" GenPrimOp
950 MutableByteArray# s -> Int# -> State# s -> (# State# s, Word# #)
951 with has_side_effects = True
953 primop ReadByteArrayOp_Word16 "readWord16Array#" GenPrimOp
954 MutableByteArray# s -> Int# -> State# s -> (# State# s, Word# #)
955 with has_side_effects = True
957 primop ReadByteArrayOp_Word32 "readWord32Array#" GenPrimOp
958 MutableByteArray# s -> Int# -> State# s -> (# State# s, WORD32 #)
959 with has_side_effects = True
961 primop ReadByteArrayOp_Word64 "readWord64Array#" GenPrimOp
962 MutableByteArray# s -> Int# -> State# s -> (# State# s, WORD64 #)
963 with has_side_effects = True
965 primop WriteByteArrayOp_Char "writeCharArray#" GenPrimOp
966 MutableByteArray# s -> Int# -> Char# -> State# s -> State# s
967 {Write 8-bit character; offset in bytes.}
968 with has_side_effects = True
970 primop WriteByteArrayOp_WideChar "writeWideCharArray#" GenPrimOp
971 MutableByteArray# s -> Int# -> Char# -> State# s -> State# s
972 {Write 31-bit character; offset in 4-byte words.}
973 with has_side_effects = True
975 primop WriteByteArrayOp_Int "writeIntArray#" GenPrimOp
976 MutableByteArray# s -> Int# -> Int# -> State# s -> State# s
977 with has_side_effects = True
979 primop WriteByteArrayOp_Word "writeWordArray#" GenPrimOp
980 MutableByteArray# s -> Int# -> Word# -> State# s -> State# s
981 with has_side_effects = True
983 primop WriteByteArrayOp_Addr "writeAddrArray#" GenPrimOp
984 MutableByteArray# s -> Int# -> Addr# -> State# s -> State# s
985 with has_side_effects = True
987 primop WriteByteArrayOp_Float "writeFloatArray#" GenPrimOp
988 MutableByteArray# s -> Int# -> Float# -> State# s -> State# s
989 with has_side_effects = True
991 primop WriteByteArrayOp_Double "writeDoubleArray#" GenPrimOp
992 MutableByteArray# s -> Int# -> Double# -> State# s -> State# s
993 with has_side_effects = True
995 primop WriteByteArrayOp_StablePtr "writeStablePtrArray#" GenPrimOp
996 MutableByteArray# s -> Int# -> StablePtr# a -> State# s -> State# s
997 with has_side_effects = True
999 primop WriteByteArrayOp_Int8 "writeInt8Array#" GenPrimOp
1000 MutableByteArray# s -> Int# -> Int# -> State# s -> State# s
1001 with has_side_effects = True
1003 primop WriteByteArrayOp_Int16 "writeInt16Array#" GenPrimOp
1004 MutableByteArray# s -> Int# -> Int# -> State# s -> State# s
1005 with has_side_effects = True
1007 primop WriteByteArrayOp_Int32 "writeInt32Array#" GenPrimOp
1008 MutableByteArray# s -> Int# -> INT32 -> State# s -> State# s
1009 with has_side_effects = True
1011 primop WriteByteArrayOp_Int64 "writeInt64Array#" GenPrimOp
1012 MutableByteArray# s -> Int# -> INT64 -> State# s -> State# s
1013 with has_side_effects = True
1015 primop WriteByteArrayOp_Word8 "writeWord8Array#" GenPrimOp
1016 MutableByteArray# s -> Int# -> Word# -> State# s -> State# s
1017 with has_side_effects = True
1019 primop WriteByteArrayOp_Word16 "writeWord16Array#" GenPrimOp
1020 MutableByteArray# s -> Int# -> Word# -> State# s -> State# s
1021 with has_side_effects = True
1023 primop WriteByteArrayOp_Word32 "writeWord32Array#" GenPrimOp
1024 MutableByteArray# s -> Int# -> WORD32 -> State# s -> State# s
1025 with has_side_effects = True
1027 primop WriteByteArrayOp_Word64 "writeWord64Array#" GenPrimOp
1028 MutableByteArray# s -> Int# -> WORD64 -> State# s -> State# s
1029 with has_side_effects = True
1031 ------------------------------------------------------------------------
1033 ------------------------------------------------------------------------
1036 { An arbitrary machine address assumed to point outside
1037 the garbage-collected heap. }
1039 pseudoop "nullAddr#" Addr#
1040 { The null address. }
1042 primop AddrAddOp "plusAddr#" GenPrimOp Addr# -> Int# -> Addr#
1043 primop AddrSubOp "minusAddr#" GenPrimOp Addr# -> Addr# -> Int#
1044 {Result is meaningless if two {\tt Addr\#}s are so far apart that their
1045 difference doesn't fit in an {\tt Int\#}.}
1046 primop AddrRemOp "remAddr#" GenPrimOp Addr# -> Int# -> Int#
1047 {Return the remainder when the {\tt Addr\#} arg, treated like an {\tt Int\#},
1048 is divided by the {\tt Int\#} arg.}
1049 #if (WORD_SIZE_IN_BITS == 32 || WORD_SIZE_IN_BITS == 64)
1050 primop Addr2IntOp "addr2Int#" GenPrimOp Addr# -> Int#
1051 {Coerce directly from address to int. Strongly deprecated.}
1052 primop Int2AddrOp "int2Addr#" GenPrimOp Int# -> Addr#
1053 {Coerce directly from int to address. Strongly deprecated.}
1056 primop AddrGtOp "gtAddr#" Compare Addr# -> Addr# -> Bool
1057 primop AddrGeOp "geAddr#" Compare Addr# -> Addr# -> Bool
1058 primop AddrEqOp "eqAddr#" Compare Addr# -> Addr# -> Bool
1059 primop AddrNeOp "neAddr#" Compare Addr# -> Addr# -> Bool
1060 primop AddrLtOp "ltAddr#" Compare Addr# -> Addr# -> Bool
1061 primop AddrLeOp "leAddr#" Compare Addr# -> Addr# -> Bool
1063 primop IndexOffAddrOp_Char "indexCharOffAddr#" GenPrimOp
1064 Addr# -> Int# -> Char#
1065 {Reads 8-bit character; offset in bytes.}
1067 primop IndexOffAddrOp_WideChar "indexWideCharOffAddr#" GenPrimOp
1068 Addr# -> Int# -> Char#
1069 {Reads 31-bit character; offset in 4-byte words.}
1071 primop IndexOffAddrOp_Int "indexIntOffAddr#" GenPrimOp
1072 Addr# -> Int# -> Int#
1074 primop IndexOffAddrOp_Word "indexWordOffAddr#" GenPrimOp
1075 Addr# -> Int# -> Word#
1077 primop IndexOffAddrOp_Addr "indexAddrOffAddr#" GenPrimOp
1078 Addr# -> Int# -> Addr#
1080 primop IndexOffAddrOp_Float "indexFloatOffAddr#" GenPrimOp
1081 Addr# -> Int# -> Float#
1083 primop IndexOffAddrOp_Double "indexDoubleOffAddr#" GenPrimOp
1084 Addr# -> Int# -> Double#
1086 primop IndexOffAddrOp_StablePtr "indexStablePtrOffAddr#" GenPrimOp
1087 Addr# -> Int# -> StablePtr# a
1089 primop IndexOffAddrOp_Int8 "indexInt8OffAddr#" GenPrimOp
1090 Addr# -> Int# -> Int#
1092 primop IndexOffAddrOp_Int16 "indexInt16OffAddr#" GenPrimOp
1093 Addr# -> Int# -> Int#
1095 primop IndexOffAddrOp_Int32 "indexInt32OffAddr#" GenPrimOp
1096 Addr# -> Int# -> INT32
1098 primop IndexOffAddrOp_Int64 "indexInt64OffAddr#" GenPrimOp
1099 Addr# -> Int# -> INT64
1101 primop IndexOffAddrOp_Word8 "indexWord8OffAddr#" GenPrimOp
1102 Addr# -> Int# -> Word#
1104 primop IndexOffAddrOp_Word16 "indexWord16OffAddr#" GenPrimOp
1105 Addr# -> Int# -> Word#
1107 primop IndexOffAddrOp_Word32 "indexWord32OffAddr#" GenPrimOp
1108 Addr# -> Int# -> WORD32
1110 primop IndexOffAddrOp_Word64 "indexWord64OffAddr#" GenPrimOp
1111 Addr# -> Int# -> WORD64
1113 primop ReadOffAddrOp_Char "readCharOffAddr#" GenPrimOp
1114 Addr# -> Int# -> State# s -> (# State# s, Char# #)
1115 {Reads 8-bit character; offset in bytes.}
1116 with has_side_effects = True
1118 primop ReadOffAddrOp_WideChar "readWideCharOffAddr#" GenPrimOp
1119 Addr# -> Int# -> State# s -> (# State# s, Char# #)
1120 {Reads 31-bit character; offset in 4-byte words.}
1121 with has_side_effects = True
1123 primop ReadOffAddrOp_Int "readIntOffAddr#" GenPrimOp
1124 Addr# -> Int# -> State# s -> (# State# s, Int# #)
1125 with has_side_effects = True
1127 primop ReadOffAddrOp_Word "readWordOffAddr#" GenPrimOp
1128 Addr# -> Int# -> State# s -> (# State# s, Word# #)
1129 with has_side_effects = True
1131 primop ReadOffAddrOp_Addr "readAddrOffAddr#" GenPrimOp
1132 Addr# -> Int# -> State# s -> (# State# s, Addr# #)
1133 with has_side_effects = True
1135 primop ReadOffAddrOp_Float "readFloatOffAddr#" GenPrimOp
1136 Addr# -> Int# -> State# s -> (# State# s, Float# #)
1137 with has_side_effects = True
1139 primop ReadOffAddrOp_Double "readDoubleOffAddr#" GenPrimOp
1140 Addr# -> Int# -> State# s -> (# State# s, Double# #)
1141 with has_side_effects = True
1143 primop ReadOffAddrOp_StablePtr "readStablePtrOffAddr#" GenPrimOp
1144 Addr# -> Int# -> State# s -> (# State# s, StablePtr# a #)
1145 with has_side_effects = True
1147 primop ReadOffAddrOp_Int8 "readInt8OffAddr#" GenPrimOp
1148 Addr# -> Int# -> State# s -> (# State# s, Int# #)
1149 with has_side_effects = True
1151 primop ReadOffAddrOp_Int16 "readInt16OffAddr#" GenPrimOp
1152 Addr# -> Int# -> State# s -> (# State# s, Int# #)
1153 with has_side_effects = True
1155 primop ReadOffAddrOp_Int32 "readInt32OffAddr#" GenPrimOp
1156 Addr# -> Int# -> State# s -> (# State# s, INT32 #)
1157 with has_side_effects = True
1159 primop ReadOffAddrOp_Int64 "readInt64OffAddr#" GenPrimOp
1160 Addr# -> Int# -> State# s -> (# State# s, INT64 #)
1161 with has_side_effects = True
1163 primop ReadOffAddrOp_Word8 "readWord8OffAddr#" GenPrimOp
1164 Addr# -> Int# -> State# s -> (# State# s, Word# #)
1165 with has_side_effects = True
1167 primop ReadOffAddrOp_Word16 "readWord16OffAddr#" GenPrimOp
1168 Addr# -> Int# -> State# s -> (# State# s, Word# #)
1169 with has_side_effects = True
1171 primop ReadOffAddrOp_Word32 "readWord32OffAddr#" GenPrimOp
1172 Addr# -> Int# -> State# s -> (# State# s, WORD32 #)
1173 with has_side_effects = True
1175 primop ReadOffAddrOp_Word64 "readWord64OffAddr#" GenPrimOp
1176 Addr# -> Int# -> State# s -> (# State# s, WORD64 #)
1177 with has_side_effects = True
1180 primop WriteOffAddrOp_Char "writeCharOffAddr#" GenPrimOp
1181 Addr# -> Int# -> Char# -> State# s -> State# s
1182 with has_side_effects = True
1184 primop WriteOffAddrOp_WideChar "writeWideCharOffAddr#" GenPrimOp
1185 Addr# -> Int# -> Char# -> State# s -> State# s
1186 with has_side_effects = True
1188 primop WriteOffAddrOp_Int "writeIntOffAddr#" GenPrimOp
1189 Addr# -> Int# -> Int# -> State# s -> State# s
1190 with has_side_effects = True
1192 primop WriteOffAddrOp_Word "writeWordOffAddr#" GenPrimOp
1193 Addr# -> Int# -> Word# -> State# s -> State# s
1194 with has_side_effects = True
1196 primop WriteOffAddrOp_Addr "writeAddrOffAddr#" GenPrimOp
1197 Addr# -> Int# -> Addr# -> State# s -> State# s
1198 with has_side_effects = True
1200 primop WriteOffAddrOp_Float "writeFloatOffAddr#" GenPrimOp
1201 Addr# -> Int# -> Float# -> State# s -> State# s
1202 with has_side_effects = True
1204 primop WriteOffAddrOp_Double "writeDoubleOffAddr#" GenPrimOp
1205 Addr# -> Int# -> Double# -> State# s -> State# s
1206 with has_side_effects = True
1208 primop WriteOffAddrOp_StablePtr "writeStablePtrOffAddr#" GenPrimOp
1209 Addr# -> Int# -> StablePtr# a -> State# s -> State# s
1210 with has_side_effects = True
1212 primop WriteOffAddrOp_Int8 "writeInt8OffAddr#" GenPrimOp
1213 Addr# -> Int# -> Int# -> State# s -> State# s
1214 with has_side_effects = True
1216 primop WriteOffAddrOp_Int16 "writeInt16OffAddr#" GenPrimOp
1217 Addr# -> Int# -> Int# -> State# s -> State# s
1218 with has_side_effects = True
1220 primop WriteOffAddrOp_Int32 "writeInt32OffAddr#" GenPrimOp
1221 Addr# -> Int# -> INT32 -> State# s -> State# s
1222 with has_side_effects = True
1224 primop WriteOffAddrOp_Int64 "writeInt64OffAddr#" GenPrimOp
1225 Addr# -> Int# -> INT64 -> State# s -> State# s
1226 with has_side_effects = True
1228 primop WriteOffAddrOp_Word8 "writeWord8OffAddr#" GenPrimOp
1229 Addr# -> Int# -> Word# -> State# s -> State# s
1230 with has_side_effects = True
1232 primop WriteOffAddrOp_Word16 "writeWord16OffAddr#" GenPrimOp
1233 Addr# -> Int# -> Word# -> State# s -> State# s
1234 with has_side_effects = True
1236 primop WriteOffAddrOp_Word32 "writeWord32OffAddr#" GenPrimOp
1237 Addr# -> Int# -> WORD32 -> State# s -> State# s
1238 with has_side_effects = True
1240 primop WriteOffAddrOp_Word64 "writeWord64OffAddr#" GenPrimOp
1241 Addr# -> Int# -> WORD64 -> State# s -> State# s
1242 with has_side_effects = True
1244 ------------------------------------------------------------------------
1245 section "Mutable variables"
1246 {Operations on MutVar\#s.}
1247 ------------------------------------------------------------------------
1249 primtype MutVar# s a
1250 {A {\tt MutVar\#} behaves like a single-element mutable array.}
1252 primop NewMutVarOp "newMutVar#" GenPrimOp
1253 a -> State# s -> (# State# s, MutVar# s a #)
1254 {Create {\tt MutVar\#} with specified initial value in specified state thread.}
1257 has_side_effects = True
1259 primop ReadMutVarOp "readMutVar#" GenPrimOp
1260 MutVar# s a -> State# s -> (# State# s, a #)
1261 {Read contents of {\tt MutVar\#}. Result is not yet evaluated.}
1263 has_side_effects = True
1265 primop WriteMutVarOp "writeMutVar#" GenPrimOp
1266 MutVar# s a -> a -> State# s -> State# s
1267 {Write contents of {\tt MutVar\#}.}
1269 has_side_effects = True
1271 primop SameMutVarOp "sameMutVar#" GenPrimOp
1272 MutVar# s a -> MutVar# s a -> Bool
1274 -- not really the right type, but we don't know about pairs here. The
1277 -- MutVar# s a -> (a -> (a,b)) -> State# s -> (# State# s, b #)
1279 primop AtomicModifyMutVarOp "atomicModifyMutVar#" GenPrimOp
1280 MutVar# s a -> (a -> b) -> State# s -> (# State# s, c #)
1283 has_side_effects = True
1285 ------------------------------------------------------------------------
1286 section "Exceptions"
1287 ------------------------------------------------------------------------
1289 primop CatchOp "catch#" GenPrimOp
1290 (State# RealWorld -> (# State# RealWorld, a #) )
1291 -> (b -> State# RealWorld -> (# State# RealWorld, a #) )
1293 -> (# State# RealWorld, a #)
1295 -- Catch is actually strict in its first argument
1296 -- but we don't want to tell the strictness
1297 -- analyser about that!
1298 -- might use caught action multiply
1300 has_side_effects = True
1302 primop RaiseOp "raise#" GenPrimOp
1305 strictness = { \ _arity -> mkStrictSig (mkTopDmdType [lazyDmd] BotRes) }
1306 -- NB: result is bottom
1309 -- raiseIO# needs to be a primop, because exceptions in the IO monad
1310 -- must be *precise* - we don't want the strictness analyser turning
1311 -- one kind of bottom into another, as it is allowed to do in pure code.
1313 primop RaiseIOOp "raiseIO#" GenPrimOp
1314 a -> State# RealWorld -> (# State# RealWorld, b #)
1317 has_side_effects = True
1319 primop BlockAsyncExceptionsOp "blockAsyncExceptions#" GenPrimOp
1320 (State# RealWorld -> (# State# RealWorld, a #))
1321 -> (State# RealWorld -> (# State# RealWorld, a #))
1324 has_side_effects = True
1326 primop UnblockAsyncExceptionsOp "unblockAsyncExceptions#" GenPrimOp
1327 (State# RealWorld -> (# State# RealWorld, a #))
1328 -> (State# RealWorld -> (# State# RealWorld, a #))
1331 has_side_effects = True
1333 primop AsyncExceptionsBlockedOp "asyncExceptionsBlocked#" GenPrimOp
1334 State# RealWorld -> (# State# RealWorld, Int# #)
1337 has_side_effects = True
1339 ------------------------------------------------------------------------
1340 section "STM-accessible Mutable Variables"
1341 ------------------------------------------------------------------------
1345 primop AtomicallyOp "atomically#" GenPrimOp
1346 (State# RealWorld -> (# State# RealWorld, a #) )
1347 -> State# RealWorld -> (# State# RealWorld, a #)
1350 has_side_effects = True
1352 primop RetryOp "retry#" GenPrimOp
1353 State# RealWorld -> (# State# RealWorld, a #)
1356 has_side_effects = True
1358 primop CatchRetryOp "catchRetry#" GenPrimOp
1359 (State# RealWorld -> (# State# RealWorld, a #) )
1360 -> (State# RealWorld -> (# State# RealWorld, a #) )
1361 -> (State# RealWorld -> (# State# RealWorld, a #) )
1364 has_side_effects = True
1366 primop CatchSTMOp "catchSTM#" GenPrimOp
1367 (State# RealWorld -> (# State# RealWorld, a #) )
1368 -> (b -> State# RealWorld -> (# State# RealWorld, a #) )
1369 -> (State# RealWorld -> (# State# RealWorld, a #) )
1372 has_side_effects = True
1374 primop Check "check#" GenPrimOp
1375 (State# RealWorld -> (# State# RealWorld, a #) )
1376 -> (State# RealWorld -> (# State# RealWorld, () #) )
1379 has_side_effects = True
1381 primop NewTVarOp "newTVar#" GenPrimOp
1383 -> State# s -> (# State# s, TVar# s a #)
1384 {Create a new {\tt TVar\#} holding a specified initial value.}
1387 has_side_effects = True
1389 primop ReadTVarOp "readTVar#" GenPrimOp
1391 -> State# s -> (# State# s, a #)
1392 {Read contents of {\tt TVar\#}. Result is not yet evaluated.}
1395 has_side_effects = True
1397 primop ReadTVarIOOp "readTVarIO#" GenPrimOp
1399 -> State# s -> (# State# s, a #)
1400 {Read contents of {\tt TVar\#} outside an STM transaction}
1403 has_side_effects = True
1405 primop WriteTVarOp "writeTVar#" GenPrimOp
1408 -> State# s -> State# s
1409 {Write contents of {\tt TVar\#}.}
1412 has_side_effects = True
1414 primop SameTVarOp "sameTVar#" GenPrimOp
1415 TVar# s a -> TVar# s a -> Bool
1418 ------------------------------------------------------------------------
1419 section "Synchronized Mutable Variables"
1420 {Operations on {\tt MVar\#}s. }
1421 ------------------------------------------------------------------------
1424 { A shared mutable variable ({\it not} the same as a {\tt MutVar\#}!).
1425 (Note: in a non-concurrent implementation, {\tt (MVar\# a)} can be
1426 represented by {\tt (MutVar\# (Maybe a))}.) }
1428 primop NewMVarOp "newMVar#" GenPrimOp
1429 State# s -> (# State# s, MVar# s a #)
1430 {Create new {\tt MVar\#}; initially empty.}
1433 has_side_effects = True
1435 primop TakeMVarOp "takeMVar#" GenPrimOp
1436 MVar# s a -> State# s -> (# State# s, a #)
1437 {If {\tt MVar\#} is empty, block until it becomes full.
1438 Then remove and return its contents, and set it empty.}
1441 has_side_effects = True
1443 primop TryTakeMVarOp "tryTakeMVar#" GenPrimOp
1444 MVar# s a -> State# s -> (# State# s, Int#, a #)
1445 {If {\tt MVar\#} is empty, immediately return with integer 0 and value undefined.
1446 Otherwise, return with integer 1 and contents of {\tt MVar\#}, and set {\tt MVar\#} empty.}
1449 has_side_effects = True
1451 primop PutMVarOp "putMVar#" GenPrimOp
1452 MVar# s a -> a -> State# s -> State# s
1453 {If {\tt MVar\#} is full, block until it becomes empty.
1454 Then store value arg as its new contents.}
1457 has_side_effects = True
1459 primop TryPutMVarOp "tryPutMVar#" GenPrimOp
1460 MVar# s a -> a -> State# s -> (# State# s, Int# #)
1461 {If {\tt MVar\#} is full, immediately return with integer 0.
1462 Otherwise, store value arg as {\tt MVar\#}'s new contents, and return with integer 1.}
1465 has_side_effects = True
1467 primop SameMVarOp "sameMVar#" GenPrimOp
1468 MVar# s a -> MVar# s a -> Bool
1470 primop IsEmptyMVarOp "isEmptyMVar#" GenPrimOp
1471 MVar# s a -> State# s -> (# State# s, Int# #)
1472 {Return 1 if {\tt MVar\#} is empty; 0 otherwise.}
1475 has_side_effects = True
1477 ------------------------------------------------------------------------
1478 section "Delay/wait operations"
1479 ------------------------------------------------------------------------
1481 primop DelayOp "delay#" GenPrimOp
1482 Int# -> State# s -> State# s
1483 {Sleep specified number of microseconds.}
1485 needs_wrapper = True
1486 has_side_effects = True
1489 primop WaitReadOp "waitRead#" GenPrimOp
1490 Int# -> State# s -> State# s
1491 {Block until input is available on specified file descriptor.}
1493 needs_wrapper = True
1494 has_side_effects = True
1497 primop WaitWriteOp "waitWrite#" GenPrimOp
1498 Int# -> State# s -> State# s
1499 {Block until output is possible on specified file descriptor.}
1501 needs_wrapper = True
1502 has_side_effects = True
1505 #ifdef mingw32_TARGET_OS
1506 primop AsyncReadOp "asyncRead#" GenPrimOp
1507 Int# -> Int# -> Int# -> Addr# -> State# RealWorld-> (# State# RealWorld, Int#, Int# #)
1508 {Asynchronously read bytes from specified file descriptor.}
1510 needs_wrapper = True
1511 has_side_effects = True
1514 primop AsyncWriteOp "asyncWrite#" GenPrimOp
1515 Int# -> Int# -> Int# -> Addr# -> State# RealWorld-> (# State# RealWorld, Int#, Int# #)
1516 {Asynchronously write bytes from specified file descriptor.}
1518 needs_wrapper = True
1519 has_side_effects = True
1522 primop AsyncDoProcOp "asyncDoProc#" GenPrimOp
1523 Addr# -> Addr# -> State# RealWorld-> (# State# RealWorld, Int#, Int# #)
1524 {Asynchronously perform procedure (first arg), passing it 2nd arg.}
1526 needs_wrapper = True
1527 has_side_effects = True
1532 ------------------------------------------------------------------------
1533 section "Concurrency primitives"
1534 ------------------------------------------------------------------------
1537 { {\tt State\#} is the primitive, unlifted type of states. It has
1538 one type parameter, thus {\tt State\# RealWorld}, or {\tt State\# s},
1539 where s is a type variable. The only purpose of the type parameter
1540 is to keep different state threads separate. It is represented by
1544 { {\tt RealWorld} is deeply magical. It is {\it primitive}, but it is not
1545 {\it unlifted} (hence {\tt ptrArg}). We never manipulate values of type
1546 {\tt RealWorld}; it's only used in the type system, to parameterise {\tt State\#}. }
1549 {(In a non-concurrent implementation, this can be a singleton
1550 type, whose (unique) value is returned by {\tt myThreadId\#}. The
1551 other operations can be omitted.)}
1553 primop ForkOp "fork#" GenPrimOp
1554 a -> State# RealWorld -> (# State# RealWorld, ThreadId# #)
1556 has_side_effects = True
1559 primop ForkOnOp "forkOn#" GenPrimOp
1560 Int# -> a -> State# RealWorld -> (# State# RealWorld, ThreadId# #)
1562 has_side_effects = True
1565 primop KillThreadOp "killThread#" GenPrimOp
1566 ThreadId# -> a -> State# RealWorld -> State# RealWorld
1568 has_side_effects = True
1571 primop YieldOp "yield#" GenPrimOp
1572 State# RealWorld -> State# RealWorld
1574 has_side_effects = True
1577 primop MyThreadIdOp "myThreadId#" GenPrimOp
1578 State# RealWorld -> (# State# RealWorld, ThreadId# #)
1581 has_side_effects = True
1583 primop LabelThreadOp "labelThread#" GenPrimOp
1584 ThreadId# -> Addr# -> State# RealWorld -> State# RealWorld
1586 has_side_effects = True
1589 primop IsCurrentThreadBoundOp "isCurrentThreadBound#" GenPrimOp
1590 State# RealWorld -> (# State# RealWorld, Int# #)
1593 has_side_effects = True
1595 primop NoDuplicateOp "noDuplicate#" GenPrimOp
1596 State# RealWorld -> State# RealWorld
1599 has_side_effects = True
1601 primop ThreadStatusOp "threadStatus#" GenPrimOp
1602 ThreadId# -> State# RealWorld -> (# State# RealWorld, Int# #)
1605 has_side_effects = True
1607 ------------------------------------------------------------------------
1608 section "Weak pointers"
1609 ------------------------------------------------------------------------
1613 -- note that tyvar "o" denotes openAlphaTyVar
1615 primop MkWeakOp "mkWeak#" GenPrimOp
1616 o -> b -> c -> State# RealWorld -> (# State# RealWorld, Weak# b #)
1618 has_side_effects = True
1621 primop MkWeakForeignEnvOp "mkWeakForeignEnv#" GenPrimOp
1622 o -> b -> Addr# -> Addr# -> Int# -> Addr# -> State# RealWorld -> (# State# RealWorld, Weak# b #)
1624 has_side_effects = True
1627 primop DeRefWeakOp "deRefWeak#" GenPrimOp
1628 Weak# a -> State# RealWorld -> (# State# RealWorld, Int#, a #)
1630 has_side_effects = True
1633 primop FinalizeWeakOp "finalizeWeak#" GenPrimOp
1634 Weak# a -> State# RealWorld -> (# State# RealWorld, Int#,
1635 (State# RealWorld -> (# State# RealWorld, () #)) #)
1637 has_side_effects = True
1640 primop TouchOp "touch#" GenPrimOp
1641 o -> State# RealWorld -> State# RealWorld
1643 has_side_effects = True
1645 ------------------------------------------------------------------------
1646 section "Stable pointers and names"
1647 ------------------------------------------------------------------------
1649 primtype StablePtr# a
1651 primtype StableName# a
1653 primop MakeStablePtrOp "makeStablePtr#" GenPrimOp
1654 a -> State# RealWorld -> (# State# RealWorld, StablePtr# a #)
1656 has_side_effects = True
1659 primop DeRefStablePtrOp "deRefStablePtr#" GenPrimOp
1660 StablePtr# a -> State# RealWorld -> (# State# RealWorld, a #)
1662 needs_wrapper = True
1663 has_side_effects = True
1666 primop EqStablePtrOp "eqStablePtr#" GenPrimOp
1667 StablePtr# a -> StablePtr# a -> Int#
1669 has_side_effects = True
1671 primop MakeStableNameOp "makeStableName#" GenPrimOp
1672 a -> State# RealWorld -> (# State# RealWorld, StableName# a #)
1674 needs_wrapper = True
1675 has_side_effects = True
1678 primop EqStableNameOp "eqStableName#" GenPrimOp
1679 StableName# a -> StableName# a -> Int#
1681 primop StableNameToIntOp "stableNameToInt#" GenPrimOp
1682 StableName# a -> Int#
1684 ------------------------------------------------------------------------
1685 section "Unsafe pointer equality"
1686 -- (#1 Bad Guy: Alistair Reid :)
1687 ------------------------------------------------------------------------
1689 primop ReallyUnsafePtrEqualityOp "reallyUnsafePtrEquality#" GenPrimOp
1692 ------------------------------------------------------------------------
1693 section "Parallelism"
1694 ------------------------------------------------------------------------
1696 primop ParOp "par#" GenPrimOp
1699 -- Note that Par is lazy to avoid that the sparked thing
1700 -- gets evaluted strictly, which it should *not* be
1701 has_side_effects = True
1703 primop GetSparkOp "getSpark#" GenPrimOp
1704 State# s -> (# State# s, Int#, a #)
1706 has_side_effects = True
1709 -- HWL: The first 4 Int# in all par... annotations denote:
1710 -- name, granularity info, size of result, degree of parallelism
1711 -- Same structure as _seq_ i.e. returns Int#
1712 -- KSW: v, the second arg in parAt# and parAtForNow#, is used only to determine
1713 -- `the processor containing the expression v'; it is not evaluated
1715 primop ParGlobalOp "parGlobal#" GenPrimOp
1716 a -> Int# -> Int# -> Int# -> Int# -> b -> Int#
1718 has_side_effects = True
1720 primop ParLocalOp "parLocal#" GenPrimOp
1721 a -> Int# -> Int# -> Int# -> Int# -> b -> Int#
1723 has_side_effects = True
1725 primop ParAtOp "parAt#" GenPrimOp
1726 b -> a -> Int# -> Int# -> Int# -> Int# -> c -> Int#
1728 has_side_effects = True
1730 primop ParAtAbsOp "parAtAbs#" GenPrimOp
1731 a -> Int# -> Int# -> Int# -> Int# -> Int# -> b -> Int#
1733 has_side_effects = True
1735 primop ParAtRelOp "parAtRel#" GenPrimOp
1736 a -> Int# -> Int# -> Int# -> Int# -> Int# -> b -> Int#
1738 has_side_effects = True
1740 primop ParAtForNowOp "parAtForNow#" GenPrimOp
1741 b -> a -> Int# -> Int# -> Int# -> Int# -> c -> Int#
1743 has_side_effects = True
1745 -- copyable# and noFollow# are yet to be implemented (for GpH)
1747 --primop CopyableOp "copyable#" GenPrimOp
1750 -- has_side_effects = True
1752 --primop NoFollowOp "noFollow#" GenPrimOp
1755 -- has_side_effects = True
1758 ------------------------------------------------------------------------
1759 section "Tag to enum stuff"
1760 {Convert back and forth between values of enumerated types
1761 and small integers.}
1762 ------------------------------------------------------------------------
1764 primop DataToTagOp "dataToTag#" GenPrimOp
1767 strictness = { \ _arity -> mkStrictSig (mkTopDmdType [seqDmd] TopRes) }
1768 -- dataToTag# must have an evaluated argument
1770 primop TagToEnumOp "tagToEnum#" GenPrimOp
1773 ------------------------------------------------------------------------
1774 section "Bytecode operations"
1775 {Support for the bytecode interpreter and linker.}
1776 ------------------------------------------------------------------------
1779 {Primitive bytecode type.}
1781 primop AddrToHValueOp "addrToHValue#" GenPrimOp
1783 {Convert an {\tt Addr\#} to a followable type.}
1785 primop MkApUpd0_Op "mkApUpd0#" GenPrimOp
1790 primop NewBCOOp "newBCO#" GenPrimOp
1791 ByteArray# -> ByteArray# -> Array# a -> Int# -> ByteArray# -> State# s -> (# State# s, BCO# #)
1793 has_side_effects = True
1796 primop UnpackClosureOp "unpackClosure#" GenPrimOp
1797 a -> (# Addr#, Array# b, ByteArray# #)
1801 primop GetApStackValOp "getApStackVal#" GenPrimOp
1802 a -> Int# -> (# Int#, b #)
1806 ------------------------------------------------------------------------
1808 {These aren't nearly as wired in as Etc...}
1809 ------------------------------------------------------------------------
1811 primop TraceCcsOp "traceCcs#" GenPrimOp
1814 has_side_effects = True
1817 ------------------------------------------------------------------------
1819 {Miscellaneous built-ins}
1820 ------------------------------------------------------------------------
1824 { Evaluates its first argument to head normal form, and then returns its second
1825 argument as the result. }
1829 { The call {\tt (inline f)} arranges that f is inlined, regardless of its size.
1830 More precisely, the call {\tt (inline f)} rewrites to the right-hand side of
1831 {\tt f}'s definition. This allows the programmer to control inlining from a
1832 particular call site rather than the definition site of the function (c.f.
1833 {\tt INLINE} pragmas in User's Guide, Section 7.10.3, "INLINE and NOINLINE
1836 This inlining occurs regardless of the argument to the call or the size of
1837 {\tt f}'s definition; it is unconditional. The main caveat is that {\tt f}'s
1838 definition must be visible to the compiler. That is, {\tt f} must be
1839 {\tt let}-bound in the current scope. If no inlining takes place, the
1840 {\tt inline} function expands to the identity function in Phase zero; so its
1841 use imposes no overhead.
1843 If the function is defined in another module, GHC only exposes its inlining
1844 in the interface file if the function is sufficiently small that it might be
1845 inlined by the automatic mechanism. There is currently no way to tell GHC to
1846 expose arbitrarily-large functions in the interface file. (This shortcoming
1847 is something that could be fixed, with some kind of pragma.) }
1851 { The {\tt lazy} function restrains strictness analysis a little. The call
1852 {\tt (lazy e)} means the same as {\tt e}, but {\tt lazy} has a magical
1853 property so far as strictness analysis is concerned: it is lazy in its first
1854 argument, even though its semantics is strict. After strictness analysis has
1855 run, calls to {\tt lazy} are inlined to be the identity function.
1857 This behaviour is occasionally useful when controlling evaluation order.
1858 Notably, {\tt lazy} is used in the library definition of {\tt Control.Parallel.par}:
1860 {\tt par :: a -> b -> b}
1862 {\tt par x y = case (par\# x) of \_ -> lazy y}
1864 If {\tt lazy} were not lazy, {\tt par} would look strict in {\tt y} which
1865 would defeat the whole purpose of {\tt par}.
1867 Like {\tt seq}, the argument of {\tt lazy} can have an unboxed type. }
1870 { The type constructor {\tt Any} is type to which you can unsafely coerce any
1871 lifted type, and back.
1873 * It is lifted, and hence represented by a pointer
1875 * It does not claim to be a {\it data} type, and that's important for
1876 the code generator, because the code gen may {\it enter} a data value
1877 but never enters a function value.
1879 It's also used to instantiate un-constrained type variables after type
1880 checking. For example
1884 Annoyingly, we sometimes need {\tt Any}s of other kinds, such as {\tt (* -> *)} etc.
1885 This is a bit like tuples. We define a couple of useful ones here,
1886 and make others up on the fly. If any of these others end up being exported
1887 into interface files, we'll get a crash; at least until we add interface-file
1888 syntax to support them. }
1890 pseudoop "unsafeCoerce#"
1892 { The function {\tt unsafeCoerce\#} allows you to side-step the typechecker entirely. That
1893 is, it allows you to coerce any type into any other type. If you use this function,
1894 you had better get it right, otherwise segmentation faults await. It is generally
1895 used when you want to write a program that you know is well-typed, but where Haskell's
1896 type system is not expressive enough to prove that it is well typed.
1898 The following uses of {\tt unsafeCoerce\#} are supposed to work (i.e. not lead to
1899 spurious compile-time or run-time crashes):
1901 * Casting any lifted type to {\tt Any}
1903 * Casting {\tt Any} back to the real type
1905 * Casting an unboxed type to another unboxed type of the same size
1906 (but not coercions between floating-point and integral types)
1908 * Casting between two types that have the same runtime representation. One case is when
1909 the two types differ only in "phantom" type parameters, for example
1910 {\tt Ptr Int} to {\tt Ptr Float}, or {\tt [Int]} to {\tt [Float]} when the list is
1911 known to be empty. Also, a {\tt newtype} of a type {\tt T} has the same representation
1912 at runtime as {\tt T}.
1914 Other uses of {\tt unsafeCoerce\#} are undefined. In particular, you should not use
1915 {\tt unsafeCoerce\#} to cast a T to an algebraic data type D, unless T is also
1916 an algebraic data type. For example, do not cast {\tt Int->Int} to {\tt Bool}, even if
1917 you later cast that {\tt Bool} back to {\tt Int->Int} before applying it. The reasons
1918 have to do with GHC's internal representation details (for the congnoscenti, data values
1919 can be entered but function closures cannot). If you want a safe type to cast things
1920 to, use {\tt Any}, which is not an algebraic data type.
1924 -- NB. It is tempting to think that casting a value to a type that it doesn't have is safe
1925 -- as long as you don't "do anything" with the value in its cast form, such as seq on it. This
1926 -- isn't the case: the compiler can insert seqs itself, and if these happen at the wrong type,
1927 -- Bad Things Might Happen. See bug #1616: in this case we cast a function of type (a,b) -> (a,b)
1928 -- to () -> () and back again. The strictness analyser saw that the function was strict, but
1929 -- the wrapper had type () -> (), and hence the wrapper de-constructed the (), the worker re-constructed
1930 -- a new (), with the result that the code ended up with "case () of (a,b) -> ...".
1932 ------------------------------------------------------------------------
1934 ------------------------------------------------------------------------