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