base: Implement bit casts between word and float types
[ghc.git] / compiler / prelude / primops.txt.pp
1 -----------------------------------------------------------------------
2 --
3 -- (c) 2010 The University of Glasgow
4 --
5 -- Primitive Operations and Types
6 --
7 -- For more information on PrimOps, see
8 --   http://ghc.haskell.org/trac/ghc/wiki/Commentary/PrimOps
9 --
10 -----------------------------------------------------------------------
11
12 -- This file is processed by the utility program genprimopcode to produce
13 -- a number of include files within the compiler and optionally to produce
14 -- human-readable documentation.
15 --
16 -- It should first be preprocessed.
17 --
18 -- Information on how PrimOps are implemented and the steps necessary to
19 -- add a new one can be found in the Commentary:
20 --
21 --  http://ghc.haskell.org/trac/ghc/wiki/Commentary/PrimOps
22
23 -- This file is divided into named sections, each containing or more
24 -- primop entries. Section headers have the format:
25 --
26 --      section "section-name" {description}
27 --
28 -- This information is used solely when producing documentation; it is
29 -- otherwise ignored.  The description is optional.
30 --
31 -- The format of each primop entry is as follows:
32 --
33 --      primop internal-name "name-in-program-text" type category {description} attributes
34
35 -- The default attribute values which apply if you don't specify
36 -- other ones.  Attribute values can be True, False, or arbitrary
37 -- text between curly brackets.  This is a kludge to enable
38 -- processors of this file to easily get hold of simple info
39 -- (eg, out_of_line), whilst avoiding parsing complex expressions
40 -- needed for strictness info.
41
42 -- The vector attribute is rather special. It takes a list of 3-tuples, each of
43 -- which is of the form <ELEM_TYPE,SCALAR_TYPE,LENGTH>. ELEM_TYPE is the type of
44 -- the elements in the vector; LENGTH is the length of the vector; and
45 -- SCALAR_TYPE is the scalar type used to inject to/project from vector
46 -- element. Note that ELEM_TYPE and SCALAR_TYPE are not the same; for example,
47 -- to broadcast a scalar value to a vector whose elements are of type Int8, we
48 -- use an Int#.
49
50 -- When a primtype or primop has a vector attribute, it is instantiated at each
51 -- 3-tuple in the list of 3-tuples. That is, the vector attribute allows us to
52 -- define a family of types or primops. Vector support also adds three new
53 -- keywords: VECTOR, SCALAR, and VECTUPLE. These keywords are expanded to types
54 -- derived from the 3-tuple. For the 3-tuple <Int64,INT64,2>, VECTOR expands to
55 -- Int64X2#, SCALAR expands to INT64, and VECTUPLE expands to (# INT64, INT64
56 -- #).
57
58 defaults
59    has_side_effects = False
60    out_of_line      = False   -- See Note Note [PrimOp can_fail and has_side_effects] in PrimOp
61    can_fail         = False   -- See Note Note [PrimOp can_fail and has_side_effects] in PrimOp
62    commutable       = False
63    code_size        = { primOpCodeSizeDefault }
64    strictness       = { \ arity -> mkClosedStrictSig (replicate arity topDmd) topRes }
65    fixity           = Nothing
66    llvm_only        = False
67    vector           = []
68
69 -- Currently, documentation is produced using latex, so contents of
70 -- description fields should be legal latex. Descriptions can contain
71 -- matched pairs of embedded curly brackets.
72
73 #include "MachDeps.h"
74
75 -- We need platform defines (tests for mingw32 below).
76 #include "ghc_boot_platform.h"
77
78 section "The word size story."
79         {Haskell98 specifies that signed integers (type {\tt Int})
80          must contain at least 30 bits. GHC always implements {\tt
81          Int} using the primitive type {\tt Int\#}, whose size equals
82          the {\tt MachDeps.h} constant {\tt WORD\_SIZE\_IN\_BITS}.
83          This is normally set based on the {\tt config.h} parameter
84          {\tt SIZEOF\_HSWORD}, i.e., 32 bits on 32-bit machines, 64
85          bits on 64-bit machines.  However, it can also be explicitly
86          set to a smaller number, e.g., 31 bits, to allow the
87          possibility of using tag bits. Currently GHC itself has only
88          32-bit and 64-bit variants, but 30 or 31-bit code can be
89          exported as an external core file for use in other back ends.
90
91          GHC also implements a primitive unsigned integer type {\tt
92          Word\#} which always has the same number of bits as {\tt
93          Int\#}.
94
95          In addition, GHC supports families of explicit-sized integers
96          and words at 8, 16, 32, and 64 bits, with the usual
97          arithmetic operations, comparisons, and a range of
98          conversions.  The 8-bit and 16-bit sizes are always
99          represented as {\tt Int\#} and {\tt Word\#}, and the
100          operations implemented in terms of the the primops on these
101          types, with suitable range restrictions on the results (using
102          the {\tt narrow$n$Int\#} and {\tt narrow$n$Word\#} families
103          of primops.  The 32-bit sizes are represented using {\tt
104          Int\#} and {\tt Word\#} when {\tt WORD\_SIZE\_IN\_BITS}
105          $\geq$ 32; otherwise, these are represented using distinct
106          primitive types {\tt Int32\#} and {\tt Word32\#}. These (when
107          needed) have a complete set of corresponding operations;
108          however, nearly all of these are implemented as external C
109          functions rather than as primops.  Exactly the same story
110          applies to the 64-bit sizes.  All of these details are hidden
111          under the {\tt PrelInt} and {\tt PrelWord} modules, which use
112          {\tt \#if}-defs to invoke the appropriate types and
113          operators.
114
115          Word size also matters for the families of primops for
116          indexing/reading/writing fixed-size quantities at offsets
117          from an array base, address, or foreign pointer.  Here, a
118          slightly different approach is taken.  The names of these
119          primops are fixed, but their {\it types} vary according to
120          the value of {\tt WORD\_SIZE\_IN\_BITS}. For example, if word
121          size is at least 32 bits then an operator like
122          \texttt{indexInt32Array\#} has type {\tt ByteArray\# -> Int\#
123          -> Int\#}; otherwise it has type {\tt ByteArray\# -> Int\# ->
124          Int32\#}.  This approach confines the necessary {\tt
125          \#if}-defs to this file; no conditional compilation is needed
126          in the files that expose these primops.
127
128          Finally, there are strongly deprecated primops for coercing
129          between {\tt Addr\#}, the primitive type of machine
130          addresses, and {\tt Int\#}.  These are pretty bogus anyway,
131          but will work on existing 32-bit and 64-bit GHC targets; they
132          are completely bogus when tag bits are used in {\tt Int\#},
133          so are not available in this case.  }
134
135 -- Define synonyms for indexing ops.
136
137 #if WORD_SIZE_IN_BITS < 32
138 #define INT32 Int32#
139 #define WORD32 Word32#
140 #else
141 #define INT32 Int#
142 #define WORD32 Word#
143 #endif
144
145 #if WORD_SIZE_IN_BITS < 64
146 #define INT64 Int64#
147 #define WORD64 Word64#
148 #else
149 #define INT64 Int#
150 #define WORD64 Word#
151 #endif
152
153 ------------------------------------------------------------------------
154 section "Char#"
155         {Operations on 31-bit characters.}
156 ------------------------------------------------------------------------
157
158 primtype Char#
159
160 primop   CharGtOp  "gtChar#"   Compare   Char# -> Char# -> Int#
161 primop   CharGeOp  "geChar#"   Compare   Char# -> Char# -> Int#
162
163 primop   CharEqOp  "eqChar#"   Compare
164    Char# -> Char# -> Int#
165    with commutable = True
166
167 primop   CharNeOp  "neChar#"   Compare
168    Char# -> Char# -> Int#
169    with commutable = True
170
171 primop   CharLtOp  "ltChar#"   Compare   Char# -> Char# -> Int#
172 primop   CharLeOp  "leChar#"   Compare   Char# -> Char# -> Int#
173
174 primop   OrdOp   "ord#"  GenPrimOp   Char# -> Int#
175    with code_size = 0
176
177 ------------------------------------------------------------------------
178 section "Int#"
179         {Operations on native-size integers (30+ bits).}
180 ------------------------------------------------------------------------
181
182 primtype Int#
183
184 primop   IntAddOp    "+#"    Dyadic
185    Int# -> Int# -> Int#
186    with commutable = True
187         fixity = infixl 6
188
189 primop   IntSubOp    "-#"    Dyadic   Int# -> Int# -> Int#
190    with fixity = infixl 6
191
192 primop   IntMulOp    "*#"
193    Dyadic   Int# -> Int# -> Int#
194    {Low word of signed integer multiply.}
195    with commutable = True
196         fixity = infixl 7
197
198 primop   IntMulMayOfloOp  "mulIntMayOflo#"
199    Dyadic   Int# -> Int# -> Int#
200    {Return non-zero if there is any possibility that the upper word of a
201     signed integer multiply might contain useful information.  Return
202     zero only if you are completely sure that no overflow can occur.
203     On a 32-bit platform, the recommended implementation is to do a
204     32 x 32 -> 64 signed multiply, and subtract result[63:32] from
205     (result[31] >>signed 31).  If this is zero, meaning that the
206     upper word is merely a sign extension of the lower one, no
207     overflow can occur.
208
209     On a 64-bit platform it is not always possible to
210     acquire the top 64 bits of the result.  Therefore, a recommended
211     implementation is to take the absolute value of both operands, and
212     return 0 iff bits[63:31] of them are zero, since that means that their
213     magnitudes fit within 31 bits, so the magnitude of the product must fit
214     into 62 bits.
215
216     If in doubt, return non-zero, but do make an effort to create the
217     correct answer for small args, since otherwise the performance of
218     \texttt{(*) :: Integer -> Integer -> Integer} will be poor.
219    }
220    with commutable = True
221
222 primop   IntQuotOp    "quotInt#"    Dyadic
223    Int# -> Int# -> Int#
224    {Rounds towards zero. The behavior is undefined if the second argument is
225     zero.
226    }
227    with can_fail = True
228
229 primop   IntRemOp    "remInt#"    Dyadic
230    Int# -> Int# -> Int#
231    {Satisfies \texttt{(quotInt\# x y) *\# y +\# (remInt\# x y) == x}. The
232     behavior is undefined if the second argument is zero.
233    }
234    with can_fail = True
235
236 primop   IntQuotRemOp "quotRemInt#"    GenPrimOp
237    Int# -> Int# -> (# Int#, Int# #)
238    {Rounds towards zero.}
239    with can_fail = True
240
241 primop   AndIOp   "andI#"   Dyadic    Int# -> Int# -> Int#
242    with commutable = True
243
244 primop   OrIOp   "orI#"     Dyadic    Int# -> Int# -> Int#
245    with commutable = True
246
247 primop   XorIOp   "xorI#"   Dyadic    Int# -> Int# -> Int#
248    with commutable = True
249
250 primop   NotIOp   "notI#"   Monadic   Int# -> Int#
251
252 primop   IntNegOp    "negateInt#"    Monadic   Int# -> Int#
253 primop   IntAddCOp   "addIntC#"    GenPrimOp   Int# -> Int# -> (# Int#, Int# #)
254          {Add signed integers reporting overflow.
255           First member of result is the sum truncated to an {\tt Int#};
256           second member is zero if the true sum fits in an {\tt Int#},
257           nonzero if overflow occurred (the sum is either too large
258           or too small to fit in an {\tt Int#}).}
259    with code_size = 2
260
261 primop   IntSubCOp   "subIntC#"    GenPrimOp   Int# -> Int# -> (# Int#, Int# #)
262          {Subtract signed integers reporting overflow.
263           First member of result is the difference truncated to an {\tt Int#};
264           second member is zero if the true difference fits in an {\tt Int#},
265           nonzero if overflow occurred (the difference is either too large
266           or too small to fit in an {\tt Int#}).}
267    with code_size = 2
268
269 primop   IntGtOp  ">#"   Compare   Int# -> Int# -> Int#
270    with fixity = infix 4
271
272 primop   IntGeOp  ">=#"   Compare   Int# -> Int# -> Int#
273    with fixity = infix 4
274
275 primop   IntEqOp  "==#"   Compare
276    Int# -> Int# -> Int#
277    with commutable = True
278         fixity = infix 4
279
280 primop   IntNeOp  "/=#"   Compare
281    Int# -> Int# -> Int#
282    with commutable = True
283         fixity = infix 4
284
285 primop   IntLtOp  "<#"   Compare   Int# -> Int# -> Int#
286    with fixity = infix 4
287
288 primop   IntLeOp  "<=#"   Compare   Int# -> Int# -> Int#
289    with fixity = infix 4
290
291 primop   ChrOp   "chr#"   GenPrimOp   Int# -> Char#
292    with code_size = 0
293
294 primop   Int2WordOp "int2Word#" GenPrimOp Int# -> Word#
295    with code_size = 0
296
297 primop   Int2FloatOp   "int2Float#"      GenPrimOp  Int# -> Float#
298 primop   Int2DoubleOp   "int2Double#"          GenPrimOp  Int# -> Double#
299
300 primop   Word2FloatOp   "word2Float#"      GenPrimOp  Word# -> Float#
301 primop   Word2DoubleOp   "word2Double#"          GenPrimOp  Word# -> Double#
302
303 primop   ISllOp   "uncheckedIShiftL#" GenPrimOp  Int# -> Int# -> Int#
304          {Shift left.  Result undefined if shift amount is not
305           in the range 0 to word size - 1 inclusive.}
306 primop   ISraOp   "uncheckedIShiftRA#" GenPrimOp Int# -> Int# -> Int#
307          {Shift right arithmetic.  Result undefined if shift amount is not
308           in the range 0 to word size - 1 inclusive.}
309 primop   ISrlOp   "uncheckedIShiftRL#" GenPrimOp Int# -> Int# -> Int#
310          {Shift right logical.  Result undefined if shift amount is not
311           in the range 0 to word size - 1 inclusive.}
312
313 ------------------------------------------------------------------------
314 section "Word#"
315         {Operations on native-sized unsigned words (30+ bits).}
316 ------------------------------------------------------------------------
317
318 primtype Word#
319
320 primop   WordAddOp   "plusWord#"   Dyadic   Word# -> Word# -> Word#
321    with commutable = True
322
323 primop   WordSubCOp   "subWordC#"   GenPrimOp   Word# -> Word# -> (# Word#, Int# #)
324          {Subtract unsigned integers reporting overflow.
325           The first element of the pair is the result.  The second element is
326           the carry flag, which is nonzero on overflow.}
327
328 -- Returns (# high, low #) (or equivalently, (# carry, low #))
329 primop   WordAdd2Op  "plusWord2#"  GenPrimOp
330    Word# -> Word# -> (# Word#, Word# #)
331    with commutable = True
332
333 primop   WordSubOp   "minusWord#"   Dyadic   Word# -> Word# -> Word#
334
335 primop   WordMulOp   "timesWord#"   Dyadic   Word# -> Word# -> Word#
336    with commutable = True
337
338 -- Returns (# high, low #)
339 primop   WordMul2Op  "timesWord2#"   GenPrimOp
340    Word# -> Word# -> (# Word#, Word# #)
341    with commutable = True
342
343 primop   WordQuotOp   "quotWord#"   Dyadic   Word# -> Word# -> Word#
344    with can_fail = True
345
346 primop   WordRemOp   "remWord#"   Dyadic   Word# -> Word# -> Word#
347    with can_fail = True
348
349 primop   WordQuotRemOp "quotRemWord#" GenPrimOp
350    Word# -> Word# -> (# Word#, Word# #)
351    with can_fail = True
352
353 -- Takes high word of dividend, then low word of dividend, then divisor.
354 -- Requires that high word is not divisible by divisor.
355 primop   WordQuotRem2Op "quotRemWord2#" GenPrimOp
356    Word# -> Word# -> Word# -> (# Word#, Word# #)
357    with can_fail = True
358
359 primop   AndOp   "and#"   Dyadic   Word# -> Word# -> Word#
360    with commutable = True
361
362 primop   OrOp   "or#"   Dyadic   Word# -> Word# -> Word#
363    with commutable = True
364
365 primop   XorOp   "xor#"   Dyadic   Word# -> Word# -> Word#
366    with commutable = True
367
368 primop   NotOp   "not#"   Monadic   Word# -> Word#
369
370 primop   SllOp   "uncheckedShiftL#"   GenPrimOp   Word# -> Int# -> Word#
371          {Shift left logical.   Result undefined if shift amount is not
372           in the range 0 to word size - 1 inclusive.}
373 primop   SrlOp   "uncheckedShiftRL#"   GenPrimOp   Word# -> Int# -> Word#
374          {Shift right logical.   Result undefined if shift  amount is not
375           in the range 0 to word size - 1 inclusive.}
376
377 primop   Word2IntOp   "word2Int#"   GenPrimOp   Word# -> Int#
378    with code_size = 0
379
380 primop   WordGtOp   "gtWord#"   Compare   Word# -> Word# -> Int#
381 primop   WordGeOp   "geWord#"   Compare   Word# -> Word# -> Int#
382 primop   WordEqOp   "eqWord#"   Compare   Word# -> Word# -> Int#
383 primop   WordNeOp   "neWord#"   Compare   Word# -> Word# -> Int#
384 primop   WordLtOp   "ltWord#"   Compare   Word# -> Word# -> Int#
385 primop   WordLeOp   "leWord#"   Compare   Word# -> Word# -> Int#
386
387 primop   PopCnt8Op   "popCnt8#"   Monadic   Word# -> Word#
388     {Count the number of set bits in the lower 8 bits of a word.}
389 primop   PopCnt16Op   "popCnt16#"   Monadic   Word# -> Word#
390     {Count the number of set bits in the lower 16 bits of a word.}
391 primop   PopCnt32Op   "popCnt32#"   Monadic   Word# -> Word#
392     {Count the number of set bits in the lower 32 bits of a word.}
393 primop   PopCnt64Op   "popCnt64#"   GenPrimOp   WORD64 -> Word#
394     {Count the number of set bits in a 64-bit word.}
395 primop   PopCntOp   "popCnt#"   Monadic   Word# -> Word#
396     {Count the number of set bits in a word.}
397
398 primop   Clz8Op   "clz8#" Monadic   Word# -> Word#
399     {Count leading zeros in the lower 8 bits of a word.}
400 primop   Clz16Op   "clz16#" Monadic   Word# -> Word#
401     {Count leading zeros in the lower 16 bits of a word.}
402 primop   Clz32Op   "clz32#" Monadic   Word# -> Word#
403     {Count leading zeros in the lower 32 bits of a word.}
404 primop   Clz64Op   "clz64#" GenPrimOp WORD64 -> Word#
405     {Count leading zeros in a 64-bit word.}
406 primop   ClzOp     "clz#"   Monadic   Word# -> Word#
407     {Count leading zeros in a word.}
408
409 primop   Ctz8Op   "ctz8#"  Monadic   Word# -> Word#
410     {Count trailing zeros in the lower 8 bits of a word.}
411 primop   Ctz16Op   "ctz16#" Monadic   Word# -> Word#
412     {Count trailing zeros in the lower 16 bits of a word.}
413 primop   Ctz32Op   "ctz32#" Monadic   Word# -> Word#
414     {Count trailing zeros in the lower 32 bits of a word.}
415 primop   Ctz64Op   "ctz64#" GenPrimOp WORD64 -> Word#
416     {Count trailing zeros in a 64-bit word.}
417 primop   CtzOp     "ctz#"   Monadic   Word# -> Word#
418     {Count trailing zeros in a word.}
419
420 primop   BSwap16Op   "byteSwap16#"   Monadic   Word# -> Word#
421     {Swap bytes in the lower 16 bits of a word. The higher bytes are undefined. }
422 primop   BSwap32Op   "byteSwap32#"   Monadic   Word# -> Word#
423     {Swap bytes in the lower 32 bits of a word. The higher bytes are undefined. }
424 primop   BSwap64Op   "byteSwap64#"   Monadic   WORD64 -> WORD64
425     {Swap bytes in a 64 bits of a word.}
426 primop   BSwapOp     "byteSwap#"     Monadic   Word# -> Word#
427     {Swap bytes in a word.}
428
429 ------------------------------------------------------------------------
430 section "Narrowings"
431         {Explicit narrowing of native-sized ints or words.}
432 ------------------------------------------------------------------------
433
434 primop   Narrow8IntOp      "narrow8Int#"      Monadic   Int# -> Int#
435 primop   Narrow16IntOp     "narrow16Int#"     Monadic   Int# -> Int#
436 primop   Narrow32IntOp     "narrow32Int#"     Monadic   Int# -> Int#
437 primop   Narrow8WordOp     "narrow8Word#"     Monadic   Word# -> Word#
438 primop   Narrow16WordOp    "narrow16Word#"    Monadic   Word# -> Word#
439 primop   Narrow32WordOp    "narrow32Word#"    Monadic   Word# -> Word#
440
441
442 #if WORD_SIZE_IN_BITS < 32
443 ------------------------------------------------------------------------
444 section "Int32#"
445         {Operations on 32-bit integers ({\tt Int32\#}).  This type is only used
446          if plain {\tt Int\#} has less than 32 bits.  In any case, the operations
447          are not primops; they are implemented (if needed) as ccalls instead.}
448 ------------------------------------------------------------------------
449
450 primtype Int32#
451
452 ------------------------------------------------------------------------
453 section "Word32#"
454         {Operations on 32-bit unsigned words. This type is only used
455          if plain {\tt Word\#} has less than 32 bits. In any case, the operations
456          are not primops; they are implemented (if needed) as ccalls instead.}
457 ------------------------------------------------------------------------
458
459 primtype Word32#
460
461 #endif
462
463
464 #if WORD_SIZE_IN_BITS < 64
465 ------------------------------------------------------------------------
466 section "Int64#"
467         {Operations on 64-bit unsigned words. This type is only used
468          if plain {\tt Int\#} has less than 64 bits. In any case, the operations
469          are not primops; they are implemented (if needed) as ccalls instead.}
470 ------------------------------------------------------------------------
471
472 primtype Int64#
473
474 ------------------------------------------------------------------------
475 section "Word64#"
476         {Operations on 64-bit unsigned words. This type is only used
477          if plain {\tt Word\#} has less than 64 bits. In any case, the operations
478          are not primops; they are implemented (if needed) as ccalls instead.}
479 ------------------------------------------------------------------------
480
481 primtype Word64#
482
483 #endif
484
485 ------------------------------------------------------------------------
486 section "Double#"
487         {Operations on double-precision (64 bit) floating-point numbers.}
488 ------------------------------------------------------------------------
489
490 primtype Double#
491
492 primop   DoubleGtOp ">##"   Compare   Double# -> Double# -> Int#
493    with fixity = infix 4
494
495 primop   DoubleGeOp ">=##"   Compare   Double# -> Double# -> Int#
496    with fixity = infix 4
497
498 primop DoubleEqOp "==##"   Compare
499    Double# -> Double# -> Int#
500    with commutable = True
501         fixity = infix 4
502
503 primop DoubleNeOp "/=##"   Compare
504    Double# -> Double# -> Int#
505    with commutable = True
506         fixity = infix 4
507
508 primop   DoubleLtOp "<##"   Compare   Double# -> Double# -> Int#
509    with fixity = infix 4
510
511 primop   DoubleLeOp "<=##"   Compare   Double# -> Double# -> Int#
512    with fixity = infix 4
513
514 primop   DoubleAddOp   "+##"   Dyadic
515    Double# -> Double# -> Double#
516    with commutable = True
517         fixity = infixl 6
518
519 primop   DoubleSubOp   "-##"   Dyadic   Double# -> Double# -> Double#
520    with fixity = infixl 6
521
522 primop   DoubleMulOp   "*##"   Dyadic
523    Double# -> Double# -> Double#
524    with commutable = True
525         fixity = infixl 7
526
527 primop   DoubleDivOp   "/##"   Dyadic
528    Double# -> Double# -> Double#
529    with can_fail = True
530         fixity = infixl 7
531
532 primop   DoubleNegOp   "negateDouble#"  Monadic   Double# -> Double#
533
534 primop   DoubleFabsOp  "fabsDouble#"    Monadic   Double# -> Double#
535
536 primop   Double2IntOp   "double2Int#"          GenPrimOp  Double# -> Int#
537    {Truncates a {\tt Double#} value to the nearest {\tt Int#}.
538     Results are undefined if the truncation if truncation yields
539     a value outside the range of {\tt Int#}.}
540
541 primop   Double2FloatOp   "double2Float#" GenPrimOp Double# -> Float#
542
543 primop   DoubleExpOp   "expDouble#"      Monadic
544    Double# -> Double#
545    with
546    code_size = { primOpCodeSizeForeignCall }
547
548 primop   DoubleLogOp   "logDouble#"      Monadic
549    Double# -> Double#
550    with
551    code_size = { primOpCodeSizeForeignCall }
552    can_fail = True
553
554 primop   DoubleSqrtOp   "sqrtDouble#"      Monadic
555    Double# -> Double#
556    with
557    code_size = { primOpCodeSizeForeignCall }
558
559 primop   DoubleSinOp   "sinDouble#"      Monadic
560    Double# -> Double#
561    with
562    code_size = { primOpCodeSizeForeignCall }
563
564 primop   DoubleCosOp   "cosDouble#"      Monadic
565    Double# -> Double#
566    with
567    code_size = { primOpCodeSizeForeignCall }
568
569 primop   DoubleTanOp   "tanDouble#"      Monadic
570    Double# -> Double#
571    with
572    code_size = { primOpCodeSizeForeignCall }
573
574 primop   DoubleAsinOp   "asinDouble#"      Monadic
575    Double# -> Double#
576    with
577    code_size = { primOpCodeSizeForeignCall }
578    can_fail = True
579
580 primop   DoubleAcosOp   "acosDouble#"      Monadic
581    Double# -> Double#
582    with
583    code_size = { primOpCodeSizeForeignCall }
584    can_fail = True
585
586 primop   DoubleAtanOp   "atanDouble#"      Monadic
587    Double# -> Double#
588    with
589    code_size = { primOpCodeSizeForeignCall }
590
591 primop   DoubleSinhOp   "sinhDouble#"      Monadic
592    Double# -> Double#
593    with
594    code_size = { primOpCodeSizeForeignCall }
595
596 primop   DoubleCoshOp   "coshDouble#"      Monadic
597    Double# -> Double#
598    with
599    code_size = { primOpCodeSizeForeignCall }
600
601 primop   DoubleTanhOp   "tanhDouble#"      Monadic
602    Double# -> Double#
603    with
604    code_size = { primOpCodeSizeForeignCall }
605
606 primop   DoublePowerOp   "**##" Dyadic
607    Double# -> Double# -> Double#
608    {Exponentiation.}
609    with
610    code_size = { primOpCodeSizeForeignCall }
611
612 primop   DoubleDecode_2IntOp   "decodeDouble_2Int#" GenPrimOp
613    Double# -> (# Int#, Word#, Word#, Int# #)
614    {Convert to integer.
615     First component of the result is -1 or 1, indicating the sign of the
616     mantissa. The next two are the high and low 32 bits of the mantissa
617     respectively, and the last is the exponent.}
618    with out_of_line = True
619
620 primop   DoubleDecode_Int64Op   "decodeDouble_Int64#" GenPrimOp
621    Double# -> (# INT64, Int# #)
622    {Decode {\tt Double\#} into mantissa and base-2 exponent.}
623    with out_of_line = True
624
625 ------------------------------------------------------------------------
626 section "Float#"
627         {Operations on single-precision (32-bit) floating-point numbers.}
628 ------------------------------------------------------------------------
629
630 primtype Float#
631
632 primop   FloatGtOp  "gtFloat#"   Compare   Float# -> Float# -> Int#
633 primop   FloatGeOp  "geFloat#"   Compare   Float# -> Float# -> Int#
634
635 primop   FloatEqOp  "eqFloat#"   Compare
636    Float# -> Float# -> Int#
637    with commutable = True
638
639 primop   FloatNeOp  "neFloat#"   Compare
640    Float# -> Float# -> Int#
641    with commutable = True
642
643 primop   FloatLtOp  "ltFloat#"   Compare   Float# -> Float# -> Int#
644 primop   FloatLeOp  "leFloat#"   Compare   Float# -> Float# -> Int#
645
646 primop   FloatAddOp   "plusFloat#"      Dyadic
647    Float# -> Float# -> Float#
648    with commutable = True
649
650 primop   FloatSubOp   "minusFloat#"      Dyadic      Float# -> Float# -> Float#
651
652 primop   FloatMulOp   "timesFloat#"      Dyadic
653    Float# -> Float# -> Float#
654    with commutable = True
655
656 primop   FloatDivOp   "divideFloat#"      Dyadic
657    Float# -> Float# -> Float#
658    with can_fail = True
659
660 primop   FloatNegOp   "negateFloat#"      Monadic    Float# -> Float#
661
662 primop   FloatFabsOp  "fabsFloat#"        Monadic    Float# -> Float#
663
664 primop   Float2IntOp   "float2Int#"      GenPrimOp  Float# -> Int#
665    {Truncates a {\tt Float#} value to the nearest {\tt Int#}.
666     Results are undefined if the truncation if truncation yields
667     a value outside the range of {\tt Int#}.}
668
669 primop   FloatExpOp   "expFloat#"      Monadic
670    Float# -> Float#
671    with
672    code_size = { primOpCodeSizeForeignCall }
673
674 primop   FloatLogOp   "logFloat#"      Monadic
675    Float# -> Float#
676    with
677    code_size = { primOpCodeSizeForeignCall }
678    can_fail = True
679
680 primop   FloatSqrtOp   "sqrtFloat#"      Monadic
681    Float# -> Float#
682    with
683    code_size = { primOpCodeSizeForeignCall }
684
685 primop   FloatSinOp   "sinFloat#"      Monadic
686    Float# -> Float#
687    with
688    code_size = { primOpCodeSizeForeignCall }
689
690 primop   FloatCosOp   "cosFloat#"      Monadic
691    Float# -> Float#
692    with
693    code_size = { primOpCodeSizeForeignCall }
694
695 primop   FloatTanOp   "tanFloat#"      Monadic
696    Float# -> Float#
697    with
698    code_size = { primOpCodeSizeForeignCall }
699
700 primop   FloatAsinOp   "asinFloat#"      Monadic
701    Float# -> Float#
702    with
703    code_size = { primOpCodeSizeForeignCall }
704    can_fail = True
705
706 primop   FloatAcosOp   "acosFloat#"      Monadic
707    Float# -> Float#
708    with
709    code_size = { primOpCodeSizeForeignCall }
710    can_fail = True
711
712 primop   FloatAtanOp   "atanFloat#"      Monadic
713    Float# -> Float#
714    with
715    code_size = { primOpCodeSizeForeignCall }
716
717 primop   FloatSinhOp   "sinhFloat#"      Monadic
718    Float# -> Float#
719    with
720    code_size = { primOpCodeSizeForeignCall }
721
722 primop   FloatCoshOp   "coshFloat#"      Monadic
723    Float# -> Float#
724    with
725    code_size = { primOpCodeSizeForeignCall }
726
727 primop   FloatTanhOp   "tanhFloat#"      Monadic
728    Float# -> Float#
729    with
730    code_size = { primOpCodeSizeForeignCall }
731
732 primop   FloatPowerOp   "powerFloat#"      Dyadic
733    Float# -> Float# -> Float#
734    with
735    code_size = { primOpCodeSizeForeignCall }
736
737 primop   Float2DoubleOp   "float2Double#" GenPrimOp  Float# -> Double#
738
739 primop   FloatDecode_IntOp   "decodeFloat_Int#" GenPrimOp
740    Float# -> (# Int#, Int# #)
741    {Convert to integers.
742     First {\tt Int\#} in result is the mantissa; second is the exponent.}
743    with out_of_line = True
744
745 ------------------------------------------------------------------------
746 section "Arrays"
747         {Operations on {\tt Array\#}.}
748 ------------------------------------------------------------------------
749
750 primtype Array# a
751
752 primtype MutableArray# s a
753
754 primop  NewArrayOp "newArray#" GenPrimOp
755    Int# -> a -> State# s -> (# State# s, MutableArray# s a #)
756    {Create a new mutable array with the specified number of elements,
757     in the specified state thread,
758     with each element containing the specified initial value.}
759    with
760    out_of_line = True
761    has_side_effects = True
762
763 primop  SameMutableArrayOp "sameMutableArray#" GenPrimOp
764    MutableArray# s a -> MutableArray# s a -> Int#
765
766 primop  ReadArrayOp "readArray#" GenPrimOp
767    MutableArray# s a -> Int# -> State# s -> (# State# s, a #)
768    {Read from specified index of mutable array. Result is not yet evaluated.}
769    with
770    has_side_effects = True
771    can_fail         = True
772
773 primop  WriteArrayOp "writeArray#" GenPrimOp
774    MutableArray# s a -> Int# -> a -> State# s -> State# s
775    {Write to specified index of mutable array.}
776    with
777    has_side_effects = True
778    can_fail         = True
779    code_size        = 2 -- card update too
780
781 primop  SizeofArrayOp "sizeofArray#" GenPrimOp
782    Array# a -> Int#
783    {Return the number of elements in the array.}
784
785 primop  SizeofMutableArrayOp "sizeofMutableArray#" GenPrimOp
786    MutableArray# s a -> Int#
787    {Return the number of elements in the array.}
788
789 primop  IndexArrayOp "indexArray#" GenPrimOp
790    Array# a -> Int# -> (# a #)
791    {Read from specified index of immutable array. Result is packaged into
792     an unboxed singleton; the result itself is not yet evaluated.}
793    with
794    can_fail         = True
795
796 primop  UnsafeFreezeArrayOp "unsafeFreezeArray#" GenPrimOp
797    MutableArray# s a -> State# s -> (# State# s, Array# a #)
798    {Make a mutable array immutable, without copying.}
799    with
800    has_side_effects = True
801
802 primop  UnsafeThawArrayOp  "unsafeThawArray#" GenPrimOp
803    Array# a -> State# s -> (# State# s, MutableArray# s a #)
804    {Make an immutable array mutable, without copying.}
805    with
806    out_of_line = True
807    has_side_effects = True
808
809 primop  CopyArrayOp "copyArray#" GenPrimOp
810   Array# a -> Int# -> MutableArray# s a -> Int# -> Int# -> State# s -> State# s
811   {Given a source array, an offset into the source array, a
812    destination array, an offset into the destination array, and a
813    number of elements to copy, copy the elements from the source array
814    to the destination array. Both arrays must fully contain the
815    specified ranges, but this is not checked. The two arrays must not
816    be the same array in different states, but this is not checked
817    either.}
818   with
819   out_of_line      = True
820   has_side_effects = True
821   can_fail         = True
822
823 primop  CopyMutableArrayOp "copyMutableArray#" GenPrimOp
824   MutableArray# s a -> Int# -> MutableArray# s a -> Int# -> Int# -> State# s -> State# s
825   {Given a source array, an offset into the source array, a
826    destination array, an offset into the destination array, and a
827    number of elements to copy, copy the elements from the source array
828    to the destination array. The source and destination arrays can
829    refer to the same array. Both arrays must fully contain the
830    specified ranges, but this is not checked.}
831   with
832   out_of_line      = True
833   has_side_effects = True
834   can_fail         = True
835
836 primop  CloneArrayOp "cloneArray#" GenPrimOp
837   Array# a -> Int# -> Int# -> Array# a
838   {Given a source array, an offset into the source array, and a number
839    of elements to copy, create a new array with the elements from the
840    source array. The provided array must fully contain the specified
841    range, but this is not checked.}
842   with
843   out_of_line      = True
844   has_side_effects = True
845   can_fail         = True
846
847 primop  CloneMutableArrayOp "cloneMutableArray#" GenPrimOp
848   MutableArray# s a -> Int# -> Int# -> State# s -> (# State# s, MutableArray# s a #)
849   {Given a source array, an offset into the source array, and a number
850    of elements to copy, create a new array with the elements from the
851    source array. The provided array must fully contain the specified
852    range, but this is not checked.}
853   with
854   out_of_line      = True
855   has_side_effects = True
856   can_fail         = True
857
858 primop  FreezeArrayOp "freezeArray#" GenPrimOp
859   MutableArray# s a -> Int# -> Int# -> State# s -> (# State# s, Array# a #)
860   {Given a source array, an offset into the source array, and a number
861    of elements to copy, create a new array with the elements from the
862    source array. The provided array must fully contain the specified
863    range, but this is not checked.}
864   with
865   out_of_line      = True
866   has_side_effects = True
867   can_fail         = True
868
869 primop  ThawArrayOp "thawArray#" GenPrimOp
870   Array# a -> Int# -> Int# -> State# s -> (# State# s, MutableArray# s a #)
871   {Given a source array, an offset into the source array, and a number
872    of elements to copy, create a new array with the elements from the
873    source array. The provided array must fully contain the specified
874    range, but this is not checked.}
875   with
876   out_of_line      = True
877   has_side_effects = True
878   can_fail         = True
879
880 primop CasArrayOp  "casArray#" GenPrimOp
881    MutableArray# s a -> Int# -> a -> a -> State# s -> (# State# s, Int#, a #)
882    {Unsafe, machine-level atomic compare and swap on an element within an Array.}
883    with
884    out_of_line = True
885    has_side_effects = True
886
887
888 ------------------------------------------------------------------------
889 section "Small Arrays"
890
891         {Operations on {\tt SmallArray\#}. A {\tt SmallArray\#} works
892          just like an {\tt Array\#}, but with different space use and
893          performance characteristics (that are often useful with small
894          arrays). The {\tt SmallArray\#} and {\tt SmallMutableArray#}
895          lack a `card table'. The purpose of a card table is to avoid
896          having to scan every element of the array on each GC by
897          keeping track of which elements have changed since the last GC
898          and only scanning those that have changed. So the consequence
899          of there being no card table is that the representation is
900          somewhat smaller and the writes are somewhat faster (because
901          the card table does not need to be updated). The disadvantage
902          of course is that for a {\tt SmallMutableArray#} the whole
903          array has to be scanned on each GC. Thus it is best suited for
904          use cases where the mutable array is not long lived, e.g.
905          where a mutable array is initialised quickly and then frozen
906          to become an immutable {\tt SmallArray\#}.
907         }
908
909 ------------------------------------------------------------------------
910
911 primtype SmallArray# a
912
913 primtype SmallMutableArray# s a
914
915 primop  NewSmallArrayOp "newSmallArray#" GenPrimOp
916    Int# -> a -> State# s -> (# State# s, SmallMutableArray# s a #)
917    {Create a new mutable array with the specified number of elements,
918     in the specified state thread,
919     with each element containing the specified initial value.}
920    with
921    out_of_line = True
922    has_side_effects = True
923
924 primop  SameSmallMutableArrayOp "sameSmallMutableArray#" GenPrimOp
925    SmallMutableArray# s a -> SmallMutableArray# s a -> Int#
926
927 primop  ReadSmallArrayOp "readSmallArray#" GenPrimOp
928    SmallMutableArray# s a -> Int# -> State# s -> (# State# s, a #)
929    {Read from specified index of mutable array. Result is not yet evaluated.}
930    with
931    has_side_effects = True
932    can_fail         = True
933
934 primop  WriteSmallArrayOp "writeSmallArray#" GenPrimOp
935    SmallMutableArray# s a -> Int# -> a -> State# s -> State# s
936    {Write to specified index of mutable array.}
937    with
938    has_side_effects = True
939    can_fail         = True
940
941 primop  SizeofSmallArrayOp "sizeofSmallArray#" GenPrimOp
942    SmallArray# a -> Int#
943    {Return the number of elements in the array.}
944
945 primop  SizeofSmallMutableArrayOp "sizeofSmallMutableArray#" GenPrimOp
946    SmallMutableArray# s a -> Int#
947    {Return the number of elements in the array.}
948
949 primop  IndexSmallArrayOp "indexSmallArray#" GenPrimOp
950    SmallArray# a -> Int# -> (# a #)
951    {Read from specified index of immutable array. Result is packaged into
952     an unboxed singleton; the result itself is not yet evaluated.}
953    with
954    can_fail         = True
955
956 primop  UnsafeFreezeSmallArrayOp "unsafeFreezeSmallArray#" GenPrimOp
957    SmallMutableArray# s a -> State# s -> (# State# s, SmallArray# a #)
958    {Make a mutable array immutable, without copying.}
959    with
960    has_side_effects = True
961
962 primop  UnsafeThawSmallArrayOp  "unsafeThawSmallArray#" GenPrimOp
963    SmallArray# a -> State# s -> (# State# s, SmallMutableArray# s a #)
964    {Make an immutable array mutable, without copying.}
965    with
966    out_of_line = True
967    has_side_effects = True
968
969 -- The code_size is only correct for the case when the copy family of
970 -- primops aren't inlined. It would be nice to keep track of both.
971
972 primop  CopySmallArrayOp "copySmallArray#" GenPrimOp
973   SmallArray# a -> Int# -> SmallMutableArray# s a -> Int# -> Int# -> State# s -> State# s
974   {Given a source array, an offset into the source array, a
975    destination array, an offset into the destination array, and a
976    number of elements to copy, copy the elements from the source array
977    to the destination array. Both arrays must fully contain the
978    specified ranges, but this is not checked. The two arrays must not
979    be the same array in different states, but this is not checked
980    either.}
981   with
982   out_of_line      = True
983   has_side_effects = True
984   can_fail         = True
985
986 primop  CopySmallMutableArrayOp "copySmallMutableArray#" GenPrimOp
987   SmallMutableArray# s a -> Int# -> SmallMutableArray# s a -> Int# -> Int# -> State# s -> State# s
988   {Given a source array, an offset into the source array, a
989    destination array, an offset into the destination array, and a
990    number of elements to copy, copy the elements from the source array
991    to the destination array. The source and destination arrays can
992    refer to the same array. Both arrays must fully contain the
993    specified ranges, but this is not checked.}
994   with
995   out_of_line      = True
996   has_side_effects = True
997   can_fail         = True
998
999 primop  CloneSmallArrayOp "cloneSmallArray#" GenPrimOp
1000   SmallArray# a -> Int# -> Int# -> SmallArray# a
1001   {Given a source array, an offset into the source array, and a number
1002    of elements to copy, create a new array with the elements from the
1003    source array. The provided array must fully contain the specified
1004    range, but this is not checked.}
1005   with
1006   out_of_line      = True
1007   has_side_effects = True
1008   can_fail         = True
1009
1010 primop  CloneSmallMutableArrayOp "cloneSmallMutableArray#" GenPrimOp
1011   SmallMutableArray# s a -> Int# -> Int# -> State# s -> (# State# s, SmallMutableArray# s a #)
1012   {Given a source array, an offset into the source array, and a number
1013    of elements to copy, create a new array with the elements from the
1014    source array. The provided array must fully contain the specified
1015    range, but this is not checked.}
1016   with
1017   out_of_line      = True
1018   has_side_effects = True
1019   can_fail         = True
1020
1021 primop  FreezeSmallArrayOp "freezeSmallArray#" GenPrimOp
1022   SmallMutableArray# s a -> Int# -> Int# -> State# s -> (# State# s, SmallArray# a #)
1023   {Given a source array, an offset into the source array, and a number
1024    of elements to copy, create a new array with the elements from the
1025    source array. The provided array must fully contain the specified
1026    range, but this is not checked.}
1027   with
1028   out_of_line      = True
1029   has_side_effects = True
1030   can_fail         = True
1031
1032 primop  ThawSmallArrayOp "thawSmallArray#" GenPrimOp
1033   SmallArray# a -> Int# -> Int# -> State# s -> (# State# s, SmallMutableArray# s a #)
1034   {Given a source array, an offset into the source array, and a number
1035    of elements to copy, create a new array with the elements from the
1036    source array. The provided array must fully contain the specified
1037    range, but this is not checked.}
1038   with
1039   out_of_line      = True
1040   has_side_effects = True
1041   can_fail         = True
1042
1043 primop CasSmallArrayOp  "casSmallArray#" GenPrimOp
1044    SmallMutableArray# s a -> Int# -> a -> a -> State# s -> (# State# s, Int#, a #)
1045    {Unsafe, machine-level atomic compare and swap on an element within an array.}
1046    with
1047    out_of_line = True
1048    has_side_effects = True
1049
1050 ------------------------------------------------------------------------
1051 section "Byte Arrays"
1052         {Operations on {\tt ByteArray\#}. A {\tt ByteArray\#} is a just a region of
1053          raw memory in the garbage-collected heap, which is not
1054          scanned for pointers. It carries its own size (in bytes).
1055          There are
1056          three sets of operations for accessing byte array contents:
1057          index for reading from immutable byte arrays, and read/write
1058          for mutable byte arrays.  Each set contains operations for a
1059          range of useful primitive data types.  Each operation takes
1060          an offset measured in terms of the size of the primitive type
1061          being read or written.}
1062
1063 ------------------------------------------------------------------------
1064
1065 primtype ByteArray#
1066
1067 primtype MutableByteArray# s
1068
1069 primop  NewByteArrayOp_Char "newByteArray#" GenPrimOp
1070    Int# -> State# s -> (# State# s, MutableByteArray# s #)
1071    {Create a new mutable byte array of specified size (in bytes), in
1072     the specified state thread.}
1073    with out_of_line = True
1074         has_side_effects = True
1075
1076 primop  NewPinnedByteArrayOp_Char "newPinnedByteArray#" GenPrimOp
1077    Int# -> State# s -> (# State# s, MutableByteArray# s #)
1078    {Create a mutable byte array that the GC guarantees not to move.}
1079    with out_of_line = True
1080         has_side_effects = True
1081
1082 primop  NewAlignedPinnedByteArrayOp_Char "newAlignedPinnedByteArray#" GenPrimOp
1083    Int# -> Int# -> State# s -> (# State# s, MutableByteArray# s #)
1084    {Create a mutable byte array, aligned by the specified amount, that the GC guarantees not to move.}
1085    with out_of_line = True
1086         has_side_effects = True
1087
1088 primop  MutableByteArrayIsPinnedOp "isMutableByteArrayPinned#" GenPrimOp
1089    MutableByteArray# s -> Int#
1090    {Determine whether a {\tt MutableByteArray\#} is guaranteed not to move
1091    during GC.}
1092    with out_of_line = True
1093
1094 primop  ByteArrayIsPinnedOp "isByteArrayPinned#" GenPrimOp
1095    ByteArray# -> Int#
1096    {Determine whether a {\tt ByteArray\#} is guaranteed not to move during GC.}
1097    with out_of_line = True
1098
1099 primop  ByteArrayContents_Char "byteArrayContents#" GenPrimOp
1100    ByteArray# -> Addr#
1101    {Intended for use with pinned arrays; otherwise very unsafe!}
1102
1103 primop  SameMutableByteArrayOp "sameMutableByteArray#" GenPrimOp
1104    MutableByteArray# s -> MutableByteArray# s -> Int#
1105
1106 primop  ShrinkMutableByteArrayOp_Char "shrinkMutableByteArray#" GenPrimOp
1107    MutableByteArray# s -> Int# -> State# s -> State# s
1108    {Shrink mutable byte array to new specified size (in bytes), in
1109     the specified state thread. The new size argument must be less than or
1110     equal to the current size as reported by {\tt sizeofMutableArray\#}.}
1111    with out_of_line = True
1112         has_side_effects = True
1113
1114 primop  ResizeMutableByteArrayOp_Char "resizeMutableByteArray#" GenPrimOp
1115    MutableByteArray# s -> Int# -> State# s -> (# State# s,MutableByteArray# s #)
1116    {Resize (unpinned) mutable byte array to new specified size (in bytes).
1117     The returned {\tt MutableByteArray\#} is either the original
1118     {\tt MutableByteArray\#} resized in-place or, if not possible, a newly
1119     allocated (unpinned) {\tt MutableByteArray\#} (with the original content
1120     copied over).
1121
1122     To avoid undefined behaviour, the original {\tt MutableByteArray\#} shall
1123     not be accessed anymore after a {\tt resizeMutableByteArray\#} has been
1124     performed.  Moreover, no reference to the old one should be kept in order
1125     to allow garbage collection of the original {\tt MutableByteArray\#} in
1126     case a new {\tt MutableByteArray\#} had to be allocated.}
1127    with out_of_line = True
1128         has_side_effects = True
1129
1130 primop  UnsafeFreezeByteArrayOp "unsafeFreezeByteArray#" GenPrimOp
1131    MutableByteArray# s -> State# s -> (# State# s, ByteArray# #)
1132    {Make a mutable byte array immutable, without copying.}
1133    with
1134    has_side_effects = True
1135
1136 primop  SizeofByteArrayOp "sizeofByteArray#" GenPrimOp
1137    ByteArray# -> Int#
1138    {Return the size of the array in bytes.}
1139
1140 primop  SizeofMutableByteArrayOp "sizeofMutableByteArray#" GenPrimOp
1141    MutableByteArray# s -> Int#
1142    {Return the size of the array in bytes. Note that this is deprecated as it is
1143    unsafe in the presence of concurrent resize operations on the same byte
1144    array. See {\tt getSizeofMutableByteArray}.}
1145
1146 primop  GetSizeofMutableByteArrayOp "getSizeofMutableByteArray#" GenPrimOp
1147    MutableByteArray# s -> State# s -> (# State# s, Int# #)
1148    {Return the number of elements in the array.}
1149
1150 primop IndexByteArrayOp_Char "indexCharArray#" GenPrimOp
1151    ByteArray# -> Int# -> Char#
1152    {Read 8-bit character; offset in bytes.}
1153    with can_fail = True
1154
1155 primop IndexByteArrayOp_WideChar "indexWideCharArray#" GenPrimOp
1156    ByteArray# -> Int# -> Char#
1157    {Read 31-bit character; offset in 4-byte words.}
1158    with can_fail = True
1159
1160 primop IndexByteArrayOp_Int "indexIntArray#" GenPrimOp
1161    ByteArray# -> Int# -> Int#
1162    with can_fail = True
1163
1164 primop IndexByteArrayOp_Word "indexWordArray#" GenPrimOp
1165    ByteArray# -> Int# -> Word#
1166    with can_fail = True
1167
1168 primop IndexByteArrayOp_Addr "indexAddrArray#" GenPrimOp
1169    ByteArray# -> Int# -> Addr#
1170    with can_fail = True
1171
1172 primop IndexByteArrayOp_Float "indexFloatArray#" GenPrimOp
1173    ByteArray# -> Int# -> Float#
1174    with can_fail = True
1175
1176 primop IndexByteArrayOp_Double "indexDoubleArray#" GenPrimOp
1177    ByteArray# -> Int# -> Double#
1178    with can_fail = True
1179
1180 primop IndexByteArrayOp_StablePtr "indexStablePtrArray#" GenPrimOp
1181    ByteArray# -> Int# -> StablePtr# a
1182    with can_fail = True
1183
1184 primop IndexByteArrayOp_Int8 "indexInt8Array#" GenPrimOp
1185    ByteArray# -> Int# -> Int#
1186    {Read 8-bit integer; offset in bytes.}
1187    with can_fail = True
1188
1189 primop IndexByteArrayOp_Int16 "indexInt16Array#" GenPrimOp
1190    ByteArray# -> Int# -> Int#
1191    {Read 16-bit integer; offset in 16-bit words.}
1192    with can_fail = True
1193
1194 primop IndexByteArrayOp_Int32 "indexInt32Array#" GenPrimOp
1195    ByteArray# -> Int# -> INT32
1196    {Read 32-bit integer; offset in 32-bit words.}
1197    with can_fail = True
1198
1199 primop IndexByteArrayOp_Int64 "indexInt64Array#" GenPrimOp
1200    ByteArray# -> Int# -> INT64
1201    {Read 64-bit integer; offset in 64-bit words.}
1202    with can_fail = True
1203
1204 primop IndexByteArrayOp_Word8 "indexWord8Array#" GenPrimOp
1205    ByteArray# -> Int# -> Word#
1206    {Read 8-bit word; offset in bytes.}
1207    with can_fail = True
1208
1209 primop IndexByteArrayOp_Word16 "indexWord16Array#" GenPrimOp
1210    ByteArray# -> Int# -> Word#
1211    {Read 16-bit word; offset in 16-bit words.}
1212    with can_fail = True
1213
1214 primop IndexByteArrayOp_Word32 "indexWord32Array#" GenPrimOp
1215    ByteArray# -> Int# -> WORD32
1216    {Read 32-bit word; offset in 32-bit words.}
1217    with can_fail = True
1218
1219 primop IndexByteArrayOp_Word64 "indexWord64Array#" GenPrimOp
1220    ByteArray# -> Int# -> WORD64
1221    {Read 64-bit word; offset in 64-bit words.}
1222    with can_fail = True
1223
1224 primop  ReadByteArrayOp_Char "readCharArray#" GenPrimOp
1225    MutableByteArray# s -> Int# -> State# s -> (# State# s, Char# #)
1226    {Read 8-bit character; offset in bytes.}
1227    with has_side_effects = True
1228         can_fail = True
1229
1230 primop  ReadByteArrayOp_WideChar "readWideCharArray#" GenPrimOp
1231    MutableByteArray# s -> Int# -> State# s -> (# State# s, Char# #)
1232    {Read 31-bit character; offset in 4-byte words.}
1233    with has_side_effects = True
1234         can_fail = True
1235
1236 primop  ReadByteArrayOp_Int "readIntArray#" GenPrimOp
1237    MutableByteArray# s -> Int# -> State# s -> (# State# s, Int# #)
1238    {Read intger; offset in words.}
1239    with has_side_effects = True
1240         can_fail = True
1241
1242 primop  ReadByteArrayOp_Word "readWordArray#" GenPrimOp
1243    MutableByteArray# s -> Int# -> State# s -> (# State# s, Word# #)
1244    {Read word; offset in words.}
1245    with has_side_effects = True
1246         can_fail = True
1247
1248 primop  ReadByteArrayOp_Addr "readAddrArray#" GenPrimOp
1249    MutableByteArray# s -> Int# -> State# s -> (# State# s, Addr# #)
1250    with has_side_effects = True
1251         can_fail = True
1252
1253 primop  ReadByteArrayOp_Float "readFloatArray#" GenPrimOp
1254    MutableByteArray# s -> Int# -> State# s -> (# State# s, Float# #)
1255    with has_side_effects = True
1256         can_fail = True
1257
1258 primop  ReadByteArrayOp_Double "readDoubleArray#" GenPrimOp
1259    MutableByteArray# s -> Int# -> State# s -> (# State# s, Double# #)
1260    with has_side_effects = True
1261         can_fail = True
1262
1263 primop  ReadByteArrayOp_StablePtr "readStablePtrArray#" GenPrimOp
1264    MutableByteArray# s -> Int# -> State# s -> (# State# s, StablePtr# a #)
1265    with has_side_effects = True
1266         can_fail = True
1267
1268 primop  ReadByteArrayOp_Int8 "readInt8Array#" GenPrimOp
1269    MutableByteArray# s -> Int# -> State# s -> (# State# s, Int# #)
1270    with has_side_effects = True
1271         can_fail = True
1272
1273 primop  ReadByteArrayOp_Int16 "readInt16Array#" GenPrimOp
1274    MutableByteArray# s -> Int# -> State# s -> (# State# s, Int# #)
1275    with has_side_effects = True
1276         can_fail = True
1277
1278 primop  ReadByteArrayOp_Int32 "readInt32Array#" GenPrimOp
1279    MutableByteArray# s -> Int# -> State# s -> (# State# s, INT32 #)
1280    with has_side_effects = True
1281         can_fail = True
1282
1283 primop  ReadByteArrayOp_Int64 "readInt64Array#" GenPrimOp
1284    MutableByteArray# s -> Int# -> State# s -> (# State# s, INT64 #)
1285    with has_side_effects = True
1286         can_fail = True
1287
1288 primop  ReadByteArrayOp_Word8 "readWord8Array#" GenPrimOp
1289    MutableByteArray# s -> Int# -> State# s -> (# State# s, Word# #)
1290    with has_side_effects = True
1291         can_fail = True
1292
1293 primop  ReadByteArrayOp_Word16 "readWord16Array#" GenPrimOp
1294    MutableByteArray# s -> Int# -> State# s -> (# State# s, Word# #)
1295    with has_side_effects = True
1296         can_fail = True
1297
1298 primop  ReadByteArrayOp_Word32 "readWord32Array#" GenPrimOp
1299    MutableByteArray# s -> Int# -> State# s -> (# State# s, WORD32 #)
1300    with has_side_effects = True
1301         can_fail = True
1302
1303 primop  ReadByteArrayOp_Word64 "readWord64Array#" GenPrimOp
1304    MutableByteArray# s -> Int# -> State# s -> (# State# s, WORD64 #)
1305    with has_side_effects = True
1306         can_fail = True
1307
1308 primop  WriteByteArrayOp_Char "writeCharArray#" GenPrimOp
1309    MutableByteArray# s -> Int# -> Char# -> State# s -> State# s
1310    {Write 8-bit character; offset in bytes.}
1311    with has_side_effects = True
1312         can_fail = True
1313
1314 primop  WriteByteArrayOp_WideChar "writeWideCharArray#" GenPrimOp
1315    MutableByteArray# s -> Int# -> Char# -> State# s -> State# s
1316    {Write 31-bit character; offset in 4-byte words.}
1317    with has_side_effects = True
1318         can_fail = True
1319
1320 primop  WriteByteArrayOp_Int "writeIntArray#" GenPrimOp
1321    MutableByteArray# s -> Int# -> Int# -> State# s -> State# s
1322    with has_side_effects = True
1323         can_fail = True
1324
1325 primop  WriteByteArrayOp_Word "writeWordArray#" GenPrimOp
1326    MutableByteArray# s -> Int# -> Word# -> State# s -> State# s
1327    with has_side_effects = True
1328         can_fail = True
1329
1330 primop  WriteByteArrayOp_Addr "writeAddrArray#" GenPrimOp
1331    MutableByteArray# s -> Int# -> Addr# -> State# s -> State# s
1332    with has_side_effects = True
1333         can_fail = True
1334
1335 primop  WriteByteArrayOp_Float "writeFloatArray#" GenPrimOp
1336    MutableByteArray# s -> Int# -> Float# -> State# s -> State# s
1337    with has_side_effects = True
1338         can_fail = True
1339
1340 primop  WriteByteArrayOp_Double "writeDoubleArray#" GenPrimOp
1341    MutableByteArray# s -> Int# -> Double# -> State# s -> State# s
1342    with has_side_effects = True
1343         can_fail = True
1344
1345 primop  WriteByteArrayOp_StablePtr "writeStablePtrArray#" GenPrimOp
1346    MutableByteArray# s -> Int# -> StablePtr# a -> State# s -> State# s
1347    with has_side_effects = True
1348         can_fail = True
1349
1350 primop  WriteByteArrayOp_Int8 "writeInt8Array#" GenPrimOp
1351    MutableByteArray# s -> Int# -> Int# -> State# s -> State# s
1352    with has_side_effects = True
1353         can_fail = True
1354
1355 primop  WriteByteArrayOp_Int16 "writeInt16Array#" GenPrimOp
1356    MutableByteArray# s -> Int# -> Int# -> State# s -> State# s
1357    with has_side_effects = True
1358         can_fail = True
1359
1360 primop  WriteByteArrayOp_Int32 "writeInt32Array#" GenPrimOp
1361    MutableByteArray# s -> Int# -> INT32 -> State# s -> State# s
1362    with has_side_effects = True
1363         can_fail = True
1364
1365 primop  WriteByteArrayOp_Int64 "writeInt64Array#" GenPrimOp
1366    MutableByteArray# s -> Int# -> INT64 -> State# s -> State# s
1367    with can_fail = True
1368         has_side_effects = True
1369
1370 primop  WriteByteArrayOp_Word8 "writeWord8Array#" GenPrimOp
1371    MutableByteArray# s -> Int# -> Word# -> State# s -> State# s
1372    with has_side_effects = True
1373         can_fail = True
1374
1375 primop  WriteByteArrayOp_Word16 "writeWord16Array#" GenPrimOp
1376    MutableByteArray# s -> Int# -> Word# -> State# s -> State# s
1377    with has_side_effects = True
1378         can_fail = True
1379
1380 primop  WriteByteArrayOp_Word32 "writeWord32Array#" GenPrimOp
1381    MutableByteArray# s -> Int# -> WORD32 -> State# s -> State# s
1382    with has_side_effects = True
1383         can_fail = True
1384
1385 primop  WriteByteArrayOp_Word64 "writeWord64Array#" GenPrimOp
1386    MutableByteArray# s -> Int# -> WORD64 -> State# s -> State# s
1387    with has_side_effects = True
1388         can_fail = True
1389
1390 primop  CopyByteArrayOp "copyByteArray#" GenPrimOp
1391   ByteArray# -> Int# -> MutableByteArray# s -> Int# -> Int# -> State# s -> State# s
1392   {Copy a range of the ByteArray# to the specified region in the MutableByteArray#.
1393    Both arrays must fully contain the specified ranges, but this is not checked.
1394    The two arrays must not be the same array in different states, but this is not checked either.}
1395   with
1396   has_side_effects = True
1397   code_size = { primOpCodeSizeForeignCall + 4}
1398   can_fail = True
1399
1400 primop  CopyMutableByteArrayOp "copyMutableByteArray#" GenPrimOp
1401   MutableByteArray# s -> Int# -> MutableByteArray# s -> Int# -> Int# -> State# s -> State# s
1402   {Copy a range of the first MutableByteArray# to the specified region in the second MutableByteArray#.
1403    Both arrays must fully contain the specified ranges, but this is not checked.}
1404   with
1405   has_side_effects = True
1406   code_size = { primOpCodeSizeForeignCall + 4 }
1407   can_fail = True
1408
1409 primop  CopyByteArrayToAddrOp "copyByteArrayToAddr#" GenPrimOp
1410   ByteArray# -> Int# -> Addr# -> Int# -> State# s -> State# s
1411   {Copy a range of the ByteArray# to the memory range starting at the Addr#.
1412    The ByteArray# and the memory region at Addr# must fully contain the
1413    specified ranges, but this is not checked. The Addr# must not point into the
1414    ByteArray# (e.g. if the ByteArray# were pinned), but this is not checked
1415    either.}
1416   with
1417   has_side_effects = True
1418   code_size = { primOpCodeSizeForeignCall + 4}
1419   can_fail = True
1420
1421 primop  CopyMutableByteArrayToAddrOp "copyMutableByteArrayToAddr#" GenPrimOp
1422   MutableByteArray# s -> Int# -> Addr# -> Int# -> State# s -> State# s
1423   {Copy a range of the MutableByteArray# to the memory range starting at the
1424    Addr#. The MutableByteArray# and the memory region at Addr# must fully
1425    contain the specified ranges, but this is not checked. The Addr# must not
1426    point into the MutableByteArray# (e.g. if the MutableByteArray# were
1427    pinned), but this is not checked either.}
1428   with
1429   has_side_effects = True
1430   code_size = { primOpCodeSizeForeignCall + 4}
1431   can_fail = True
1432
1433 primop  CopyAddrToByteArrayOp "copyAddrToByteArray#" GenPrimOp
1434   Addr# -> MutableByteArray# s -> Int# -> Int# -> State# s -> State# s
1435   {Copy a memory range starting at the Addr# to the specified range in the
1436    MutableByteArray#. The memory region at Addr# and the ByteArray# must fully
1437    contain the specified ranges, but this is not checked. The Addr# must not
1438    point into the MutableByteArray# (e.g. if the MutableByteArray# were pinned),
1439    but this is not checked either.}
1440   with
1441   has_side_effects = True
1442   code_size = { primOpCodeSizeForeignCall + 4}
1443   can_fail = True
1444
1445 primop  SetByteArrayOp "setByteArray#" GenPrimOp
1446   MutableByteArray# s -> Int# -> Int# -> Int# -> State# s -> State# s
1447   {{\tt setByteArray# ba off len c} sets the byte range {\tt [off, off+len]} of
1448    the {\tt MutableByteArray#} to the byte {\tt c}.}
1449   with
1450   has_side_effects = True
1451   code_size = { primOpCodeSizeForeignCall + 4 }
1452   can_fail = True
1453
1454 -- Atomic operations
1455
1456 primop  AtomicReadByteArrayOp_Int "atomicReadIntArray#" GenPrimOp
1457    MutableByteArray# s -> Int# -> State# s -> (# State# s, Int# #)
1458    {Given an array and an offset in Int units, read an element. The
1459     index is assumed to be in bounds. Implies a full memory barrier.}
1460    with has_side_effects = True
1461         can_fail = True
1462
1463 primop  AtomicWriteByteArrayOp_Int "atomicWriteIntArray#" GenPrimOp
1464    MutableByteArray# s -> Int# -> Int# -> State# s -> State# s
1465    {Given an array and an offset in Int units, write an element. The
1466     index is assumed to be in bounds. Implies a full memory barrier.}
1467    with has_side_effects = True
1468         can_fail = True
1469
1470 primop CasByteArrayOp_Int "casIntArray#" GenPrimOp
1471    MutableByteArray# s -> Int# -> Int# -> Int# -> State# s -> (# State# s, Int# #)
1472    {Given an array, an offset in Int units, the expected old value, and
1473     the new value, perform an atomic compare and swap i.e. write the new
1474     value if the current value matches the provided old value. Returns
1475     the value of the element before the operation. Implies a full memory
1476     barrier.}
1477    with has_side_effects = True
1478         can_fail = True
1479
1480 primop FetchAddByteArrayOp_Int "fetchAddIntArray#" GenPrimOp
1481    MutableByteArray# s -> Int# -> Int# -> State# s -> (# State# s, Int# #)
1482    {Given an array, and offset in Int units, and a value to add,
1483     atomically add the value to the element. Returns the value of the
1484     element before the operation. Implies a full memory barrier.}
1485    with has_side_effects = True
1486         can_fail = True
1487
1488 primop FetchSubByteArrayOp_Int "fetchSubIntArray#" GenPrimOp
1489    MutableByteArray# s -> Int# -> Int# -> State# s -> (# State# s, Int# #)
1490    {Given an array, and offset in Int units, and a value to subtract,
1491     atomically substract the value to the element. Returns the value of
1492     the element before the operation. Implies a full memory barrier.}
1493    with has_side_effects = True
1494         can_fail = True
1495
1496 primop FetchAndByteArrayOp_Int "fetchAndIntArray#" GenPrimOp
1497    MutableByteArray# s -> Int# -> Int# -> State# s -> (# State# s, Int# #)
1498    {Given an array, and offset in Int units, and a value to AND,
1499     atomically AND the value to the element. Returns the value of the
1500     element before the operation. Implies a full memory barrier.}
1501    with has_side_effects = True
1502         can_fail = True
1503
1504 primop FetchNandByteArrayOp_Int "fetchNandIntArray#" GenPrimOp
1505    MutableByteArray# s -> Int# -> Int# -> State# s -> (# State# s, Int# #)
1506    {Given an array, and offset in Int units, and a value to NAND,
1507     atomically NAND the value to the element. Returns the value of the
1508     element before the operation. Implies a full memory barrier.}
1509    with has_side_effects = True
1510         can_fail = True
1511
1512 primop FetchOrByteArrayOp_Int "fetchOrIntArray#" GenPrimOp
1513    MutableByteArray# s -> Int# -> Int# -> State# s -> (# State# s, Int# #)
1514    {Given an array, and offset in Int units, and a value to OR,
1515     atomically OR the value to the element. Returns the value of the
1516     element before the operation. Implies a full memory barrier.}
1517    with has_side_effects = True
1518         can_fail = True
1519
1520 primop FetchXorByteArrayOp_Int "fetchXorIntArray#" GenPrimOp
1521    MutableByteArray# s -> Int# -> Int# -> State# s -> (# State# s, Int# #)
1522    {Given an array, and offset in Int units, and a value to XOR,
1523     atomically XOR the value to the element. Returns the value of the
1524     element before the operation. Implies a full memory barrier.}
1525    with has_side_effects = True
1526         can_fail = True
1527
1528
1529 ------------------------------------------------------------------------
1530 section "Arrays of arrays"
1531         {Operations on {\tt ArrayArray\#}. An {\tt ArrayArray\#} contains references to {\em unpointed}
1532          arrays, such as {\tt ByteArray\#s}. Hence, it is not parameterised by the element types,
1533          just like a {\tt ByteArray\#}, but it needs to be scanned during GC, just like an {\tt Array#}.
1534          We represent an {\tt ArrayArray\#} exactly as a {\tt Array\#}, but provide element-type-specific
1535          indexing, reading, and writing.}
1536 ------------------------------------------------------------------------
1537
1538 primtype ArrayArray#
1539
1540 primtype MutableArrayArray# s
1541
1542 primop  NewArrayArrayOp "newArrayArray#" GenPrimOp
1543    Int# -> State# s -> (# State# s, MutableArrayArray# s #)
1544    {Create a new mutable array of arrays with the specified number of elements,
1545     in the specified state thread, with each element recursively referring to the
1546     newly created array.}
1547    with
1548    out_of_line = True
1549    has_side_effects = True
1550
1551 primop  SameMutableArrayArrayOp "sameMutableArrayArray#" GenPrimOp
1552    MutableArrayArray# s -> MutableArrayArray# s -> Int#
1553
1554 primop  UnsafeFreezeArrayArrayOp "unsafeFreezeArrayArray#" GenPrimOp
1555    MutableArrayArray# s -> State# s -> (# State# s, ArrayArray# #)
1556    {Make a mutable array of arrays immutable, without copying.}
1557    with
1558    has_side_effects = True
1559
1560 primop  SizeofArrayArrayOp "sizeofArrayArray#" GenPrimOp
1561    ArrayArray# -> Int#
1562    {Return the number of elements in the array.}
1563
1564 primop  SizeofMutableArrayArrayOp "sizeofMutableArrayArray#" GenPrimOp
1565    MutableArrayArray# s -> Int#
1566    {Return the number of elements in the array.}
1567
1568 primop IndexArrayArrayOp_ByteArray "indexByteArrayArray#" GenPrimOp
1569    ArrayArray# -> Int# -> ByteArray#
1570    with can_fail = True
1571
1572 primop IndexArrayArrayOp_ArrayArray "indexArrayArrayArray#" GenPrimOp
1573    ArrayArray# -> Int# -> ArrayArray#
1574    with can_fail = True
1575
1576 primop  ReadArrayArrayOp_ByteArray "readByteArrayArray#" GenPrimOp
1577    MutableArrayArray# s -> Int# -> State# s -> (# State# s, ByteArray# #)
1578    with has_side_effects = True
1579         can_fail = True
1580
1581 primop  ReadArrayArrayOp_MutableByteArray "readMutableByteArrayArray#" GenPrimOp
1582    MutableArrayArray# s -> Int# -> State# s -> (# State# s, MutableByteArray# s #)
1583    with has_side_effects = True
1584         can_fail = True
1585
1586 primop  ReadArrayArrayOp_ArrayArray "readArrayArrayArray#" GenPrimOp
1587    MutableArrayArray# s -> Int# -> State# s -> (# State# s, ArrayArray# #)
1588    with has_side_effects = True
1589         can_fail = True
1590
1591 primop  ReadArrayArrayOp_MutableArrayArray "readMutableArrayArrayArray#" GenPrimOp
1592    MutableArrayArray# s -> Int# -> State# s -> (# State# s, MutableArrayArray# s #)
1593    with has_side_effects = True
1594         can_fail = True
1595
1596 primop  WriteArrayArrayOp_ByteArray "writeByteArrayArray#" GenPrimOp
1597    MutableArrayArray# s -> Int# -> ByteArray# -> State# s -> State# s
1598    with has_side_effects = True
1599         can_fail = True
1600
1601 primop  WriteArrayArrayOp_MutableByteArray "writeMutableByteArrayArray#" GenPrimOp
1602    MutableArrayArray# s -> Int# -> MutableByteArray# s -> State# s -> State# s
1603    with has_side_effects = True
1604         can_fail = True
1605
1606 primop  WriteArrayArrayOp_ArrayArray "writeArrayArrayArray#" GenPrimOp
1607    MutableArrayArray# s -> Int# -> ArrayArray# -> State# s -> State# s
1608    with has_side_effects = True
1609         can_fail = True
1610
1611 primop  WriteArrayArrayOp_MutableArrayArray "writeMutableArrayArrayArray#" GenPrimOp
1612    MutableArrayArray# s -> Int# -> MutableArrayArray# s -> State# s -> State# s
1613    with has_side_effects = True
1614         can_fail = True
1615
1616 primop  CopyArrayArrayOp "copyArrayArray#" GenPrimOp
1617   ArrayArray# -> Int# -> MutableArrayArray# s -> Int# -> Int# -> State# s -> State# s
1618   {Copy a range of the ArrayArray# to the specified region in the MutableArrayArray#.
1619    Both arrays must fully contain the specified ranges, but this is not checked.
1620    The two arrays must not be the same array in different states, but this is not checked either.}
1621   with
1622   out_of_line      = True
1623   has_side_effects = True
1624   can_fail         = True
1625
1626 primop  CopyMutableArrayArrayOp "copyMutableArrayArray#" GenPrimOp
1627   MutableArrayArray# s -> Int# -> MutableArrayArray# s -> Int# -> Int# -> State# s -> State# s
1628   {Copy a range of the first MutableArrayArray# to the specified region in the second
1629    MutableArrayArray#.
1630    Both arrays must fully contain the specified ranges, but this is not checked.}
1631   with
1632   out_of_line      = True
1633   has_side_effects = True
1634   can_fail         = True
1635
1636 ------------------------------------------------------------------------
1637 section "Addr#"
1638 ------------------------------------------------------------------------
1639
1640 primtype Addr#
1641         { An arbitrary machine address assumed to point outside
1642          the garbage-collected heap. }
1643
1644 pseudoop "nullAddr#" Addr#
1645         { The null address. }
1646
1647 primop   AddrAddOp "plusAddr#" GenPrimOp Addr# -> Int# -> Addr#
1648 primop   AddrSubOp "minusAddr#" GenPrimOp Addr# -> Addr# -> Int#
1649          {Result is meaningless if two {\tt Addr\#}s are so far apart that their
1650          difference doesn't fit in an {\tt Int\#}.}
1651 primop   AddrRemOp "remAddr#" GenPrimOp Addr# -> Int# -> Int#
1652          {Return the remainder when the {\tt Addr\#} arg, treated like an {\tt Int\#},
1653           is divided by the {\tt Int\#} arg.}
1654 #if (WORD_SIZE_IN_BITS == 32 || WORD_SIZE_IN_BITS == 64)
1655 primop   Addr2IntOp  "addr2Int#"     GenPrimOp   Addr# -> Int#
1656         {Coerce directly from address to int. Strongly deprecated.}
1657    with code_size = 0
1658 primop   Int2AddrOp   "int2Addr#"    GenPrimOp  Int# -> Addr#
1659         {Coerce directly from int to address. Strongly deprecated.}
1660    with code_size = 0
1661 #endif
1662
1663 primop   AddrGtOp  "gtAddr#"   Compare   Addr# -> Addr# -> Int#
1664 primop   AddrGeOp  "geAddr#"   Compare   Addr# -> Addr# -> Int#
1665 primop   AddrEqOp  "eqAddr#"   Compare   Addr# -> Addr# -> Int#
1666 primop   AddrNeOp  "neAddr#"   Compare   Addr# -> Addr# -> Int#
1667 primop   AddrLtOp  "ltAddr#"   Compare   Addr# -> Addr# -> Int#
1668 primop   AddrLeOp  "leAddr#"   Compare   Addr# -> Addr# -> Int#
1669
1670 primop IndexOffAddrOp_Char "indexCharOffAddr#" GenPrimOp
1671    Addr# -> Int# -> Char#
1672    {Reads 8-bit character; offset in bytes.}
1673    with can_fail = True
1674
1675 primop IndexOffAddrOp_WideChar "indexWideCharOffAddr#" GenPrimOp
1676    Addr# -> Int# -> Char#
1677    {Reads 31-bit character; offset in 4-byte words.}
1678    with can_fail = True
1679
1680 primop IndexOffAddrOp_Int "indexIntOffAddr#" GenPrimOp
1681    Addr# -> Int# -> Int#
1682    with can_fail = True
1683
1684 primop IndexOffAddrOp_Word "indexWordOffAddr#" GenPrimOp
1685    Addr# -> Int# -> Word#
1686    with can_fail = True
1687
1688 primop IndexOffAddrOp_Addr "indexAddrOffAddr#" GenPrimOp
1689    Addr# -> Int# -> Addr#
1690    with can_fail = True
1691
1692 primop IndexOffAddrOp_Float "indexFloatOffAddr#" GenPrimOp
1693    Addr# -> Int# -> Float#
1694    with can_fail = True
1695
1696 primop IndexOffAddrOp_Double "indexDoubleOffAddr#" GenPrimOp
1697    Addr# -> Int# -> Double#
1698    with can_fail = True
1699
1700 primop IndexOffAddrOp_StablePtr "indexStablePtrOffAddr#" GenPrimOp
1701    Addr# -> Int# -> StablePtr# a
1702    with can_fail = True
1703
1704 primop IndexOffAddrOp_Int8 "indexInt8OffAddr#" GenPrimOp
1705    Addr# -> Int# -> Int#
1706    with can_fail = True
1707
1708 primop IndexOffAddrOp_Int16 "indexInt16OffAddr#" GenPrimOp
1709    Addr# -> Int# -> Int#
1710    with can_fail = True
1711
1712 primop IndexOffAddrOp_Int32 "indexInt32OffAddr#" GenPrimOp
1713    Addr# -> Int# -> INT32
1714    with can_fail = True
1715
1716 primop IndexOffAddrOp_Int64 "indexInt64OffAddr#" GenPrimOp
1717    Addr# -> Int# -> INT64
1718    with can_fail = True
1719
1720 primop IndexOffAddrOp_Word8 "indexWord8OffAddr#" GenPrimOp
1721    Addr# -> Int# -> Word#
1722    with can_fail = True
1723
1724 primop IndexOffAddrOp_Word16 "indexWord16OffAddr#" GenPrimOp
1725    Addr# -> Int# -> Word#
1726    with can_fail = True
1727
1728 primop IndexOffAddrOp_Word32 "indexWord32OffAddr#" GenPrimOp
1729    Addr# -> Int# -> WORD32
1730    with can_fail = True
1731
1732 primop IndexOffAddrOp_Word64 "indexWord64OffAddr#" GenPrimOp
1733    Addr# -> Int# -> WORD64
1734    with can_fail = True
1735
1736 primop ReadOffAddrOp_Char "readCharOffAddr#" GenPrimOp
1737    Addr# -> Int# -> State# s -> (# State# s, Char# #)
1738    {Reads 8-bit character; offset in bytes.}
1739    with has_side_effects = True
1740         can_fail         = True
1741
1742 primop ReadOffAddrOp_WideChar "readWideCharOffAddr#" GenPrimOp
1743    Addr# -> Int# -> State# s -> (# State# s, Char# #)
1744    {Reads 31-bit character; offset in 4-byte words.}
1745    with has_side_effects = True
1746         can_fail         = True
1747
1748 primop ReadOffAddrOp_Int "readIntOffAddr#" GenPrimOp
1749    Addr# -> Int# -> State# s -> (# State# s, Int# #)
1750    with has_side_effects = True
1751         can_fail         = True
1752
1753 primop ReadOffAddrOp_Word "readWordOffAddr#" GenPrimOp
1754    Addr# -> Int# -> State# s -> (# State# s, Word# #)
1755    with has_side_effects = True
1756         can_fail         = True
1757
1758 primop ReadOffAddrOp_Addr "readAddrOffAddr#" GenPrimOp
1759    Addr# -> Int# -> State# s -> (# State# s, Addr# #)
1760    with has_side_effects = True
1761         can_fail         = True
1762
1763 primop ReadOffAddrOp_Float "readFloatOffAddr#" GenPrimOp
1764    Addr# -> Int# -> State# s -> (# State# s, Float# #)
1765    with has_side_effects = True
1766         can_fail         = True
1767
1768 primop ReadOffAddrOp_Double "readDoubleOffAddr#" GenPrimOp
1769    Addr# -> Int# -> State# s -> (# State# s, Double# #)
1770    with has_side_effects = True
1771         can_fail         = True
1772
1773 primop ReadOffAddrOp_StablePtr "readStablePtrOffAddr#" GenPrimOp
1774    Addr# -> Int# -> State# s -> (# State# s, StablePtr# a #)
1775    with has_side_effects = True
1776         can_fail         = True
1777
1778 primop ReadOffAddrOp_Int8 "readInt8OffAddr#" GenPrimOp
1779    Addr# -> Int# -> State# s -> (# State# s, Int# #)
1780    with has_side_effects = True
1781         can_fail         = True
1782
1783 primop ReadOffAddrOp_Int16 "readInt16OffAddr#" GenPrimOp
1784    Addr# -> Int# -> State# s -> (# State# s, Int# #)
1785    with has_side_effects = True
1786         can_fail         = True
1787
1788 primop ReadOffAddrOp_Int32 "readInt32OffAddr#" GenPrimOp
1789    Addr# -> Int# -> State# s -> (# State# s, INT32 #)
1790    with has_side_effects = True
1791         can_fail         = True
1792
1793 primop ReadOffAddrOp_Int64 "readInt64OffAddr#" GenPrimOp
1794    Addr# -> Int# -> State# s -> (# State# s, INT64 #)
1795    with has_side_effects = True
1796         can_fail         = True
1797
1798 primop ReadOffAddrOp_Word8 "readWord8OffAddr#" GenPrimOp
1799    Addr# -> Int# -> State# s -> (# State# s, Word# #)
1800    with has_side_effects = True
1801         can_fail         = True
1802
1803 primop ReadOffAddrOp_Word16 "readWord16OffAddr#" GenPrimOp
1804    Addr# -> Int# -> State# s -> (# State# s, Word# #)
1805    with has_side_effects = True
1806         can_fail         = True
1807
1808 primop ReadOffAddrOp_Word32 "readWord32OffAddr#" GenPrimOp
1809    Addr# -> Int# -> State# s -> (# State# s, WORD32 #)
1810    with has_side_effects = True
1811         can_fail         = True
1812
1813 primop ReadOffAddrOp_Word64 "readWord64OffAddr#" GenPrimOp
1814    Addr# -> Int# -> State# s -> (# State# s, WORD64 #)
1815    with has_side_effects = True
1816         can_fail         = True
1817
1818 primop  WriteOffAddrOp_Char "writeCharOffAddr#" GenPrimOp
1819    Addr# -> Int# -> Char# -> State# s -> State# s
1820    with has_side_effects = True
1821         can_fail         = True
1822
1823 primop  WriteOffAddrOp_WideChar "writeWideCharOffAddr#" GenPrimOp
1824    Addr# -> Int# -> Char# -> State# s -> State# s
1825    with has_side_effects = True
1826         can_fail         = True
1827
1828 primop  WriteOffAddrOp_Int "writeIntOffAddr#" GenPrimOp
1829    Addr# -> Int# -> Int# -> State# s -> State# s
1830    with has_side_effects = True
1831         can_fail         = True
1832
1833 primop  WriteOffAddrOp_Word "writeWordOffAddr#" GenPrimOp
1834    Addr# -> Int# -> Word# -> State# s -> State# s
1835    with has_side_effects = True
1836         can_fail         = True
1837
1838 primop  WriteOffAddrOp_Addr "writeAddrOffAddr#" GenPrimOp
1839    Addr# -> Int# -> Addr# -> State# s -> State# s
1840    with has_side_effects = True
1841         can_fail         = True
1842
1843 primop  WriteOffAddrOp_Float "writeFloatOffAddr#" GenPrimOp
1844    Addr# -> Int# -> Float# -> State# s -> State# s
1845    with has_side_effects = True
1846         can_fail         = True
1847
1848 primop  WriteOffAddrOp_Double "writeDoubleOffAddr#" GenPrimOp
1849    Addr# -> Int# -> Double# -> State# s -> State# s
1850    with has_side_effects = True
1851         can_fail         = True
1852
1853 primop  WriteOffAddrOp_StablePtr "writeStablePtrOffAddr#" GenPrimOp
1854    Addr# -> Int# -> StablePtr# a -> State# s -> State# s
1855    with has_side_effects = True
1856         can_fail         = True
1857
1858 primop  WriteOffAddrOp_Int8 "writeInt8OffAddr#" GenPrimOp
1859    Addr# -> Int# -> Int# -> State# s -> State# s
1860    with has_side_effects = True
1861         can_fail         = True
1862
1863 primop  WriteOffAddrOp_Int16 "writeInt16OffAddr#" GenPrimOp
1864    Addr# -> Int# -> Int# -> State# s -> State# s
1865    with has_side_effects = True
1866         can_fail         = True
1867
1868 primop  WriteOffAddrOp_Int32 "writeInt32OffAddr#" GenPrimOp
1869    Addr# -> Int# -> INT32 -> State# s -> State# s
1870    with has_side_effects = True
1871         can_fail         = True
1872
1873 primop  WriteOffAddrOp_Int64 "writeInt64OffAddr#" GenPrimOp
1874    Addr# -> Int# -> INT64 -> State# s -> State# s
1875    with has_side_effects = True
1876         can_fail         = True
1877
1878 primop  WriteOffAddrOp_Word8 "writeWord8OffAddr#" GenPrimOp
1879    Addr# -> Int# -> Word# -> State# s -> State# s
1880    with has_side_effects = True
1881         can_fail         = True
1882
1883 primop  WriteOffAddrOp_Word16 "writeWord16OffAddr#" GenPrimOp
1884    Addr# -> Int# -> Word# -> State# s -> State# s
1885    with has_side_effects = True
1886         can_fail         = True
1887
1888 primop  WriteOffAddrOp_Word32 "writeWord32OffAddr#" GenPrimOp
1889    Addr# -> Int# -> WORD32 -> State# s -> State# s
1890    with has_side_effects = True
1891         can_fail         = True
1892
1893 primop  WriteOffAddrOp_Word64 "writeWord64OffAddr#" GenPrimOp
1894    Addr# -> Int# -> WORD64 -> State# s -> State# s
1895    with has_side_effects = True
1896         can_fail         = True
1897
1898 ------------------------------------------------------------------------
1899 section "Mutable variables"
1900         {Operations on MutVar\#s.}
1901 ------------------------------------------------------------------------
1902
1903 primtype MutVar# s a
1904         {A {\tt MutVar\#} behaves like a single-element mutable array.}
1905
1906 primop  NewMutVarOp "newMutVar#" GenPrimOp
1907    a -> State# s -> (# State# s, MutVar# s a #)
1908    {Create {\tt MutVar\#} with specified initial value in specified state thread.}
1909    with
1910    out_of_line = True
1911    has_side_effects = True
1912
1913 -- Note [Why MutVar# ops can't fail]
1914 -- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1915 --
1916 -- We don't label readMutVar# or writeMutVar# as can_fail.
1917 -- This may seem a bit peculiar, because they surely *could*
1918 -- fail spectacularly if passed a pointer to unallocated memory.
1919 -- But MutVar#s are always correct by construction; we never
1920 -- test if a pointer is valid before using it with these operations.
1921 -- So we never have to worry about floating the pointer reference
1922 -- outside a validity test. At the moment, has_side_effects blocks
1923 -- up the relevant optimizations anyway, but we hope to draw finer
1924 -- distinctions soon, which should improve matters for readMutVar#
1925 -- at least.
1926
1927 primop  ReadMutVarOp "readMutVar#" GenPrimOp
1928    MutVar# s a -> State# s -> (# State# s, a #)
1929    {Read contents of {\tt MutVar\#}. Result is not yet evaluated.}
1930    with
1931    -- See Note [Why MutVar# ops can't fail]
1932    has_side_effects = True
1933
1934 primop  WriteMutVarOp "writeMutVar#"  GenPrimOp
1935    MutVar# s a -> a -> State# s -> State# s
1936    {Write contents of {\tt MutVar\#}.}
1937    with
1938    -- See Note [Why MutVar# ops can't fail]
1939    has_side_effects = True
1940    code_size = { primOpCodeSizeForeignCall } -- for the write barrier
1941
1942 primop  SameMutVarOp "sameMutVar#" GenPrimOp
1943    MutVar# s a -> MutVar# s a -> Int#
1944
1945 -- Note [Why not an unboxed tuple in atomicModifyMutVar#?]
1946 -- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1947 --
1948 -- Looking at the type of atomicModifyMutVar#, one might wonder why
1949 -- it doesn't return an unboxed tuple. e.g.,
1950 --
1951 --   MutVar# s a -> (a -> (# a, b #)) -> State# s -> (# State# s, b #)
1952 --
1953 -- The reason is that atomicModifyMutVar# relies on laziness for its atomicity.
1954 -- Given a MutVar# containing x, atomicModifyMutVar# merely replaces the
1955 -- its contents with a thunk of the form (fst (f x)). This can be done using an
1956 -- atomic compare-and-swap as it is merely replacing a pointer.
1957
1958 primop  AtomicModifyMutVarOp "atomicModifyMutVar#" GenPrimOp
1959    MutVar# s a -> (a -> b) -> State# s -> (# State# s, c #)
1960    { Modify the contents of a {\tt MutVar\#}. Note that this isn't strictly
1961      speaking the correct type for this function, it should really be
1962      {\tt MutVar# s a -> (a -> (a,b)) -> State# s -> (# State# s, b #)}, however
1963      we don't know about pairs here. }
1964    with
1965    out_of_line = True
1966    has_side_effects = True
1967    can_fail         = True
1968
1969 primop  CasMutVarOp "casMutVar#" GenPrimOp
1970   MutVar# s a -> a -> a -> State# s -> (# State# s, Int#, a #)
1971    with
1972    out_of_line = True
1973    has_side_effects = True
1974
1975 ------------------------------------------------------------------------
1976 section "Exceptions"
1977 ------------------------------------------------------------------------
1978
1979 -- Note [Strictness for mask/unmask/catch]
1980 -- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1981 -- Consider this example, which comes from GHC.IO.Handle.Internals:
1982 --    wantReadableHandle3 f ma b st
1983 --      = case ... of
1984 --          DEFAULT -> case ma of MVar a -> ...
1985 --          0#      -> maskAsynchExceptions# (\st -> case ma of MVar a -> ...)
1986 -- The outer case just decides whether to mask exceptions, but we don't want
1987 -- thereby to hide the strictness in 'ma'!  Hence the use of strictApply1Dmd.
1988 --
1989 -- For catch, catchSTM, and catchRetry, we must be extra careful; see
1990 -- Note [Exceptions and strictness] in Demand
1991
1992 primop  CatchOp "catch#" GenPrimOp
1993           (State# RealWorld -> (# State# RealWorld, a #) )
1994        -> (b -> State# RealWorld -> (# State# RealWorld, a #) )
1995        -> State# RealWorld
1996        -> (# State# RealWorld, a #)
1997    with
1998    strictness  = { \ _arity -> mkClosedStrictSig [ lazyApply1Dmd
1999                                                  , lazyApply2Dmd
2000                                                  , topDmd] topRes }
2001                  -- See Note [Strictness for mask/unmask/catch]
2002    out_of_line = True
2003    has_side_effects = True
2004
2005 primop  RaiseOp "raise#" GenPrimOp
2006    b -> o
2007       -- NB: the type variable "o" is "a", but with OpenKind
2008    with
2009    strictness  = { \ _arity -> mkClosedStrictSig [topDmd] exnRes }
2010       -- NB: result is ThrowsExn
2011    out_of_line = True
2012    has_side_effects = True
2013      -- raise# certainly throws a Haskell exception and hence has_side_effects
2014      -- It doesn't actually make much difference because the fact that it
2015      -- returns bottom independently ensures that we are careful not to discard
2016      -- it.  But still, it's better to say the Right Thing.
2017
2018 -- raiseIO# needs to be a primop, because exceptions in the IO monad
2019 -- must be *precise* - we don't want the strictness analyser turning
2020 -- one kind of bottom into another, as it is allowed to do in pure code.
2021 --
2022 -- But we *do* want to know that it returns bottom after
2023 -- being applied to two arguments, so that this function is strict in y
2024 --     f x y | x>0       = raiseIO blah
2025 --           | y>0       = return 1
2026 --           | otherwise = return 2
2027 --
2028 -- TODO Check that the above notes on @f@ are valid. The function successfully
2029 -- produces an IO exception when compiled without optimization. If we analyze
2030 -- it as strict in @y@, won't we change that behavior under optimization?
2031 -- I thought the rule was that it was okay to replace one valid imprecise
2032 -- exception with another, but not to replace a precise exception with
2033 -- an imprecise one (dfeuer, 2017-03-05).
2034
2035 primop  RaiseIOOp "raiseIO#" GenPrimOp
2036    a -> State# RealWorld -> (# State# RealWorld, b #)
2037    with
2038    strictness  = { \ _arity -> mkClosedStrictSig [topDmd, topDmd] exnRes }
2039    out_of_line = True
2040    has_side_effects = True
2041
2042 primop  MaskAsyncExceptionsOp "maskAsyncExceptions#" GenPrimOp
2043         (State# RealWorld -> (# State# RealWorld, a #))
2044      -> (State# RealWorld -> (# State# RealWorld, a #))
2045    with
2046    strictness  = { \ _arity -> mkClosedStrictSig [strictApply1Dmd,topDmd] topRes }
2047                  -- See Note [Strictness for mask/unmask/catch]
2048    out_of_line = True
2049    has_side_effects = True
2050
2051 primop  MaskUninterruptibleOp "maskUninterruptible#" GenPrimOp
2052         (State# RealWorld -> (# State# RealWorld, a #))
2053      -> (State# RealWorld -> (# State# RealWorld, a #))
2054    with
2055    strictness  = { \ _arity -> mkClosedStrictSig [strictApply1Dmd,topDmd] topRes }
2056    out_of_line = True
2057    has_side_effects = True
2058
2059 primop  UnmaskAsyncExceptionsOp "unmaskAsyncExceptions#" GenPrimOp
2060         (State# RealWorld -> (# State# RealWorld, a #))
2061      -> (State# RealWorld -> (# State# RealWorld, a #))
2062    with
2063    strictness  = { \ _arity -> mkClosedStrictSig [strictApply1Dmd,topDmd] topRes }
2064                  -- See Note [Strictness for mask/unmask/catch]
2065    out_of_line = True
2066    has_side_effects = True
2067
2068 primop  MaskStatus "getMaskingState#" GenPrimOp
2069         State# RealWorld -> (# State# RealWorld, Int# #)
2070    with
2071    out_of_line = True
2072    has_side_effects = True
2073
2074 ------------------------------------------------------------------------
2075 section "STM-accessible Mutable Variables"
2076 ------------------------------------------------------------------------
2077
2078 primtype TVar# s a
2079
2080 primop  AtomicallyOp "atomically#" GenPrimOp
2081       (State# RealWorld -> (# State# RealWorld, a #) )
2082    -> State# RealWorld -> (# State# RealWorld, a #)
2083    with
2084    strictness  = { \ _arity -> mkClosedStrictSig [strictApply1Dmd,topDmd] topRes }
2085                  -- See Note [Strictness for mask/unmask/catch]
2086    out_of_line = True
2087    has_side_effects = True
2088
2089 -- NB: retry#'s strictness information specifies it to return bottom.
2090 -- This lets the compiler perform some extra simplifications, since retry#
2091 -- will technically never return.
2092 --
2093 -- This allows the simplifier to replace things like:
2094 --   case retry# s1
2095 --     (# s2, a #) -> e
2096 -- with:
2097 --   retry# s1
2098 -- where 'e' would be unreachable anyway.  See Trac #8091.
2099 primop  RetryOp "retry#" GenPrimOp
2100    State# RealWorld -> (# State# RealWorld, a #)
2101    with
2102    strictness  = { \ _arity -> mkClosedStrictSig [topDmd] botRes }
2103    out_of_line = True
2104    has_side_effects = True
2105
2106 primop  CatchRetryOp "catchRetry#" GenPrimOp
2107       (State# RealWorld -> (# State# RealWorld, a #) )
2108    -> (State# RealWorld -> (# State# RealWorld, a #) )
2109    -> (State# RealWorld -> (# State# RealWorld, a #) )
2110    with
2111    strictness  = { \ _arity -> mkClosedStrictSig [ catchArgDmd
2112                                                  , lazyApply1Dmd
2113                                                  , topDmd ] topRes }
2114                  -- See Note [Strictness for mask/unmask/catch]
2115    out_of_line = True
2116    has_side_effects = True
2117
2118 primop  CatchSTMOp "catchSTM#" GenPrimOp
2119       (State# RealWorld -> (# State# RealWorld, a #) )
2120    -> (b -> State# RealWorld -> (# State# RealWorld, a #) )
2121    -> (State# RealWorld -> (# State# RealWorld, a #) )
2122    with
2123    strictness  = { \ _arity -> mkClosedStrictSig [ lazyApply1Dmd
2124                                                  , lazyApply2Dmd
2125                                                  , topDmd ] topRes }
2126                  -- See Note [Strictness for mask/unmask/catch]
2127    out_of_line = True
2128    has_side_effects = True
2129
2130 primop  Check "check#" GenPrimOp
2131       (State# RealWorld -> (# State# RealWorld, a #) )
2132    -> (State# RealWorld -> State# RealWorld)
2133    with
2134    out_of_line = True
2135    has_side_effects = True
2136
2137 primop  NewTVarOp "newTVar#" GenPrimOp
2138        a
2139     -> State# s -> (# State# s, TVar# s a #)
2140    {Create a new {\tt TVar\#} holding a specified initial value.}
2141    with
2142    out_of_line  = True
2143    has_side_effects = True
2144
2145 primop  ReadTVarOp "readTVar#" GenPrimOp
2146        TVar# s a
2147     -> State# s -> (# State# s, a #)
2148    {Read contents of {\tt TVar\#}.  Result is not yet evaluated.}
2149    with
2150    out_of_line  = True
2151    has_side_effects = True
2152
2153 primop ReadTVarIOOp "readTVarIO#" GenPrimOp
2154        TVar# s a
2155     -> State# s -> (# State# s, a #)
2156    {Read contents of {\tt TVar\#} outside an STM transaction}
2157    with
2158    out_of_line      = True
2159    has_side_effects = True
2160
2161 primop  WriteTVarOp "writeTVar#" GenPrimOp
2162        TVar# s a
2163     -> a
2164     -> State# s -> State# s
2165    {Write contents of {\tt TVar\#}.}
2166    with
2167    out_of_line      = True
2168    has_side_effects = True
2169
2170 primop  SameTVarOp "sameTVar#" GenPrimOp
2171    TVar# s a -> TVar# s a -> Int#
2172
2173
2174 ------------------------------------------------------------------------
2175 section "Synchronized Mutable Variables"
2176         {Operations on {\tt MVar\#}s. }
2177 ------------------------------------------------------------------------
2178
2179 primtype MVar# s a
2180         { A shared mutable variable ({\it not} the same as a {\tt MutVar\#}!).
2181         (Note: in a non-concurrent implementation, {\tt (MVar\# a)} can be
2182         represented by {\tt (MutVar\# (Maybe a))}.) }
2183
2184 primop  NewMVarOp "newMVar#"  GenPrimOp
2185    State# s -> (# State# s, MVar# s a #)
2186    {Create new {\tt MVar\#}; initially empty.}
2187    with
2188    out_of_line = True
2189    has_side_effects = True
2190
2191 primop  TakeMVarOp "takeMVar#" GenPrimOp
2192    MVar# s a -> State# s -> (# State# s, a #)
2193    {If {\tt MVar\#} is empty, block until it becomes full.
2194    Then remove and return its contents, and set it empty.}
2195    with
2196    out_of_line      = True
2197    has_side_effects = True
2198
2199 primop  TryTakeMVarOp "tryTakeMVar#" GenPrimOp
2200    MVar# s a -> State# s -> (# State# s, Int#, a #)
2201    {If {\tt MVar\#} is empty, immediately return with integer 0 and value undefined.
2202    Otherwise, return with integer 1 and contents of {\tt MVar\#}, and set {\tt MVar\#} empty.}
2203    with
2204    out_of_line      = True
2205    has_side_effects = True
2206
2207 primop  PutMVarOp "putMVar#" GenPrimOp
2208    MVar# s a -> a -> State# s -> State# s
2209    {If {\tt MVar\#} is full, block until it becomes empty.
2210    Then store value arg as its new contents.}
2211    with
2212    out_of_line      = True
2213    has_side_effects = True
2214
2215 primop  TryPutMVarOp "tryPutMVar#" GenPrimOp
2216    MVar# s a -> a -> State# s -> (# State# s, Int# #)
2217    {If {\tt MVar\#} is full, immediately return with integer 0.
2218     Otherwise, store value arg as {\tt MVar\#}'s new contents, and return with integer 1.}
2219    with
2220    out_of_line      = True
2221    has_side_effects = True
2222
2223 primop  ReadMVarOp "readMVar#" GenPrimOp
2224    MVar# s a -> State# s -> (# State# s, a #)
2225    {If {\tt MVar\#} is empty, block until it becomes full.
2226    Then read its contents without modifying the MVar, without possibility
2227    of intervention from other threads.}
2228    with
2229    out_of_line      = True
2230    has_side_effects = True
2231
2232 primop  TryReadMVarOp "tryReadMVar#" GenPrimOp
2233    MVar# s a -> State# s -> (# State# s, Int#, a #)
2234    {If {\tt MVar\#} is empty, immediately return with integer 0 and value undefined.
2235    Otherwise, return with integer 1 and contents of {\tt MVar\#}.}
2236    with
2237    out_of_line      = True
2238    has_side_effects = True
2239
2240 primop  SameMVarOp "sameMVar#" GenPrimOp
2241    MVar# s a -> MVar# s a -> Int#
2242
2243 primop  IsEmptyMVarOp "isEmptyMVar#" GenPrimOp
2244    MVar# s a -> State# s -> (# State# s, Int# #)
2245    {Return 1 if {\tt MVar\#} is empty; 0 otherwise.}
2246    with
2247    out_of_line = True
2248    has_side_effects = True
2249
2250 ------------------------------------------------------------------------
2251 section "Delay/wait operations"
2252 ------------------------------------------------------------------------
2253
2254 primop  DelayOp "delay#" GenPrimOp
2255    Int# -> State# s -> State# s
2256    {Sleep specified number of microseconds.}
2257    with
2258    has_side_effects = True
2259    out_of_line      = True
2260
2261 primop  WaitReadOp "waitRead#" GenPrimOp
2262    Int# -> State# s -> State# s
2263    {Block until input is available on specified file descriptor.}
2264    with
2265    has_side_effects = True
2266    out_of_line      = True
2267
2268 primop  WaitWriteOp "waitWrite#" GenPrimOp
2269    Int# -> State# s -> State# s
2270    {Block until output is possible on specified file descriptor.}
2271    with
2272    has_side_effects = True
2273    out_of_line      = True
2274
2275 #ifdef mingw32_TARGET_OS
2276 primop  AsyncReadOp "asyncRead#" GenPrimOp
2277    Int# -> Int# -> Int# -> Addr# -> State# RealWorld-> (# State# RealWorld, Int#, Int# #)
2278    {Asynchronously read bytes from specified file descriptor.}
2279    with
2280    has_side_effects = True
2281    out_of_line      = True
2282
2283 primop  AsyncWriteOp "asyncWrite#" GenPrimOp
2284    Int# -> Int# -> Int# -> Addr# -> State# RealWorld-> (# State# RealWorld, Int#, Int# #)
2285    {Asynchronously write bytes from specified file descriptor.}
2286    with
2287    has_side_effects = True
2288    out_of_line      = True
2289
2290 primop  AsyncDoProcOp "asyncDoProc#" GenPrimOp
2291    Addr# -> Addr# -> State# RealWorld-> (# State# RealWorld, Int#, Int# #)
2292    {Asynchronously perform procedure (first arg), passing it 2nd arg.}
2293    with
2294    has_side_effects = True
2295    out_of_line      = True
2296
2297 #endif
2298
2299 ------------------------------------------------------------------------
2300 section "Concurrency primitives"
2301 ------------------------------------------------------------------------
2302
2303 primtype State# s
2304         { {\tt State\#} is the primitive, unlifted type of states.  It has
2305         one type parameter, thus {\tt State\# RealWorld}, or {\tt State\# s},
2306         where s is a type variable. The only purpose of the type parameter
2307         is to keep different state threads separate.  It is represented by
2308         nothing at all. }
2309
2310 primtype RealWorld
2311         { {\tt RealWorld} is deeply magical.  It is {\it primitive}, but it is not
2312         {\it unlifted} (hence {\tt ptrArg}).  We never manipulate values of type
2313         {\tt RealWorld}; it's only used in the type system, to parameterise {\tt State\#}. }
2314
2315 primtype ThreadId#
2316         {(In a non-concurrent implementation, this can be a singleton
2317         type, whose (unique) value is returned by {\tt myThreadId\#}.  The
2318         other operations can be omitted.)}
2319
2320 primop  ForkOp "fork#" GenPrimOp
2321    a -> State# RealWorld -> (# State# RealWorld, ThreadId# #)
2322    with
2323    has_side_effects = True
2324    out_of_line      = True
2325
2326 primop  ForkOnOp "forkOn#" GenPrimOp
2327    Int# -> a -> State# RealWorld -> (# State# RealWorld, ThreadId# #)
2328    with
2329    has_side_effects = True
2330    out_of_line      = True
2331
2332 primop  KillThreadOp "killThread#"  GenPrimOp
2333    ThreadId# -> a -> State# RealWorld -> State# RealWorld
2334    with
2335    has_side_effects = True
2336    out_of_line      = True
2337
2338 primop  YieldOp "yield#" GenPrimOp
2339    State# RealWorld -> State# RealWorld
2340    with
2341    has_side_effects = True
2342    out_of_line      = True
2343
2344 primop  MyThreadIdOp "myThreadId#" GenPrimOp
2345    State# RealWorld -> (# State# RealWorld, ThreadId# #)
2346    with
2347    out_of_line = True
2348    has_side_effects = True
2349
2350 primop LabelThreadOp "labelThread#" GenPrimOp
2351    ThreadId# -> Addr# -> State# RealWorld -> State# RealWorld
2352    with
2353    has_side_effects = True
2354    out_of_line      = True
2355
2356 primop  IsCurrentThreadBoundOp "isCurrentThreadBound#" GenPrimOp
2357    State# RealWorld -> (# State# RealWorld, Int# #)
2358    with
2359    out_of_line = True
2360    has_side_effects = True
2361
2362 primop  NoDuplicateOp "noDuplicate#" GenPrimOp
2363    State# s -> State# s
2364    with
2365    out_of_line = True
2366    has_side_effects = True
2367
2368 primop  ThreadStatusOp "threadStatus#" GenPrimOp
2369    ThreadId# -> State# RealWorld -> (# State# RealWorld, Int#, Int#, Int# #)
2370    with
2371    out_of_line = True
2372    has_side_effects = True
2373
2374 ------------------------------------------------------------------------
2375 section "Weak pointers"
2376 ------------------------------------------------------------------------
2377
2378 primtype Weak# b
2379
2380 -- note that tyvar "o" denotes openAlphaTyVar
2381
2382 primop  MkWeakOp "mkWeak#" GenPrimOp
2383    o -> b -> (State# RealWorld -> (# State# RealWorld, c #))
2384      -> State# RealWorld -> (# State# RealWorld, Weak# b #)
2385    with
2386    has_side_effects = True
2387    out_of_line      = True
2388
2389 primop  MkWeakNoFinalizerOp "mkWeakNoFinalizer#" GenPrimOp
2390    o -> b -> State# RealWorld -> (# State# RealWorld, Weak# b #)
2391    with
2392    has_side_effects = True
2393    out_of_line      = True
2394
2395 primop  AddCFinalizerToWeakOp "addCFinalizerToWeak#" GenPrimOp
2396    Addr# -> Addr# -> Int# -> Addr# -> Weak# b
2397           -> State# RealWorld -> (# State# RealWorld, Int# #)
2398    { {\tt addCFinalizerToWeak# fptr ptr flag eptr w} attaches a C
2399      function pointer {\tt fptr} to a weak pointer {\tt w} as a finalizer. If
2400      {\tt flag} is zero, {\tt fptr} will be called with one argument,
2401      {\tt ptr}. Otherwise, it will be called with two arguments,
2402      {\tt eptr} and {\tt ptr}. {\tt addCFinalizerToWeak#} returns
2403      1 on success, or 0 if {\tt w} is already dead. }
2404    with
2405    has_side_effects = True
2406    out_of_line      = True
2407
2408 primop  DeRefWeakOp "deRefWeak#" GenPrimOp
2409    Weak# a -> State# RealWorld -> (# State# RealWorld, Int#, a #)
2410    with
2411    has_side_effects = True
2412    out_of_line      = True
2413
2414 primop  FinalizeWeakOp "finalizeWeak#" GenPrimOp
2415    Weak# a -> State# RealWorld -> (# State# RealWorld, Int#,
2416               (State# RealWorld -> (# State# RealWorld, b #) ) #)
2417    { Finalize a weak pointer. The return value is an unboxed tuple
2418      containing the new state of the world and an "unboxed Maybe",
2419      represented by an {\tt Int#} and a (possibly invalid) finalization
2420      action. An {\tt Int#} of {\tt 1} indicates that the finalizer is valid. The
2421      return value {\tt b} from the finalizer should be ignored. }
2422    with
2423    has_side_effects = True
2424    out_of_line      = True
2425
2426 primop TouchOp "touch#" GenPrimOp
2427    o -> State# RealWorld -> State# RealWorld
2428    with
2429    code_size = { 0 }
2430    has_side_effects = True
2431
2432 ------------------------------------------------------------------------
2433 section "Stable pointers and names"
2434 ------------------------------------------------------------------------
2435
2436 primtype StablePtr# a
2437
2438 primtype StableName# a
2439
2440 primop  MakeStablePtrOp "makeStablePtr#" GenPrimOp
2441    a -> State# RealWorld -> (# State# RealWorld, StablePtr# a #)
2442    with
2443    has_side_effects = True
2444    out_of_line      = True
2445
2446 primop  DeRefStablePtrOp "deRefStablePtr#" GenPrimOp
2447    StablePtr# a -> State# RealWorld -> (# State# RealWorld, a #)
2448    with
2449    has_side_effects = True
2450    out_of_line      = True
2451
2452 primop  EqStablePtrOp "eqStablePtr#" GenPrimOp
2453    StablePtr# a -> StablePtr# a -> Int#
2454    with
2455    has_side_effects = True
2456
2457 primop  MakeStableNameOp "makeStableName#" GenPrimOp
2458    a -> State# RealWorld -> (# State# RealWorld, StableName# a #)
2459    with
2460    has_side_effects = True
2461    out_of_line      = True
2462
2463 primop  EqStableNameOp "eqStableName#" GenPrimOp
2464    StableName# a -> StableName# b -> Int#
2465
2466 primop  StableNameToIntOp "stableNameToInt#" GenPrimOp
2467    StableName# a -> Int#
2468
2469 ------------------------------------------------------------------------
2470 section "Compact normal form"
2471 ------------------------------------------------------------------------
2472
2473 primtype Compact#
2474
2475 primop  CompactNewOp "compactNew#" GenPrimOp
2476    Word# -> State# RealWorld -> (# State# RealWorld, Compact# #)
2477    { Create a new Compact with the given size (in bytes, not words).
2478      The size is rounded up to a multiple of the allocator block size,
2479      and capped to one mega block. }
2480    with
2481    has_side_effects = True
2482    out_of_line      = True
2483
2484 primop  CompactResizeOp "compactResize#" GenPrimOp
2485    Compact# -> Word# -> State# RealWorld ->
2486    State# RealWorld
2487    { Set the new allocation size of the compact. This value (in bytes)
2488      determines the size of each block in the compact chain. }
2489    with
2490    has_side_effects = True
2491    out_of_line      = True
2492
2493 primop  CompactContainsOp "compactContains#" GenPrimOp
2494    Compact# -> a -> State# RealWorld -> (# State# RealWorld, Int# #)
2495    { Returns 1# if the object is contained in the compact, 0# otherwise. }
2496    with
2497    out_of_line      = True
2498
2499 primop  CompactContainsAnyOp "compactContainsAny#" GenPrimOp
2500    a -> State# RealWorld -> (# State# RealWorld, Int# #)
2501    { Returns 1# if the object is in any compact at all, 0# otherwise. }
2502    with
2503    out_of_line      = True
2504
2505 primop  CompactGetFirstBlockOp "compactGetFirstBlock#" GenPrimOp
2506    Compact# -> State# RealWorld -> (# State# RealWorld, Addr#, Word# #)
2507    { Returns the address and the size (in bytes) of the first block of
2508      a compact. }
2509    with
2510    out_of_line      = True
2511
2512 primop  CompactGetNextBlockOp "compactGetNextBlock#" GenPrimOp
2513    Compact# -> Addr# -> State# RealWorld -> (# State# RealWorld, Addr#, Word# #)
2514    { Given a compact and the address of one its blocks, returns the
2515      next block and its size, or #nullAddr if the argument was the
2516      last block in the compact. }
2517    with
2518    out_of_line      = True
2519
2520 primop  CompactAllocateBlockOp "compactAllocateBlock#" GenPrimOp
2521    Word# -> Addr# -> State# RealWorld -> (# State# RealWorld, Addr# #)
2522    { Attempt to allocate a compact block with the given size (in
2523      bytes) at the given address. The first argument is a hint to
2524      the allocator, allocation might be satisfied at a different
2525      address (which is returned).
2526      The resulting block is not known to the GC until
2527      compactFixupPointers# is called on it, and care must be taken
2528      so that the address does not escape or memory will be leaked.
2529    }
2530    with
2531    has_side_effects = True
2532    out_of_line      = True
2533
2534 primop  CompactFixupPointersOp "compactFixupPointers#" GenPrimOp
2535    Addr# -> Addr# -> State# RealWorld -> (# State# RealWorld, Compact#, Addr# #)
2536    { Given the pointer to the first block of a compact, and the
2537      address of the root object in the old address space, fix up
2538      the internal pointers inside the compact to account for
2539      a different position in memory than when it was serialized.
2540      This method must be called exactly once after importing
2541      a serialized compact, and returns the new compact and
2542      the new adjusted root address. }
2543    with
2544    has_side_effects = True
2545    out_of_line      = True
2546
2547 primop CompactAdd "compactAdd#" GenPrimOp
2548    Compact# -> a -> State# RealWorld -> (# State# RealWorld, a #)
2549    { Recursively add a closure and its transitive closure to a
2550      {\texttt Compact\#}, evaluating any unevaluated components at the
2551      same time.  Note: {\texttt compactAdd\#} is not thread-safe, so
2552      only one thread may call {\texttt compactAdd\#} with a particular
2553      {\texttt Compact#} at any given time.  The primop does not
2554      enforce any mutual exclusion; the caller is expected to
2555      arrange this. }
2556    with
2557    has_side_effects = True
2558    out_of_line      = True
2559
2560 primop CompactAddWithSharing "compactAddWithSharing#" GenPrimOp
2561    Compact# -> a -> State# RealWorld -> (# State# RealWorld, a #)
2562    { Like {\texttt compactAdd\#}, but retains sharing and cycles
2563    during compaction. }
2564    with
2565    has_side_effects = True
2566    out_of_line      = True
2567
2568 primop CompactSize "compactSize#" GenPrimOp
2569    Compact# -> State# RealWorld -> (# State# RealWorld, Word# #)
2570    { Return the size (in bytes) of the total amount of data in the Compact# }
2571    with
2572    has_side_effects = True
2573    out_of_line      = True
2574
2575 ------------------------------------------------------------------------
2576 section "Unsafe pointer equality"
2577 --  (#1 Bad Guy: Alastair Reid :)
2578 ------------------------------------------------------------------------
2579
2580 primop  ReallyUnsafePtrEqualityOp "reallyUnsafePtrEquality#" GenPrimOp
2581    a -> a -> Int#
2582    { Returns 1# if the given pointers are equal and 0# otherwise. }
2583    with
2584    can_fail   = True -- See Note [reallyUnsafePtrEquality#]
2585
2586
2587 -- Note [reallyUnsafePtrEquality#]
2588 -- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2589 -- 
2590 -- reallyUnsafePtrEquality# can't actually fail, per se, but we mark it can_fail
2591 -- anyway. Until 5a9a1738023a, GHC considered primops okay for speculation only
2592 -- when their arguments were known to be forced. This was unnecessarily
2593 -- conservative, but it prevented reallyUnsafePtrEquality# from floating out of
2594 -- places where its arguments were known to be forced. Unfortunately, GHC could
2595 -- sometimes lose track of whether those arguments were forced, leading to let/app
2596 -- invariant failures (see Trac 13027 and the discussion in Trac 11444). Now that
2597 -- ok_for_speculation skips over lifted arguments, we need to explicitly prevent
2598 -- reallyUnsafePtrEquality# from floating out. The reasons are closely related
2599 -- to those described in Note [dataToTag#], although the consequences are less
2600 -- severe. Imagine if we had
2601 -- 
2602 --     \x y . case x of x'
2603 --              DEFAULT ->
2604 --            case y of y'
2605 --              DEFAULT ->
2606 --               let eq = reallyUnsafePtrEquality# x' y'
2607 --               in ...
2608 -- 
2609 -- If the let floats out, we'll get
2610 -- 
2611 --     \x y . let eq = reallyUnsafePtrEquality# x y
2612 --            in case x of ...
2613 -- 
2614 -- The trouble is that pointer equality between thunks is very different
2615 -- from pointer equality between the values those thunks reduce to, and the latter
2616 -- is typically much more precise.
2617
2618 ------------------------------------------------------------------------
2619 section "Parallelism"
2620 ------------------------------------------------------------------------
2621
2622 primop  ParOp "par#" GenPrimOp
2623    a -> Int#
2624    with
2625       -- Note that Par is lazy to avoid that the sparked thing
2626       -- gets evaluated strictly, which it should *not* be
2627    has_side_effects = True
2628    code_size = { primOpCodeSizeForeignCall }
2629
2630 primop SparkOp "spark#" GenPrimOp
2631    a -> State# s -> (# State# s, a #)
2632    with has_side_effects = True
2633    code_size = { primOpCodeSizeForeignCall }
2634
2635 primop SeqOp "seq#" GenPrimOp
2636    a -> State# s -> (# State# s, a #)
2637
2638    -- why return the value?  So that we can control sharing of seq'd
2639    -- values: in
2640    --    let x = e in x `seq` ... x ...
2641    -- we don't want to inline x, so better to represent it as
2642    --    let x = e in case seq# x RW of (# _, x' #) -> ... x' ...
2643    -- also it matches the type of rseq in the Eval monad.
2644
2645 primop GetSparkOp "getSpark#" GenPrimOp
2646    State# s -> (# State# s, Int#, a #)
2647    with
2648    has_side_effects = True
2649    out_of_line = True
2650
2651 primop NumSparks "numSparks#" GenPrimOp
2652    State# s -> (# State# s, Int# #)
2653    { Returns the number of sparks in the local spark pool. }
2654    with
2655    has_side_effects = True
2656    out_of_line = True
2657
2658 ------------------------------------------------------------------------
2659 section "Tag to enum stuff"
2660         {Convert back and forth between values of enumerated types
2661         and small integers.}
2662 ------------------------------------------------------------------------
2663
2664 primop  DataToTagOp "dataToTag#" GenPrimOp
2665    a -> Int#
2666    with
2667    can_fail   = True -- See Note [dataToTag#]
2668    strictness = { \ _arity -> mkClosedStrictSig [evalDmd] topRes }
2669                 -- dataToTag# must have an evaluated argument
2670
2671 primop  TagToEnumOp "tagToEnum#" GenPrimOp
2672    Int# -> a
2673
2674 {- Note [dataToTag#]
2675 ~~~~~~~~~~~~~~~~~~~~
2676 The dataToTag# primop should always be applied to an evaluated argument.
2677 The way to ensure this is to invoke it via the 'getTag' wrapper in GHC.Base:
2678    getTag :: a -> Int#
2679    getTag !x = dataToTag# x
2680
2681 But now consider
2682     \z. case x of y -> let v = dataToTag# y in ...
2683
2684 To improve floating, the FloatOut pass (deliberately) does a
2685 binder-swap on the case, to give
2686     \z. case x of y -> let v = dataToTag# x in ...
2687
2688 Now FloatOut might float that v-binding outside the \z.  But that is
2689 bad because that might mean x gest evaluated much too early!  (CorePrep
2690 adds an eval to a dataToTag# call, to ensure that the argument really is
2691 evaluated; see CorePrep Note [dataToTag magic].)
2692
2693 Solution: make DataToTag into a can_fail primop.  That will stop it floating
2694 (see Note [PrimOp can_fail and has_side_effects] in PrimOp).  It's a bit of
2695 a hack but never mind.
2696 -}
2697
2698 ------------------------------------------------------------------------
2699 section "Bytecode operations"
2700         {Support for manipulating bytecode objects used by the interpreter and
2701         linker.
2702
2703         Bytecode objects are heap objects which represent top-level bindings and
2704         contain a list of instructions and data needed by these instructions.}
2705 ------------------------------------------------------------------------
2706
2707 primtype BCO#
2708    { Primitive bytecode type. }
2709
2710 primop   AddrToAnyOp "addrToAny#" GenPrimOp
2711    Addr# -> (# a #)
2712    { Convert an {\tt Addr\#} to a followable Any type. }
2713    with
2714    code_size = 0
2715
2716 primop   AnyToAddrOp "anyToAddr#" GenPrimOp
2717    a -> State# RealWorld -> (# State# RealWorld, Addr# #)
2718    { Retrieve the address of any Haskell value. This is
2719      essentially an {\texttt unsafeCoerce\#}, but if implemented as such
2720      the core lint pass complains and fails to compile.
2721      As a primop, it is opaque to core/stg, and only appears
2722      in cmm (where the copy propagation pass will get rid of it).
2723      Note that "a" must be a value, not a thunk! It's too late
2724      for strictness analysis to enforce this, so you're on your
2725      own to guarantee this. Also note that {\texttt Addr\#} is not a GC
2726      pointer - up to you to guarantee that it does not become
2727      a dangling pointer immediately after you get it.}
2728    with
2729    code_size = 0
2730
2731 primop   MkApUpd0_Op "mkApUpd0#" GenPrimOp
2732    BCO# -> (# a #)
2733    { Wrap a BCO in a {\tt AP_UPD} thunk which will be updated with the value of
2734      the BCO when evaluated. }
2735    with
2736    out_of_line = True
2737
2738 primop  NewBCOOp "newBCO#" GenPrimOp
2739    ByteArray# -> ByteArray# -> Array# a -> Int# -> ByteArray# -> State# s -> (# State# s, BCO# #)
2740    { {\tt newBCO\# instrs lits ptrs arity bitmap} creates a new bytecode object. The
2741      resulting object encodes a function of the given arity with the instructions
2742      encoded in {\tt instrs}, and a static reference table usage bitmap given by
2743      {\tt bitmap}. }
2744    with
2745    has_side_effects = True
2746    out_of_line      = True
2747
2748 primop  UnpackClosureOp "unpackClosure#" GenPrimOp
2749    a -> (# Addr#, Array# b, ByteArray# #)
2750    { {\tt unpackClosure\# closure} copies non-pointers and pointers in the
2751      payload of the given closure into two new arrays, and returns a pointer to
2752      the first word of the closure's info table, a pointer array for the
2753      pointers in the payload, and a non-pointer array for the non-pointers in
2754      the payload. }
2755    with
2756    out_of_line = True
2757
2758 primop  GetApStackValOp "getApStackVal#" GenPrimOp
2759    a -> Int# -> (# Int#, b #)
2760    with
2761    out_of_line = True
2762
2763 ------------------------------------------------------------------------
2764 section "Misc"
2765         {These aren't nearly as wired in as Etc...}
2766 ------------------------------------------------------------------------
2767
2768 primop  GetCCSOfOp "getCCSOf#" GenPrimOp
2769    a -> State# s -> (# State# s, Addr# #)
2770
2771 primop  GetCurrentCCSOp "getCurrentCCS#" GenPrimOp
2772    a -> State# s -> (# State# s, Addr# #)
2773    { Returns the current {\tt CostCentreStack} (value is {\tt NULL} if
2774      not profiling).  Takes a dummy argument which can be used to
2775      avoid the call to {\tt getCCCS\#} being floated out by the
2776      simplifier, which would result in an uninformative stack
2777      ("CAF"). }
2778
2779 primop  ClearCCSOp "clearCCS#" GenPrimOp
2780    (State# s -> (# State# s, a #)) -> State# s -> (# State# s, a #)
2781    { Run the supplied IO action with an empty CCS.  For example, this
2782      is used by the interpreter to run an interpreted computation
2783      without the call stack showing that it was invoked from GHC. }
2784    with
2785    out_of_line = True
2786
2787 ------------------------------------------------------------------------
2788 section "Etc"
2789         {Miscellaneous built-ins}
2790 ------------------------------------------------------------------------
2791
2792 primtype Proxy# a
2793    { The type constructor {\tt Proxy#} is used to bear witness to some
2794    type variable. It's used when you want to pass around proxy values
2795    for doing things like modelling type applications. A {\tt Proxy#}
2796    is not only unboxed, it also has a polymorphic kind, and has no
2797    runtime representation, being totally free. }
2798
2799 pseudoop "proxy#"
2800    Proxy# a
2801    { Witness for an unboxed {\tt Proxy#} value, which has no runtime
2802    representation. }
2803
2804 pseudoop   "seq"
2805    a -> b -> b
2806    { The value of {\tt seq a b} is bottom if {\tt a} is bottom, and
2807      otherwise equal to {\tt b}. {\tt seq} is usually introduced to
2808      improve performance by avoiding unneeded laziness.
2809
2810      A note on evaluation order: the expression {\tt seq a b} does
2811      {\it not} guarantee that {\tt a} will be evaluated before {\tt b}.
2812      The only guarantee given by {\tt seq} is that the both {\tt a}
2813      and {\tt b} will be evaluated before {\tt seq} returns a value.
2814      In particular, this means that {\tt b} may be evaluated before
2815      {\tt a}. If you need to guarantee a specific order of evaluation,
2816      you must use the function {\tt pseq} from the "parallel" package. }
2817
2818 pseudoop   "unsafeCoerce#"
2819    a -> b
2820    { The function {\tt unsafeCoerce\#} allows you to side-step the typechecker entirely. That
2821         is, it allows you to coerce any type into any other type. If you use this function,
2822         you had better get it right, otherwise segmentation faults await. It is generally
2823         used when you want to write a program that you know is well-typed, but where Haskell's
2824         type system is not expressive enough to prove that it is well typed.
2825
2826         The following uses of {\tt unsafeCoerce\#} are supposed to work (i.e. not lead to
2827         spurious compile-time or run-time crashes):
2828
2829          * Casting any lifted type to {\tt Any}
2830
2831          * Casting {\tt Any} back to the real type
2832
2833          * Casting an unboxed type to another unboxed type of the same size.
2834            (Casting between floating-point and integral types does not work.
2835            See the {\tt GHC.Float} module for functions to do work.)
2836
2837          * Casting between two types that have the same runtime representation.  One case is when
2838            the two types differ only in "phantom" type parameters, for example
2839            {\tt Ptr Int} to {\tt Ptr Float}, or {\tt [Int]} to {\tt [Float]} when the list is
2840            known to be empty.  Also, a {\tt newtype} of a type {\tt T} has the same representation
2841            at runtime as {\tt T}.
2842
2843         Other uses of {\tt unsafeCoerce\#} are undefined.  In particular, you should not use
2844         {\tt unsafeCoerce\#} to cast a T to an algebraic data type D, unless T is also
2845         an algebraic data type.  For example, do not cast {\tt Int->Int} to {\tt Bool}, even if
2846         you later cast that {\tt Bool} back to {\tt Int->Int} before applying it.  The reasons
2847         have to do with GHC's internal representation details (for the congnoscenti, data values
2848         can be entered but function closures cannot).  If you want a safe type to cast things
2849         to, use {\tt Any}, which is not an algebraic data type.
2850
2851         }
2852
2853 -- NB. It is tempting to think that casting a value to a type that it doesn't have is safe
2854 -- as long as you don't "do anything" with the value in its cast form, such as seq on it.  This
2855 -- isn't the case: the compiler can insert seqs itself, and if these happen at the wrong type,
2856 -- Bad Things Might Happen.  See bug #1616: in this case we cast a function of type (a,b) -> (a,b)
2857 -- to () -> () and back again.  The strictness analyser saw that the function was strict, but
2858 -- the wrapper had type () -> (), and hence the wrapper de-constructed the (), the worker re-constructed
2859 -- a new (), with the result that the code ended up with "case () of (a,b) -> ...".
2860
2861 primop  TraceEventOp "traceEvent#" GenPrimOp
2862    Addr# -> State# s -> State# s
2863    { Emits an event via the RTS tracing framework.  The contents
2864      of the event is the zero-terminated byte string passed as the first
2865      argument.  The event will be emitted either to the .eventlog file,
2866      or to stderr, depending on the runtime RTS flags. }
2867    with
2868    has_side_effects = True
2869    out_of_line      = True
2870
2871 primop  TraceMarkerOp "traceMarker#" GenPrimOp
2872    Addr# -> State# s -> State# s
2873    { Emits a marker event via the RTS tracing framework.  The contents
2874      of the event is the zero-terminated byte string passed as the first
2875      argument.  The event will be emitted either to the .eventlog file,
2876      or to stderr, depending on the runtime RTS flags. }
2877    with
2878    has_side_effects = True
2879    out_of_line      = True
2880
2881 ------------------------------------------------------------------------
2882 section "Safe coercions"
2883 ------------------------------------------------------------------------
2884
2885 pseudoop   "coerce"
2886    Coercible a b => a -> b
2887    { The function {\tt coerce} allows you to safely convert between values of
2888      types that have the same representation with no run-time overhead. In the
2889      simplest case you can use it instead of a newtype constructor, to go from
2890      the newtype's concrete type to the abstract type. But it also works in
2891      more complicated settings, e.g. converting a list of newtypes to a list of
2892      concrete types.
2893    }
2894
2895 ------------------------------------------------------------------------
2896 section "SIMD Vectors"
2897         {Operations on SIMD vectors.}
2898 ------------------------------------------------------------------------
2899
2900 #define ALL_VECTOR_TYPES \
2901   [<Int8,Int#,16>,<Int16,Int#,8>,<Int32,INT32,4>,<Int64,INT64,2> \
2902   ,<Int8,Int#,32>,<Int16,Int#,16>,<Int32,INT32,8>,<Int64,INT64,4> \
2903   ,<Int8,Int#,64>,<Int16,Int#,32>,<Int32,INT32,16>,<Int64,INT64,8> \
2904   ,<Word8,Word#,16>,<Word16,Word#,8>,<Word32,WORD32,4>,<Word64,WORD64,2> \
2905   ,<Word8,Word#,32>,<Word16,Word#,16>,<Word32,WORD32,8>,<Word64,WORD64,4> \
2906   ,<Word8,Word#,64>,<Word16,Word#,32>,<Word32,WORD32,16>,<Word64,WORD64,8> \
2907   ,<Float,Float#,4>,<Double,Double#,2> \
2908   ,<Float,Float#,8>,<Double,Double#,4> \
2909   ,<Float,Float#,16>,<Double,Double#,8>]
2910
2911 #define SIGNED_VECTOR_TYPES \
2912   [<Int8,Int#,16>,<Int16,Int#,8>,<Int32,INT32,4>,<Int64,INT64,2> \
2913   ,<Int8,Int#,32>,<Int16,Int#,16>,<Int32,INT32,8>,<Int64,INT64,4> \
2914   ,<Int8,Int#,64>,<Int16,Int#,32>,<Int32,INT32,16>,<Int64,INT64,8> \
2915   ,<Float,Float#,4>,<Double,Double#,2> \
2916   ,<Float,Float#,8>,<Double,Double#,4> \
2917   ,<Float,Float#,16>,<Double,Double#,8>]
2918
2919 #define FLOAT_VECTOR_TYPES \
2920   [<Float,Float#,4>,<Double,Double#,2> \
2921   ,<Float,Float#,8>,<Double,Double#,4> \
2922   ,<Float,Float#,16>,<Double,Double#,8>]
2923
2924 #define INT_VECTOR_TYPES \
2925   [<Int8,Int#,16>,<Int16,Int#,8>,<Int32,INT32,4>,<Int64,INT64,2> \
2926   ,<Int8,Int#,32>,<Int16,Int#,16>,<Int32,INT32,8>,<Int64,INT64,4> \
2927   ,<Int8,Int#,64>,<Int16,Int#,32>,<Int32,INT32,16>,<Int64,INT64,8> \
2928   ,<Word8,Word#,16>,<Word16,Word#,8>,<Word32,WORD32,4>,<Word64,WORD64,2> \
2929   ,<Word8,Word#,32>,<Word16,Word#,16>,<Word32,WORD32,8>,<Word64,WORD64,4> \
2930   ,<Word8,Word#,64>,<Word16,Word#,32>,<Word32,WORD32,16>,<Word64,WORD64,8>]
2931
2932 primtype VECTOR
2933    with llvm_only = True
2934         vector = ALL_VECTOR_TYPES
2935
2936 primop VecBroadcastOp "broadcast#" GenPrimOp
2937    SCALAR -> VECTOR
2938    { Broadcast a scalar to all elements of a vector. }
2939    with llvm_only = True
2940         vector = ALL_VECTOR_TYPES
2941
2942 primop VecPackOp "pack#" GenPrimOp
2943    VECTUPLE -> VECTOR
2944    { Pack the elements of an unboxed tuple into a vector. }
2945    with llvm_only = True
2946         vector = ALL_VECTOR_TYPES
2947
2948 primop VecUnpackOp "unpack#" GenPrimOp
2949    VECTOR -> VECTUPLE
2950    { Unpack the elements of a vector into an unboxed tuple. #}
2951    with llvm_only = True
2952         vector = ALL_VECTOR_TYPES
2953
2954 primop VecInsertOp "insert#" GenPrimOp
2955    VECTOR -> SCALAR -> Int# -> VECTOR
2956    { Insert a scalar at the given position in a vector. }
2957    with can_fail = True
2958         llvm_only = True
2959         vector = ALL_VECTOR_TYPES
2960
2961 primop VecAddOp "plus#" Dyadic
2962    VECTOR -> VECTOR -> VECTOR
2963    { Add two vectors element-wise. }
2964    with commutable = True
2965         llvm_only = True
2966         vector = ALL_VECTOR_TYPES
2967
2968 primop VecSubOp "minus#" Dyadic
2969    VECTOR -> VECTOR -> VECTOR
2970    { Subtract two vectors element-wise. }
2971    with llvm_only = True
2972         vector = ALL_VECTOR_TYPES
2973
2974 primop VecMulOp "times#" Dyadic
2975    VECTOR -> VECTOR -> VECTOR
2976    { Multiply two vectors element-wise. }
2977    with commutable = True
2978         llvm_only = True
2979         vector = ALL_VECTOR_TYPES
2980
2981 primop VecDivOp "divide#" Dyadic
2982    VECTOR -> VECTOR -> VECTOR
2983    { Divide two vectors element-wise. }
2984    with can_fail = True
2985         llvm_only = True
2986         vector = FLOAT_VECTOR_TYPES
2987
2988 primop VecQuotOp "quot#" Dyadic
2989    VECTOR -> VECTOR -> VECTOR
2990    { Rounds towards zero element-wise. }
2991    with can_fail = True
2992         llvm_only = True
2993         vector = INT_VECTOR_TYPES
2994
2995 primop VecRemOp "rem#" Dyadic
2996    VECTOR -> VECTOR -> VECTOR
2997    { Satisfies \texttt{(quot\# x y) times\# y plus\# (rem\# x y) == x}. }
2998    with can_fail = True
2999         llvm_only = True
3000         vector = INT_VECTOR_TYPES
3001
3002 primop VecNegOp "negate#" Monadic
3003    VECTOR -> VECTOR
3004    { Negate element-wise. }
3005    with llvm_only = True
3006         vector = SIGNED_VECTOR_TYPES
3007
3008 primop VecIndexByteArrayOp "indexArray#" GenPrimOp
3009    ByteArray# -> Int# -> VECTOR
3010    { Read a vector from specified index of immutable array. }
3011    with can_fail = True
3012         llvm_only = True
3013         vector = ALL_VECTOR_TYPES
3014
3015 primop VecReadByteArrayOp "readArray#" GenPrimOp
3016    MutableByteArray# s -> Int# -> State# s -> (# State# s, VECTOR #)
3017    { Read a vector from specified index of mutable array. }
3018    with has_side_effects = True
3019         can_fail = True
3020         llvm_only = True
3021         vector = ALL_VECTOR_TYPES
3022
3023 primop VecWriteByteArrayOp "writeArray#" GenPrimOp
3024    MutableByteArray# s -> Int# -> VECTOR -> State# s -> State# s
3025    { Write a vector to specified index of mutable array. }
3026    with has_side_effects = True
3027         can_fail = True
3028         llvm_only = True
3029         vector = ALL_VECTOR_TYPES
3030
3031 primop VecIndexOffAddrOp "indexOffAddr#" GenPrimOp
3032    Addr# -> Int# -> VECTOR
3033    { Reads vector; offset in bytes. }
3034    with can_fail = True
3035         llvm_only = True
3036         vector = ALL_VECTOR_TYPES
3037
3038 primop VecReadOffAddrOp "readOffAddr#" GenPrimOp
3039    Addr# -> Int# -> State# s -> (# State# s, VECTOR #)
3040    { Reads vector; offset in bytes. }
3041    with has_side_effects = True
3042         can_fail = True
3043         llvm_only = True
3044         vector = ALL_VECTOR_TYPES
3045
3046 primop VecWriteOffAddrOp "writeOffAddr#" GenPrimOp
3047    Addr# -> Int# -> VECTOR -> State# s -> State# s
3048    { Write vector; offset in bytes. }
3049    with has_side_effects = True
3050         can_fail = True
3051         llvm_only = True
3052         vector = ALL_VECTOR_TYPES
3053
3054
3055 primop VecIndexScalarByteArrayOp "indexArrayAs#" GenPrimOp
3056    ByteArray# -> Int# -> VECTOR
3057    { Read a vector from specified index of immutable array of scalars; offset is in scalar elements. }
3058    with can_fail = True
3059         llvm_only = True
3060         vector = ALL_VECTOR_TYPES
3061
3062 primop VecReadScalarByteArrayOp "readArrayAs#" GenPrimOp
3063    MutableByteArray# s -> Int# -> State# s -> (# State# s, VECTOR #)
3064    { Read a vector from specified index of mutable array of scalars; offset is in scalar elements. }
3065    with has_side_effects = True
3066         can_fail = True
3067         llvm_only = True
3068         vector = ALL_VECTOR_TYPES
3069
3070 primop VecWriteScalarByteArrayOp "writeArrayAs#" GenPrimOp
3071    MutableByteArray# s -> Int# -> VECTOR -> State# s -> State# s
3072    { Write a vector to specified index of mutable array of scalars; offset is in scalar elements. }
3073    with has_side_effects = True
3074         can_fail = True
3075         llvm_only = True
3076         vector = ALL_VECTOR_TYPES
3077
3078 primop VecIndexScalarOffAddrOp "indexOffAddrAs#" GenPrimOp
3079    Addr# -> Int# -> VECTOR
3080    { Reads vector; offset in scalar elements. }
3081    with can_fail = True
3082         llvm_only = True
3083         vector = ALL_VECTOR_TYPES
3084
3085 primop VecReadScalarOffAddrOp "readOffAddrAs#" GenPrimOp
3086    Addr# -> Int# -> State# s -> (# State# s, VECTOR #)
3087    { Reads vector; offset in scalar elements. }
3088    with has_side_effects = True
3089         can_fail = True
3090         llvm_only = True
3091         vector = ALL_VECTOR_TYPES
3092
3093 primop VecWriteScalarOffAddrOp "writeOffAddrAs#" GenPrimOp
3094    Addr# -> Int# -> VECTOR -> State# s -> State# s
3095    { Write vector; offset in scalar elements. }
3096    with has_side_effects = True
3097         can_fail = True
3098         llvm_only = True
3099         vector = ALL_VECTOR_TYPES
3100
3101 ------------------------------------------------------------------------
3102
3103 section "Prefetch"
3104         {Prefetch operations: Note how every prefetch operation has a name
3105   with the pattern prefetch*N#, where N is either 0,1,2, or 3.
3106
3107   This suffix number, N, is the "locality level" of the prefetch, following the
3108   convention in GCC and other compilers.
3109   Higher locality numbers correspond to the memory being loaded in more
3110   levels of the cpu cache, and being retained after initial use. The naming
3111   convention follows the naming convention of the prefetch intrinsic found
3112   in the GCC and Clang C compilers.
3113
3114   On the LLVM backend, prefetch*N# uses the LLVM prefetch intrinsic
3115   with locality level N. The code generated by LLVM is target architecture
3116   dependent, but should agree with the GHC NCG on x86 systems.
3117
3118   On the Sparc and PPC native backends, prefetch*N is a No-Op.
3119
3120   On the x86 NCG, N=0 will generate prefetchNTA,
3121   N=1 generates prefetcht2, N=2 generates prefetcht1, and
3122   N=3 generates prefetcht0.
3123
3124   For streaming workloads, the prefetch*0 operations are recommended.
3125   For workloads which do many reads or writes to a memory location in a short period of time,
3126   prefetch*3 operations are recommended.
3127
3128   For further reading about prefetch and associated systems performance optimization,
3129   the instruction set and optimization manuals by Intel and other CPU vendors are
3130   excellent starting place.
3131
3132
3133   The "Intel 64 and IA-32 Architectures Optimization Reference Manual" is
3134   especially a helpful read, even if your software is meant for other CPU
3135   architectures or vendor hardware. The manual can be found at
3136   http://www.intel.com/content/www/us/en/architecture-and-technology/64-ia-32-architectures-optimization-manual.html .
3137
3138   The {\tt prefetch*} family of operations has the order of operations
3139   determined by passing around the {\tt State#} token.
3140
3141   To get a "pure" version of these operations, use {\tt inlinePerformIO} which is quite safe in this context.
3142
3143   It is important to note that while the prefetch operations will never change the
3144   answer to a pure computation, They CAN change the memory locations resident
3145   in a CPU cache and that may change the performance and timing characteristics
3146   of an application. The prefetch operations are marked has_side_effects=True
3147   to reflect that these operations have side effects with respect to the runtime
3148   performance characteristics of the resulting code. Additionally, if the prefetchValue
3149   operations did not have this attribute, GHC does a float out transformation that
3150   results in a let/app violation, at least with the current design.
3151   }
3152
3153
3154
3155 ------------------------------------------------------------------------
3156
3157
3158 --- the Int# argument for prefetch is the byte offset on the byteArray or  Addr#
3159
3160 ---
3161 primop PrefetchByteArrayOp3 "prefetchByteArray3#" GenPrimOp
3162   ByteArray# -> Int# ->  State# s -> State# s
3163   with has_side_effects =  True
3164
3165 primop PrefetchMutableByteArrayOp3 "prefetchMutableByteArray3#" GenPrimOp
3166   MutableByteArray# s -> Int# -> State# s -> State# s
3167   with has_side_effects =  True
3168
3169 primop PrefetchAddrOp3 "prefetchAddr3#" GenPrimOp
3170   Addr# -> Int# -> State# s -> State# s
3171   with has_side_effects =  True
3172
3173 primop PrefetchValueOp3 "prefetchValue3#" GenPrimOp
3174    a -> State# s -> State# s
3175    with strictness  = { \ _arity -> mkClosedStrictSig [botDmd, topDmd] topRes }
3176         has_side_effects =  True
3177 ----
3178
3179 primop PrefetchByteArrayOp2 "prefetchByteArray2#" GenPrimOp
3180   ByteArray# -> Int# ->  State# s -> State# s
3181   with has_side_effects =  True
3182
3183 primop PrefetchMutableByteArrayOp2 "prefetchMutableByteArray2#" GenPrimOp
3184   MutableByteArray# s -> Int# -> State# s -> State# s
3185   with has_side_effects =  True
3186
3187 primop PrefetchAddrOp2 "prefetchAddr2#" GenPrimOp
3188   Addr# -> Int# ->  State# s -> State# s
3189   with has_side_effects =  True
3190
3191 primop PrefetchValueOp2 "prefetchValue2#" GenPrimOp
3192    a ->  State# s -> State# s
3193    with strictness  = { \ _arity -> mkClosedStrictSig [botDmd, topDmd] topRes }
3194         has_side_effects =  True
3195 ----
3196
3197 primop PrefetchByteArrayOp1 "prefetchByteArray1#" GenPrimOp
3198    ByteArray# -> Int# -> State# s -> State# s
3199    with has_side_effects =  True
3200
3201 primop PrefetchMutableByteArrayOp1 "prefetchMutableByteArray1#" GenPrimOp
3202   MutableByteArray# s -> Int# -> State# s -> State# s
3203   with has_side_effects =  True
3204
3205 primop PrefetchAddrOp1 "prefetchAddr1#" GenPrimOp
3206   Addr# -> Int# -> State# s -> State# s
3207   with has_side_effects =  True
3208
3209 primop PrefetchValueOp1 "prefetchValue1#" GenPrimOp
3210    a -> State# s -> State# s
3211    with strictness  = { \ _arity -> mkClosedStrictSig [botDmd, topDmd] topRes }
3212         has_side_effects =  True
3213 ----
3214
3215 primop PrefetchByteArrayOp0 "prefetchByteArray0#" GenPrimOp
3216   ByteArray# -> Int# ->  State# s -> State# s
3217   with has_side_effects =  True
3218
3219 primop PrefetchMutableByteArrayOp0 "prefetchMutableByteArray0#" GenPrimOp
3220   MutableByteArray# s -> Int# -> State# s -> State# s
3221   with has_side_effects =  True
3222
3223 primop PrefetchAddrOp0 "prefetchAddr0#" GenPrimOp
3224   Addr# -> Int# -> State# s -> State# s
3225   with has_side_effects =  True
3226
3227 primop PrefetchValueOp0 "prefetchValue0#" GenPrimOp
3228    a -> State# s -> State# s
3229    with strictness  = { \ _arity -> mkClosedStrictSig [botDmd, topDmd] topRes }
3230         has_side_effects =  True
3231
3232 ------------------------------------------------------------------------
3233 ---                                                                  ---
3234 ------------------------------------------------------------------------
3235
3236 thats_all_folks