Typos in comments only [ci skip]
[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   {Set the range of the MutableByteArray# to the specified character.}
1444   with
1445   has_side_effects = True
1446   code_size = { primOpCodeSizeForeignCall + 4 }
1447   can_fail = True
1448
1449 -- Atomic operations
1450
1451 primop  AtomicReadByteArrayOp_Int "atomicReadIntArray#" GenPrimOp
1452    MutableByteArray# s -> Int# -> State# s -> (# State# s, Int# #)
1453    {Given an array and an offset in Int units, read an element. The
1454     index is assumed to be in bounds. Implies a full memory barrier.}
1455    with has_side_effects = True
1456         can_fail = True
1457
1458 primop  AtomicWriteByteArrayOp_Int "atomicWriteIntArray#" GenPrimOp
1459    MutableByteArray# s -> Int# -> Int# -> State# s -> State# s
1460    {Given an array and an offset in Int units, write an element. The
1461     index is assumed to be in bounds. Implies a full memory barrier.}
1462    with has_side_effects = True
1463         can_fail = True
1464
1465 primop CasByteArrayOp_Int "casIntArray#" GenPrimOp
1466    MutableByteArray# s -> Int# -> Int# -> Int# -> State# s -> (# State# s, Int# #)
1467    {Given an array, an offset in Int units, the expected old value, and
1468     the new value, perform an atomic compare and swap i.e. write the new
1469     value if the current value matches the provided old value. Returns
1470     the value of the element before the operation. Implies a full memory
1471     barrier.}
1472    with has_side_effects = True
1473         can_fail = True
1474
1475 primop FetchAddByteArrayOp_Int "fetchAddIntArray#" GenPrimOp
1476    MutableByteArray# s -> Int# -> Int# -> State# s -> (# State# s, Int# #)
1477    {Given an array, and offset in Int units, and a value to add,
1478     atomically add the value to the element. Returns the value of the
1479     element before the operation. Implies a full memory barrier.}
1480    with has_side_effects = True
1481         can_fail = True
1482
1483 primop FetchSubByteArrayOp_Int "fetchSubIntArray#" GenPrimOp
1484    MutableByteArray# s -> Int# -> Int# -> State# s -> (# State# s, Int# #)
1485    {Given an array, and offset in Int units, and a value to subtract,
1486     atomically substract the value to the element. Returns the value of
1487     the element before the operation. Implies a full memory barrier.}
1488    with has_side_effects = True
1489         can_fail = True
1490
1491 primop FetchAndByteArrayOp_Int "fetchAndIntArray#" GenPrimOp
1492    MutableByteArray# s -> Int# -> Int# -> State# s -> (# State# s, Int# #)
1493    {Given an array, and offset in Int units, and a value to AND,
1494     atomically AND the value to the element. Returns the value of the
1495     element before the operation. Implies a full memory barrier.}
1496    with has_side_effects = True
1497         can_fail = True
1498
1499 primop FetchNandByteArrayOp_Int "fetchNandIntArray#" GenPrimOp
1500    MutableByteArray# s -> Int# -> Int# -> State# s -> (# State# s, Int# #)
1501    {Given an array, and offset in Int units, and a value to NAND,
1502     atomically NAND the value to the element. Returns the value of the
1503     element before the operation. Implies a full memory barrier.}
1504    with has_side_effects = True
1505         can_fail = True
1506
1507 primop FetchOrByteArrayOp_Int "fetchOrIntArray#" GenPrimOp
1508    MutableByteArray# s -> Int# -> Int# -> State# s -> (# State# s, Int# #)
1509    {Given an array, and offset in Int units, and a value to OR,
1510     atomically OR the value to the element. Returns the value of the
1511     element before the operation. Implies a full memory barrier.}
1512    with has_side_effects = True
1513         can_fail = True
1514
1515 primop FetchXorByteArrayOp_Int "fetchXorIntArray#" GenPrimOp
1516    MutableByteArray# s -> Int# -> Int# -> State# s -> (# State# s, Int# #)
1517    {Given an array, and offset in Int units, and a value to XOR,
1518     atomically XOR the value to the element. Returns the value of the
1519     element before the operation. Implies a full memory barrier.}
1520    with has_side_effects = True
1521         can_fail = True
1522
1523
1524 ------------------------------------------------------------------------
1525 section "Arrays of arrays"
1526         {Operations on {\tt ArrayArray\#}. An {\tt ArrayArray\#} contains references to {\em unpointed}
1527          arrays, such as {\tt ByteArray\#s}. Hence, it is not parameterised by the element types,
1528          just like a {\tt ByteArray\#}, but it needs to be scanned during GC, just like an {\tt Array#}.
1529          We represent an {\tt ArrayArray\#} exactly as a {\tt Array\#}, but provide element-type-specific
1530          indexing, reading, and writing.}
1531 ------------------------------------------------------------------------
1532
1533 primtype ArrayArray#
1534
1535 primtype MutableArrayArray# s
1536
1537 primop  NewArrayArrayOp "newArrayArray#" GenPrimOp
1538    Int# -> State# s -> (# State# s, MutableArrayArray# s #)
1539    {Create a new mutable array of arrays with the specified number of elements,
1540     in the specified state thread, with each element recursively referring to the
1541     newly created array.}
1542    with
1543    out_of_line = True
1544    has_side_effects = True
1545
1546 primop  SameMutableArrayArrayOp "sameMutableArrayArray#" GenPrimOp
1547    MutableArrayArray# s -> MutableArrayArray# s -> Int#
1548
1549 primop  UnsafeFreezeArrayArrayOp "unsafeFreezeArrayArray#" GenPrimOp
1550    MutableArrayArray# s -> State# s -> (# State# s, ArrayArray# #)
1551    {Make a mutable array of arrays immutable, without copying.}
1552    with
1553    has_side_effects = True
1554
1555 primop  SizeofArrayArrayOp "sizeofArrayArray#" GenPrimOp
1556    ArrayArray# -> Int#
1557    {Return the number of elements in the array.}
1558
1559 primop  SizeofMutableArrayArrayOp "sizeofMutableArrayArray#" GenPrimOp
1560    MutableArrayArray# s -> Int#
1561    {Return the number of elements in the array.}
1562
1563 primop IndexArrayArrayOp_ByteArray "indexByteArrayArray#" GenPrimOp
1564    ArrayArray# -> Int# -> ByteArray#
1565    with can_fail = True
1566
1567 primop IndexArrayArrayOp_ArrayArray "indexArrayArrayArray#" GenPrimOp
1568    ArrayArray# -> Int# -> ArrayArray#
1569    with can_fail = True
1570
1571 primop  ReadArrayArrayOp_ByteArray "readByteArrayArray#" GenPrimOp
1572    MutableArrayArray# s -> Int# -> State# s -> (# State# s, ByteArray# #)
1573    with has_side_effects = True
1574         can_fail = True
1575
1576 primop  ReadArrayArrayOp_MutableByteArray "readMutableByteArrayArray#" GenPrimOp
1577    MutableArrayArray# s -> Int# -> State# s -> (# State# s, MutableByteArray# s #)
1578    with has_side_effects = True
1579         can_fail = True
1580
1581 primop  ReadArrayArrayOp_ArrayArray "readArrayArrayArray#" GenPrimOp
1582    MutableArrayArray# s -> Int# -> State# s -> (# State# s, ArrayArray# #)
1583    with has_side_effects = True
1584         can_fail = True
1585
1586 primop  ReadArrayArrayOp_MutableArrayArray "readMutableArrayArrayArray#" GenPrimOp
1587    MutableArrayArray# s -> Int# -> State# s -> (# State# s, MutableArrayArray# s #)
1588    with has_side_effects = True
1589         can_fail = True
1590
1591 primop  WriteArrayArrayOp_ByteArray "writeByteArrayArray#" GenPrimOp
1592    MutableArrayArray# s -> Int# -> ByteArray# -> State# s -> State# s
1593    with has_side_effects = True
1594         can_fail = True
1595
1596 primop  WriteArrayArrayOp_MutableByteArray "writeMutableByteArrayArray#" GenPrimOp
1597    MutableArrayArray# s -> Int# -> MutableByteArray# s -> State# s -> State# s
1598    with has_side_effects = True
1599         can_fail = True
1600
1601 primop  WriteArrayArrayOp_ArrayArray "writeArrayArrayArray#" GenPrimOp
1602    MutableArrayArray# s -> Int# -> ArrayArray# -> State# s -> State# s
1603    with has_side_effects = True
1604         can_fail = True
1605
1606 primop  WriteArrayArrayOp_MutableArrayArray "writeMutableArrayArrayArray#" GenPrimOp
1607    MutableArrayArray# s -> Int# -> MutableArrayArray# s -> State# s -> State# s
1608    with has_side_effects = True
1609         can_fail = True
1610
1611 primop  CopyArrayArrayOp "copyArrayArray#" GenPrimOp
1612   ArrayArray# -> Int# -> MutableArrayArray# s -> Int# -> Int# -> State# s -> State# s
1613   {Copy a range of the ArrayArray# to the specified region in the MutableArrayArray#.
1614    Both arrays must fully contain the specified ranges, but this is not checked.
1615    The two arrays must not be the same array in different states, but this is not checked either.}
1616   with
1617   out_of_line      = True
1618   has_side_effects = True
1619   can_fail         = True
1620
1621 primop  CopyMutableArrayArrayOp "copyMutableArrayArray#" GenPrimOp
1622   MutableArrayArray# s -> Int# -> MutableArrayArray# s -> Int# -> Int# -> State# s -> State# s
1623   {Copy a range of the first MutableArrayArray# to the specified region in the second
1624    MutableArrayArray#.
1625    Both arrays must fully contain the specified ranges, but this is not checked.}
1626   with
1627   out_of_line      = True
1628   has_side_effects = True
1629   can_fail         = True
1630
1631 ------------------------------------------------------------------------
1632 section "Addr#"
1633 ------------------------------------------------------------------------
1634
1635 primtype Addr#
1636         { An arbitrary machine address assumed to point outside
1637          the garbage-collected heap. }
1638
1639 pseudoop "nullAddr#" Addr#
1640         { The null address. }
1641
1642 primop   AddrAddOp "plusAddr#" GenPrimOp Addr# -> Int# -> Addr#
1643 primop   AddrSubOp "minusAddr#" GenPrimOp Addr# -> Addr# -> Int#
1644          {Result is meaningless if two {\tt Addr\#}s are so far apart that their
1645          difference doesn't fit in an {\tt Int\#}.}
1646 primop   AddrRemOp "remAddr#" GenPrimOp Addr# -> Int# -> Int#
1647          {Return the remainder when the {\tt Addr\#} arg, treated like an {\tt Int\#},
1648           is divided by the {\tt Int\#} arg.}
1649 #if (WORD_SIZE_IN_BITS == 32 || WORD_SIZE_IN_BITS == 64)
1650 primop   Addr2IntOp  "addr2Int#"     GenPrimOp   Addr# -> Int#
1651         {Coerce directly from address to int. Strongly deprecated.}
1652    with code_size = 0
1653 primop   Int2AddrOp   "int2Addr#"    GenPrimOp  Int# -> Addr#
1654         {Coerce directly from int to address. Strongly deprecated.}
1655    with code_size = 0
1656 #endif
1657
1658 primop   AddrGtOp  "gtAddr#"   Compare   Addr# -> Addr# -> Int#
1659 primop   AddrGeOp  "geAddr#"   Compare   Addr# -> Addr# -> Int#
1660 primop   AddrEqOp  "eqAddr#"   Compare   Addr# -> Addr# -> Int#
1661 primop   AddrNeOp  "neAddr#"   Compare   Addr# -> Addr# -> Int#
1662 primop   AddrLtOp  "ltAddr#"   Compare   Addr# -> Addr# -> Int#
1663 primop   AddrLeOp  "leAddr#"   Compare   Addr# -> Addr# -> Int#
1664
1665 primop IndexOffAddrOp_Char "indexCharOffAddr#" GenPrimOp
1666    Addr# -> Int# -> Char#
1667    {Reads 8-bit character; offset in bytes.}
1668    with can_fail = True
1669
1670 primop IndexOffAddrOp_WideChar "indexWideCharOffAddr#" GenPrimOp
1671    Addr# -> Int# -> Char#
1672    {Reads 31-bit character; offset in 4-byte words.}
1673    with can_fail = True
1674
1675 primop IndexOffAddrOp_Int "indexIntOffAddr#" GenPrimOp
1676    Addr# -> Int# -> Int#
1677    with can_fail = True
1678
1679 primop IndexOffAddrOp_Word "indexWordOffAddr#" GenPrimOp
1680    Addr# -> Int# -> Word#
1681    with can_fail = True
1682
1683 primop IndexOffAddrOp_Addr "indexAddrOffAddr#" GenPrimOp
1684    Addr# -> Int# -> Addr#
1685    with can_fail = True
1686
1687 primop IndexOffAddrOp_Float "indexFloatOffAddr#" GenPrimOp
1688    Addr# -> Int# -> Float#
1689    with can_fail = True
1690
1691 primop IndexOffAddrOp_Double "indexDoubleOffAddr#" GenPrimOp
1692    Addr# -> Int# -> Double#
1693    with can_fail = True
1694
1695 primop IndexOffAddrOp_StablePtr "indexStablePtrOffAddr#" GenPrimOp
1696    Addr# -> Int# -> StablePtr# a
1697    with can_fail = True
1698
1699 primop IndexOffAddrOp_Int8 "indexInt8OffAddr#" GenPrimOp
1700    Addr# -> Int# -> Int#
1701    with can_fail = True
1702
1703 primop IndexOffAddrOp_Int16 "indexInt16OffAddr#" GenPrimOp
1704    Addr# -> Int# -> Int#
1705    with can_fail = True
1706
1707 primop IndexOffAddrOp_Int32 "indexInt32OffAddr#" GenPrimOp
1708    Addr# -> Int# -> INT32
1709    with can_fail = True
1710
1711 primop IndexOffAddrOp_Int64 "indexInt64OffAddr#" GenPrimOp
1712    Addr# -> Int# -> INT64
1713    with can_fail = True
1714
1715 primop IndexOffAddrOp_Word8 "indexWord8OffAddr#" GenPrimOp
1716    Addr# -> Int# -> Word#
1717    with can_fail = True
1718
1719 primop IndexOffAddrOp_Word16 "indexWord16OffAddr#" GenPrimOp
1720    Addr# -> Int# -> Word#
1721    with can_fail = True
1722
1723 primop IndexOffAddrOp_Word32 "indexWord32OffAddr#" GenPrimOp
1724    Addr# -> Int# -> WORD32
1725    with can_fail = True
1726
1727 primop IndexOffAddrOp_Word64 "indexWord64OffAddr#" GenPrimOp
1728    Addr# -> Int# -> WORD64
1729    with can_fail = True
1730
1731 primop ReadOffAddrOp_Char "readCharOffAddr#" GenPrimOp
1732    Addr# -> Int# -> State# s -> (# State# s, Char# #)
1733    {Reads 8-bit character; offset in bytes.}
1734    with has_side_effects = True
1735         can_fail         = True
1736
1737 primop ReadOffAddrOp_WideChar "readWideCharOffAddr#" GenPrimOp
1738    Addr# -> Int# -> State# s -> (# State# s, Char# #)
1739    {Reads 31-bit character; offset in 4-byte words.}
1740    with has_side_effects = True
1741         can_fail         = True
1742
1743 primop ReadOffAddrOp_Int "readIntOffAddr#" GenPrimOp
1744    Addr# -> Int# -> State# s -> (# State# s, Int# #)
1745    with has_side_effects = True
1746         can_fail         = True
1747
1748 primop ReadOffAddrOp_Word "readWordOffAddr#" GenPrimOp
1749    Addr# -> Int# -> State# s -> (# State# s, Word# #)
1750    with has_side_effects = True
1751         can_fail         = True
1752
1753 primop ReadOffAddrOp_Addr "readAddrOffAddr#" GenPrimOp
1754    Addr# -> Int# -> State# s -> (# State# s, Addr# #)
1755    with has_side_effects = True
1756         can_fail         = True
1757
1758 primop ReadOffAddrOp_Float "readFloatOffAddr#" GenPrimOp
1759    Addr# -> Int# -> State# s -> (# State# s, Float# #)
1760    with has_side_effects = True
1761         can_fail         = True
1762
1763 primop ReadOffAddrOp_Double "readDoubleOffAddr#" GenPrimOp
1764    Addr# -> Int# -> State# s -> (# State# s, Double# #)
1765    with has_side_effects = True
1766         can_fail         = True
1767
1768 primop ReadOffAddrOp_StablePtr "readStablePtrOffAddr#" GenPrimOp
1769    Addr# -> Int# -> State# s -> (# State# s, StablePtr# a #)
1770    with has_side_effects = True
1771         can_fail         = True
1772
1773 primop ReadOffAddrOp_Int8 "readInt8OffAddr#" GenPrimOp
1774    Addr# -> Int# -> State# s -> (# State# s, Int# #)
1775    with has_side_effects = True
1776         can_fail         = True
1777
1778 primop ReadOffAddrOp_Int16 "readInt16OffAddr#" GenPrimOp
1779    Addr# -> Int# -> State# s -> (# State# s, Int# #)
1780    with has_side_effects = True
1781         can_fail         = True
1782
1783 primop ReadOffAddrOp_Int32 "readInt32OffAddr#" GenPrimOp
1784    Addr# -> Int# -> State# s -> (# State# s, INT32 #)
1785    with has_side_effects = True
1786         can_fail         = True
1787
1788 primop ReadOffAddrOp_Int64 "readInt64OffAddr#" GenPrimOp
1789    Addr# -> Int# -> State# s -> (# State# s, INT64 #)
1790    with has_side_effects = True
1791         can_fail         = True
1792
1793 primop ReadOffAddrOp_Word8 "readWord8OffAddr#" GenPrimOp
1794    Addr# -> Int# -> State# s -> (# State# s, Word# #)
1795    with has_side_effects = True
1796         can_fail         = True
1797
1798 primop ReadOffAddrOp_Word16 "readWord16OffAddr#" GenPrimOp
1799    Addr# -> Int# -> State# s -> (# State# s, Word# #)
1800    with has_side_effects = True
1801         can_fail         = True
1802
1803 primop ReadOffAddrOp_Word32 "readWord32OffAddr#" GenPrimOp
1804    Addr# -> Int# -> State# s -> (# State# s, WORD32 #)
1805    with has_side_effects = True
1806         can_fail         = True
1807
1808 primop ReadOffAddrOp_Word64 "readWord64OffAddr#" GenPrimOp
1809    Addr# -> Int# -> State# s -> (# State# s, WORD64 #)
1810    with has_side_effects = True
1811         can_fail         = True
1812
1813 primop  WriteOffAddrOp_Char "writeCharOffAddr#" GenPrimOp
1814    Addr# -> Int# -> Char# -> State# s -> State# s
1815    with has_side_effects = True
1816         can_fail         = True
1817
1818 primop  WriteOffAddrOp_WideChar "writeWideCharOffAddr#" GenPrimOp
1819    Addr# -> Int# -> Char# -> State# s -> State# s
1820    with has_side_effects = True
1821         can_fail         = True
1822
1823 primop  WriteOffAddrOp_Int "writeIntOffAddr#" GenPrimOp
1824    Addr# -> Int# -> Int# -> State# s -> State# s
1825    with has_side_effects = True
1826         can_fail         = True
1827
1828 primop  WriteOffAddrOp_Word "writeWordOffAddr#" GenPrimOp
1829    Addr# -> Int# -> Word# -> State# s -> State# s
1830    with has_side_effects = True
1831         can_fail         = True
1832
1833 primop  WriteOffAddrOp_Addr "writeAddrOffAddr#" GenPrimOp
1834    Addr# -> Int# -> Addr# -> State# s -> State# s
1835    with has_side_effects = True
1836         can_fail         = True
1837
1838 primop  WriteOffAddrOp_Float "writeFloatOffAddr#" GenPrimOp
1839    Addr# -> Int# -> Float# -> State# s -> State# s
1840    with has_side_effects = True
1841         can_fail         = True
1842
1843 primop  WriteOffAddrOp_Double "writeDoubleOffAddr#" GenPrimOp
1844    Addr# -> Int# -> Double# -> State# s -> State# s
1845    with has_side_effects = True
1846         can_fail         = True
1847
1848 primop  WriteOffAddrOp_StablePtr "writeStablePtrOffAddr#" GenPrimOp
1849    Addr# -> Int# -> StablePtr# a -> State# s -> State# s
1850    with has_side_effects = True
1851         can_fail         = True
1852
1853 primop  WriteOffAddrOp_Int8 "writeInt8OffAddr#" GenPrimOp
1854    Addr# -> Int# -> Int# -> State# s -> State# s
1855    with has_side_effects = True
1856         can_fail         = True
1857
1858 primop  WriteOffAddrOp_Int16 "writeInt16OffAddr#" GenPrimOp
1859    Addr# -> Int# -> Int# -> State# s -> State# s
1860    with has_side_effects = True
1861         can_fail         = True
1862
1863 primop  WriteOffAddrOp_Int32 "writeInt32OffAddr#" GenPrimOp
1864    Addr# -> Int# -> INT32 -> State# s -> State# s
1865    with has_side_effects = True
1866         can_fail         = True
1867
1868 primop  WriteOffAddrOp_Int64 "writeInt64OffAddr#" GenPrimOp
1869    Addr# -> Int# -> INT64 -> State# s -> State# s
1870    with has_side_effects = True
1871         can_fail         = True
1872
1873 primop  WriteOffAddrOp_Word8 "writeWord8OffAddr#" GenPrimOp
1874    Addr# -> Int# -> Word# -> State# s -> State# s
1875    with has_side_effects = True
1876         can_fail         = True
1877
1878 primop  WriteOffAddrOp_Word16 "writeWord16OffAddr#" GenPrimOp
1879    Addr# -> Int# -> Word# -> State# s -> State# s
1880    with has_side_effects = True
1881         can_fail         = True
1882
1883 primop  WriteOffAddrOp_Word32 "writeWord32OffAddr#" GenPrimOp
1884    Addr# -> Int# -> WORD32 -> State# s -> State# s
1885    with has_side_effects = True
1886         can_fail         = True
1887
1888 primop  WriteOffAddrOp_Word64 "writeWord64OffAddr#" GenPrimOp
1889    Addr# -> Int# -> WORD64 -> State# s -> State# s
1890    with has_side_effects = True
1891         can_fail         = True
1892
1893 ------------------------------------------------------------------------
1894 section "Mutable variables"
1895         {Operations on MutVar\#s.}
1896 ------------------------------------------------------------------------
1897
1898 primtype MutVar# s a
1899         {A {\tt MutVar\#} behaves like a single-element mutable array.}
1900
1901 primop  NewMutVarOp "newMutVar#" GenPrimOp
1902    a -> State# s -> (# State# s, MutVar# s a #)
1903    {Create {\tt MutVar\#} with specified initial value in specified state thread.}
1904    with
1905    out_of_line = True
1906    has_side_effects = True
1907
1908 primop  ReadMutVarOp "readMutVar#" GenPrimOp
1909    MutVar# s a -> State# s -> (# State# s, a #)
1910    {Read contents of {\tt MutVar\#}. Result is not yet evaluated.}
1911    with
1912    has_side_effects = True
1913    can_fail         = True
1914
1915 primop  WriteMutVarOp "writeMutVar#"  GenPrimOp
1916    MutVar# s a -> a -> State# s -> State# s
1917    {Write contents of {\tt MutVar\#}.}
1918    with
1919    has_side_effects = True
1920    code_size = { primOpCodeSizeForeignCall } -- for the write barrier
1921    can_fail         = True
1922
1923 primop  SameMutVarOp "sameMutVar#" GenPrimOp
1924    MutVar# s a -> MutVar# s a -> Int#
1925
1926 -- not really the right type, but we don't know about pairs here.  The
1927 -- correct type is
1928 --
1929 --   MutVar# s a -> (a -> (a,b)) -> State# s -> (# State# s, b #)
1930 --
1931 primop  AtomicModifyMutVarOp "atomicModifyMutVar#" GenPrimOp
1932    MutVar# s a -> (a -> b) -> State# s -> (# State# s, c #)
1933    with
1934    out_of_line = True
1935    has_side_effects = True
1936    can_fail         = True
1937
1938 primop  CasMutVarOp "casMutVar#" GenPrimOp
1939   MutVar# s a -> a -> a -> State# s -> (# State# s, Int#, a #)
1940    with
1941    out_of_line = True
1942    has_side_effects = True
1943
1944 ------------------------------------------------------------------------
1945 section "Exceptions"
1946 ------------------------------------------------------------------------
1947
1948 {- Note [Strictness for mask/unmask/catch]
1949 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1950 Consider this example, which comes from GHC.IO.Handle.Internals:
1951    wantReadableHandle3 f ma b st
1952      = case ... of
1953          DEFAULT -> case ma of MVar a -> ...
1954          0#      -> maskAsynchExceptions# (\st -> case ma of MVar a -> ...)
1955 The outer case just decides whether to mask exceptions, but we don't want
1956 thereby to hide the strictness in 'ma'!  Hence the use of strictApply1Dmd.
1957
1958 For catch, we must be extra careful; see
1959 Note [Exceptions and strictness] in Demand
1960 -}
1961
1962 primop  CatchOp "catch#" GenPrimOp
1963           (State# RealWorld -> (# State# RealWorld, a #) )
1964        -> (b -> State# RealWorld -> (# State# RealWorld, a #) )
1965        -> State# RealWorld
1966        -> (# State# RealWorld, a #)
1967    with
1968    strictness  = { \ _arity -> mkClosedStrictSig [ catchArgDmd
1969                                                  , lazyApply2Dmd
1970                                                  , topDmd] topRes }
1971                  -- See Note [Strictness for mask/unmask/catch]
1972    out_of_line = True
1973    has_side_effects = True
1974
1975 primop  RaiseOp "raise#" GenPrimOp
1976    b -> o
1977       -- NB: the type variable "o" is "a", but with OpenKind
1978    with
1979    strictness  = { \ _arity -> mkClosedStrictSig [topDmd] exnRes }
1980       -- NB: result is ThrowsExn
1981    out_of_line = True
1982    has_side_effects = True
1983      -- raise# certainly throws a Haskell exception and hence has_side_effects
1984      -- It doesn't actually make much difference because the fact that it
1985      -- returns bottom independently ensures that we are careful not to discard
1986      -- it.  But still, it's better to say the Right Thing.
1987
1988 -- raiseIO# needs to be a primop, because exceptions in the IO monad
1989 -- must be *precise* - we don't want the strictness analyser turning
1990 -- one kind of bottom into another, as it is allowed to do in pure code.
1991 --
1992 -- But we *do* want to know that it returns bottom after
1993 -- being applied to two arguments, so that this function is strict in y
1994 --     f x y | x>0       = raiseIO blah
1995 --           | y>0       = return 1
1996 --           | otherwise = return 2
1997
1998 primop  RaiseIOOp "raiseIO#" GenPrimOp
1999    a -> State# RealWorld -> (# State# RealWorld, b #)
2000    with
2001    strictness  = { \ _arity -> mkClosedStrictSig [topDmd, topDmd] exnRes }
2002    out_of_line = True
2003    has_side_effects = True
2004
2005 primop  MaskAsyncExceptionsOp "maskAsyncExceptions#" GenPrimOp
2006         (State# RealWorld -> (# State# RealWorld, a #))
2007      -> (State# RealWorld -> (# State# RealWorld, a #))
2008    with
2009    strictness  = { \ _arity -> mkClosedStrictSig [strictApply1Dmd,topDmd] topRes }
2010                  -- See Note [Strictness for mask/unmask/catch]
2011    out_of_line = True
2012    has_side_effects = True
2013
2014 primop  MaskUninterruptibleOp "maskUninterruptible#" GenPrimOp
2015         (State# RealWorld -> (# State# RealWorld, a #))
2016      -> (State# RealWorld -> (# State# RealWorld, a #))
2017    with
2018    strictness  = { \ _arity -> mkClosedStrictSig [strictApply1Dmd,topDmd] topRes }
2019    out_of_line = True
2020    has_side_effects = True
2021
2022 primop  UnmaskAsyncExceptionsOp "unmaskAsyncExceptions#" GenPrimOp
2023         (State# RealWorld -> (# State# RealWorld, a #))
2024      -> (State# RealWorld -> (# State# RealWorld, a #))
2025    with
2026    strictness  = { \ _arity -> mkClosedStrictSig [strictApply1Dmd,topDmd] topRes }
2027                  -- See Note [Strictness for mask/unmask/catch]
2028    out_of_line = True
2029    has_side_effects = True
2030
2031 primop  MaskStatus "getMaskingState#" GenPrimOp
2032         State# RealWorld -> (# State# RealWorld, Int# #)
2033    with
2034    out_of_line = True
2035    has_side_effects = True
2036
2037 ------------------------------------------------------------------------
2038 section "STM-accessible Mutable Variables"
2039 ------------------------------------------------------------------------
2040
2041 primtype TVar# s a
2042
2043 primop  AtomicallyOp "atomically#" GenPrimOp
2044       (State# RealWorld -> (# State# RealWorld, a #) )
2045    -> State# RealWorld -> (# State# RealWorld, a #)
2046    with
2047    strictness  = { \ _arity -> mkClosedStrictSig [strictApply1Dmd,topDmd] topRes }
2048                  -- See Note [Strictness for mask/unmask/catch]
2049    out_of_line = True
2050    has_side_effects = True
2051
2052 -- NB: retry#'s strictness information specifies it to return bottom.
2053 -- This lets the compiler perform some extra simplifications, since retry#
2054 -- will technically never return.
2055 --
2056 -- This allows the simplifier to replace things like:
2057 --   case retry# s1
2058 --     (# s2, a #) -> e
2059 -- with:
2060 --   retry# s1
2061 -- where 'e' would be unreachable anyway.  See Trac #8091.
2062 primop  RetryOp "retry#" GenPrimOp
2063    State# RealWorld -> (# State# RealWorld, a #)
2064    with
2065    strictness  = { \ _arity -> mkClosedStrictSig [topDmd] botRes }
2066    out_of_line = True
2067    has_side_effects = True
2068
2069 primop  CatchRetryOp "catchRetry#" GenPrimOp
2070       (State# RealWorld -> (# State# RealWorld, a #) )
2071    -> (State# RealWorld -> (# State# RealWorld, a #) )
2072    -> (State# RealWorld -> (# State# RealWorld, a #) )
2073    with
2074    strictness  = { \ _arity -> mkClosedStrictSig [ catchArgDmd
2075                                                  , lazyApply1Dmd
2076                                                  , topDmd ] topRes }
2077                  -- See Note [Strictness for mask/unmask/catch]
2078    out_of_line = True
2079    has_side_effects = True
2080
2081 primop  CatchSTMOp "catchSTM#" GenPrimOp
2082       (State# RealWorld -> (# State# RealWorld, a #) )
2083    -> (b -> State# RealWorld -> (# State# RealWorld, a #) )
2084    -> (State# RealWorld -> (# State# RealWorld, a #) )
2085    with
2086    strictness  = { \ _arity -> mkClosedStrictSig [ catchArgDmd
2087                                                  , lazyApply2Dmd
2088                                                  , topDmd ] topRes }
2089                  -- See Note [Strictness for mask/unmask/catch]
2090    out_of_line = True
2091    has_side_effects = True
2092
2093 primop  Check "check#" GenPrimOp
2094       (State# RealWorld -> (# State# RealWorld, a #) )
2095    -> (State# RealWorld -> State# RealWorld)
2096    with
2097    out_of_line = True
2098    has_side_effects = True
2099
2100 primop  NewTVarOp "newTVar#" GenPrimOp
2101        a
2102     -> State# s -> (# State# s, TVar# s a #)
2103    {Create a new {\tt TVar\#} holding a specified initial value.}
2104    with
2105    out_of_line  = True
2106    has_side_effects = True
2107
2108 primop  ReadTVarOp "readTVar#" GenPrimOp
2109        TVar# s a
2110     -> State# s -> (# State# s, a #)
2111    {Read contents of {\tt TVar\#}.  Result is not yet evaluated.}
2112    with
2113    out_of_line  = True
2114    has_side_effects = True
2115
2116 primop ReadTVarIOOp "readTVarIO#" GenPrimOp
2117        TVar# s a
2118     -> State# s -> (# State# s, a #)
2119    {Read contents of {\tt TVar\#} outside an STM transaction}
2120    with
2121    out_of_line      = True
2122    has_side_effects = True
2123
2124 primop  WriteTVarOp "writeTVar#" GenPrimOp
2125        TVar# s a
2126     -> a
2127     -> State# s -> State# s
2128    {Write contents of {\tt TVar\#}.}
2129    with
2130    out_of_line      = True
2131    has_side_effects = True
2132
2133 primop  SameTVarOp "sameTVar#" GenPrimOp
2134    TVar# s a -> TVar# s a -> Int#
2135
2136
2137 ------------------------------------------------------------------------
2138 section "Synchronized Mutable Variables"
2139         {Operations on {\tt MVar\#}s. }
2140 ------------------------------------------------------------------------
2141
2142 primtype MVar# s a
2143         { A shared mutable variable ({\it not} the same as a {\tt MutVar\#}!).
2144         (Note: in a non-concurrent implementation, {\tt (MVar\# a)} can be
2145         represented by {\tt (MutVar\# (Maybe a))}.) }
2146
2147 primop  NewMVarOp "newMVar#"  GenPrimOp
2148    State# s -> (# State# s, MVar# s a #)
2149    {Create new {\tt MVar\#}; initially empty.}
2150    with
2151    out_of_line = True
2152    has_side_effects = True
2153
2154 primop  TakeMVarOp "takeMVar#" GenPrimOp
2155    MVar# s a -> State# s -> (# State# s, a #)
2156    {If {\tt MVar\#} is empty, block until it becomes full.
2157    Then remove and return its contents, and set it empty.}
2158    with
2159    out_of_line      = True
2160    has_side_effects = True
2161
2162 primop  TryTakeMVarOp "tryTakeMVar#" GenPrimOp
2163    MVar# s a -> State# s -> (# State# s, Int#, a #)
2164    {If {\tt MVar\#} is empty, immediately return with integer 0 and value undefined.
2165    Otherwise, return with integer 1 and contents of {\tt MVar\#}, and set {\tt MVar\#} empty.}
2166    with
2167    out_of_line      = True
2168    has_side_effects = True
2169
2170 primop  PutMVarOp "putMVar#" GenPrimOp
2171    MVar# s a -> a -> State# s -> State# s
2172    {If {\tt MVar\#} is full, block until it becomes empty.
2173    Then store value arg as its new contents.}
2174    with
2175    out_of_line      = True
2176    has_side_effects = True
2177
2178 primop  TryPutMVarOp "tryPutMVar#" GenPrimOp
2179    MVar# s a -> a -> State# s -> (# State# s, Int# #)
2180    {If {\tt MVar\#} is full, immediately return with integer 0.
2181     Otherwise, store value arg as {\tt MVar\#}'s new contents, and return with integer 1.}
2182    with
2183    out_of_line      = True
2184    has_side_effects = True
2185
2186 primop  ReadMVarOp "readMVar#" GenPrimOp
2187    MVar# s a -> State# s -> (# State# s, a #)
2188    {If {\tt MVar\#} is empty, block until it becomes full.
2189    Then read its contents without modifying the MVar, without possibility
2190    of intervention from other threads.}
2191    with
2192    out_of_line      = True
2193    has_side_effects = True
2194
2195 primop  TryReadMVarOp "tryReadMVar#" GenPrimOp
2196    MVar# s a -> State# s -> (# State# s, Int#, a #)
2197    {If {\tt MVar\#} is empty, immediately return with integer 0 and value undefined.
2198    Otherwise, return with integer 1 and contents of {\tt MVar\#}.}
2199    with
2200    out_of_line      = True
2201    has_side_effects = True
2202
2203 primop  SameMVarOp "sameMVar#" GenPrimOp
2204    MVar# s a -> MVar# s a -> Int#
2205
2206 primop  IsEmptyMVarOp "isEmptyMVar#" GenPrimOp
2207    MVar# s a -> State# s -> (# State# s, Int# #)
2208    {Return 1 if {\tt MVar\#} is empty; 0 otherwise.}
2209    with
2210    out_of_line = True
2211    has_side_effects = True
2212
2213 ------------------------------------------------------------------------
2214 section "Delay/wait operations"
2215 ------------------------------------------------------------------------
2216
2217 primop  DelayOp "delay#" GenPrimOp
2218    Int# -> State# s -> State# s
2219    {Sleep specified number of microseconds.}
2220    with
2221    has_side_effects = True
2222    out_of_line      = True
2223
2224 primop  WaitReadOp "waitRead#" GenPrimOp
2225    Int# -> State# s -> State# s
2226    {Block until input is available on specified file descriptor.}
2227    with
2228    has_side_effects = True
2229    out_of_line      = True
2230
2231 primop  WaitWriteOp "waitWrite#" GenPrimOp
2232    Int# -> State# s -> State# s
2233    {Block until output is possible on specified file descriptor.}
2234    with
2235    has_side_effects = True
2236    out_of_line      = True
2237
2238 #ifdef mingw32_TARGET_OS
2239 primop  AsyncReadOp "asyncRead#" GenPrimOp
2240    Int# -> Int# -> Int# -> Addr# -> State# RealWorld-> (# State# RealWorld, Int#, Int# #)
2241    {Asynchronously read bytes from specified file descriptor.}
2242    with
2243    has_side_effects = True
2244    out_of_line      = True
2245
2246 primop  AsyncWriteOp "asyncWrite#" GenPrimOp
2247    Int# -> Int# -> Int# -> Addr# -> State# RealWorld-> (# State# RealWorld, Int#, Int# #)
2248    {Asynchronously write bytes from specified file descriptor.}
2249    with
2250    has_side_effects = True
2251    out_of_line      = True
2252
2253 primop  AsyncDoProcOp "asyncDoProc#" GenPrimOp
2254    Addr# -> Addr# -> State# RealWorld-> (# State# RealWorld, Int#, Int# #)
2255    {Asynchronously perform procedure (first arg), passing it 2nd arg.}
2256    with
2257    has_side_effects = True
2258    out_of_line      = True
2259
2260 #endif
2261
2262 ------------------------------------------------------------------------
2263 section "Concurrency primitives"
2264 ------------------------------------------------------------------------
2265
2266 primtype State# s
2267         { {\tt State\#} is the primitive, unlifted type of states.  It has
2268         one type parameter, thus {\tt State\# RealWorld}, or {\tt State\# s},
2269         where s is a type variable. The only purpose of the type parameter
2270         is to keep different state threads separate.  It is represented by
2271         nothing at all. }
2272
2273 primtype RealWorld
2274         { {\tt RealWorld} is deeply magical.  It is {\it primitive}, but it is not
2275         {\it unlifted} (hence {\tt ptrArg}).  We never manipulate values of type
2276         {\tt RealWorld}; it's only used in the type system, to parameterise {\tt State\#}. }
2277
2278 primtype ThreadId#
2279         {(In a non-concurrent implementation, this can be a singleton
2280         type, whose (unique) value is returned by {\tt myThreadId\#}.  The
2281         other operations can be omitted.)}
2282
2283 primop  ForkOp "fork#" GenPrimOp
2284    a -> State# RealWorld -> (# State# RealWorld, ThreadId# #)
2285    with
2286    has_side_effects = True
2287    out_of_line      = True
2288
2289 primop  ForkOnOp "forkOn#" GenPrimOp
2290    Int# -> a -> State# RealWorld -> (# State# RealWorld, ThreadId# #)
2291    with
2292    has_side_effects = True
2293    out_of_line      = True
2294
2295 primop  KillThreadOp "killThread#"  GenPrimOp
2296    ThreadId# -> a -> State# RealWorld -> State# RealWorld
2297    with
2298    has_side_effects = True
2299    out_of_line      = True
2300
2301 primop  YieldOp "yield#" GenPrimOp
2302    State# RealWorld -> State# RealWorld
2303    with
2304    has_side_effects = True
2305    out_of_line      = True
2306
2307 primop  MyThreadIdOp "myThreadId#" GenPrimOp
2308    State# RealWorld -> (# State# RealWorld, ThreadId# #)
2309    with
2310    out_of_line = True
2311    has_side_effects = True
2312
2313 primop LabelThreadOp "labelThread#" GenPrimOp
2314    ThreadId# -> Addr# -> State# RealWorld -> State# RealWorld
2315    with
2316    has_side_effects = True
2317    out_of_line      = True
2318
2319 primop  IsCurrentThreadBoundOp "isCurrentThreadBound#" GenPrimOp
2320    State# RealWorld -> (# State# RealWorld, Int# #)
2321    with
2322    out_of_line = True
2323    has_side_effects = True
2324
2325 primop  NoDuplicateOp "noDuplicate#" GenPrimOp
2326    State# RealWorld -> State# RealWorld
2327    with
2328    out_of_line = True
2329    has_side_effects = True
2330
2331 primop  ThreadStatusOp "threadStatus#" GenPrimOp
2332    ThreadId# -> State# RealWorld -> (# State# RealWorld, Int#, Int#, Int# #)
2333    with
2334    out_of_line = True
2335    has_side_effects = True
2336
2337 ------------------------------------------------------------------------
2338 section "Weak pointers"
2339 ------------------------------------------------------------------------
2340
2341 primtype Weak# b
2342
2343 -- note that tyvar "o" denotes openAlphaTyVar
2344
2345 primop  MkWeakOp "mkWeak#" GenPrimOp
2346    o -> b -> (State# RealWorld -> (# State# RealWorld, c #))
2347      -> State# RealWorld -> (# State# RealWorld, Weak# b #)
2348    with
2349    has_side_effects = True
2350    out_of_line      = True
2351
2352 primop  MkWeakNoFinalizerOp "mkWeakNoFinalizer#" GenPrimOp
2353    o -> b -> State# RealWorld -> (# State# RealWorld, Weak# b #)
2354    with
2355    has_side_effects = True
2356    out_of_line      = True
2357
2358 primop  AddCFinalizerToWeakOp "addCFinalizerToWeak#" GenPrimOp
2359    Addr# -> Addr# -> Int# -> Addr# -> Weak# b
2360           -> State# RealWorld -> (# State# RealWorld, Int# #)
2361    { {\tt addCFinalizerToWeak# fptr ptr flag eptr w} attaches a C
2362      function pointer {\tt fptr} to a weak pointer {\tt w} as a finalizer. If
2363      {\tt flag} is zero, {\tt fptr} will be called with one argument,
2364      {\tt ptr}. Otherwise, it will be called with two arguments,
2365      {\tt eptr} and {\tt ptr}. {\tt addCFinalizerToWeak#} returns
2366      1 on success, or 0 if {\tt w} is already dead. }
2367    with
2368    has_side_effects = True
2369    out_of_line      = True
2370
2371 primop  DeRefWeakOp "deRefWeak#" GenPrimOp
2372    Weak# a -> State# RealWorld -> (# State# RealWorld, Int#, a #)
2373    with
2374    has_side_effects = True
2375    out_of_line      = True
2376
2377 primop  FinalizeWeakOp "finalizeWeak#" GenPrimOp
2378    Weak# a -> State# RealWorld -> (# State# RealWorld, Int#,
2379               (State# RealWorld -> (# State# RealWorld, b #) ) #)
2380    { Finalize a weak pointer. The return value is an unboxed tuple
2381      containing the new state of the world and an "unboxed Maybe",
2382      represented by an {\tt Int#} and a (possibly invalid) finalization
2383      action. An {\tt Int#} of {\tt 1} indicates that the finalizer is valid. The
2384      return value {\tt b} from the finalizer should be ignored. }
2385    with
2386    has_side_effects = True
2387    out_of_line      = True
2388
2389 primop TouchOp "touch#" GenPrimOp
2390    o -> State# RealWorld -> State# RealWorld
2391    with
2392    code_size = { 0 }
2393    has_side_effects = True
2394
2395 ------------------------------------------------------------------------
2396 section "Stable pointers and names"
2397 ------------------------------------------------------------------------
2398
2399 primtype StablePtr# a
2400
2401 primtype StableName# a
2402
2403 primop  MakeStablePtrOp "makeStablePtr#" GenPrimOp
2404    a -> State# RealWorld -> (# State# RealWorld, StablePtr# a #)
2405    with
2406    has_side_effects = True
2407    out_of_line      = True
2408
2409 primop  DeRefStablePtrOp "deRefStablePtr#" GenPrimOp
2410    StablePtr# a -> State# RealWorld -> (# State# RealWorld, a #)
2411    with
2412    has_side_effects = True
2413    out_of_line      = True
2414
2415 primop  EqStablePtrOp "eqStablePtr#" GenPrimOp
2416    StablePtr# a -> StablePtr# a -> Int#
2417    with
2418    has_side_effects = True
2419
2420 primop  MakeStableNameOp "makeStableName#" GenPrimOp
2421    a -> State# RealWorld -> (# State# RealWorld, StableName# a #)
2422    with
2423    has_side_effects = True
2424    out_of_line      = True
2425
2426 primop  EqStableNameOp "eqStableName#" GenPrimOp
2427    StableName# a -> StableName# b -> Int#
2428
2429 primop  StableNameToIntOp "stableNameToInt#" GenPrimOp
2430    StableName# a -> Int#
2431
2432 ------------------------------------------------------------------------
2433 section "Compact normal form"
2434 ------------------------------------------------------------------------
2435
2436 primtype Compact#
2437
2438 primop  CompactNewOp "compactNew#" GenPrimOp
2439    Word# -> State# RealWorld -> (# State# RealWorld, Compact# #)
2440    { Create a new Compact with the given size (in bytes, not words).
2441      The size is rounded up to a multiple of the allocator block size,
2442      and capped to one mega block. }
2443    with
2444    has_side_effects = True
2445    out_of_line      = True
2446
2447 primop  CompactResizeOp "compactResize#" GenPrimOp
2448    Compact# -> Word# -> State# RealWorld ->
2449    State# RealWorld
2450    { Set the new allocation size of the compact. This value (in bytes)
2451      determines the size of each block in the compact chain. }
2452    with
2453    has_side_effects = True
2454    out_of_line      = True
2455
2456 primop  CompactContainsOp "compactContains#" GenPrimOp
2457    Compact# -> a -> State# RealWorld -> (# State# RealWorld, Int# #)
2458    { Returns 1# if the object is contained in the compact, 0# otherwise. }
2459    with
2460    out_of_line      = True
2461
2462 primop  CompactContainsAnyOp "compactContainsAny#" GenPrimOp
2463    a -> State# RealWorld -> (# State# RealWorld, Int# #)
2464    { Returns 1# if the object is in any compact at all, 0# otherwise. }
2465    with
2466    out_of_line      = True
2467
2468 primop  CompactGetFirstBlockOp "compactGetFirstBlock#" GenPrimOp
2469    Compact# -> State# RealWorld -> (# State# RealWorld, Addr#, Word# #)
2470    { Returns the address and the size (in bytes) of the first block of
2471      a compact. }
2472    with
2473    out_of_line      = True
2474
2475 primop  CompactGetNextBlockOp "compactGetNextBlock#" GenPrimOp
2476    Compact# -> Addr# -> State# RealWorld -> (# State# RealWorld, Addr#, Word# #)
2477    { Given a compact and the address of one its blocks, returns the
2478      next block and its size, or #nullAddr if the argument was the
2479      last block in the compact. }
2480    with
2481    out_of_line      = True
2482
2483 primop  CompactAllocateBlockOp "compactAllocateBlock#" GenPrimOp
2484    Word# -> Addr# -> State# RealWorld -> (# State# RealWorld, Addr# #)
2485    { Attempt to allocate a compact block with the given size (in
2486      bytes) at the given address. The first argument is a hint to
2487      the allocator, allocation might be satisfied at a different
2488      address (which is returned).
2489      The resulting block is not known to the GC until
2490      compactFixupPointers# is called on it, and care must be taken
2491      so that the address does not escape or memory will be leaked.
2492    }
2493    with
2494    has_side_effects = True
2495    out_of_line      = True
2496
2497 primop  CompactFixupPointersOp "compactFixupPointers#" GenPrimOp
2498    Addr# -> Addr# -> State# RealWorld -> (# State# RealWorld, Compact#, Addr# #)
2499    { Given the pointer to the first block of a compact, and the
2500      address of the root object in the old address space, fix up
2501      the internal pointers inside the compact to account for
2502      a different position in memory than when it was serialized.
2503      This method must be called exactly once after importing
2504      a serialized compact, and returns the new compact and
2505      the new adjusted root address. }
2506    with
2507    has_side_effects = True
2508    out_of_line      = True
2509
2510 primop CompactAdd "compactAdd#" GenPrimOp
2511    Compact# -> a -> State# RealWorld -> (# State# RealWorld, a #)
2512    { Recursively add a closure and its transitive closure to a
2513      {\texttt Compact\#}, evaluating any unevaluated components at the
2514      same time.  Note: {\texttt compactAdd\#} is not thread-safe, so
2515      only one thread may call {\texttt compactAdd\#} with a particular
2516      {\texttt Compact#} at any given time.  The primop does not
2517      enforce any mutual exclusion; the caller is expected to
2518      arrange this. }
2519    with
2520    has_side_effects = True
2521    out_of_line      = True
2522
2523 primop CompactAddWithSharing "compactAddWithSharing#" GenPrimOp
2524    Compact# -> a -> State# RealWorld -> (# State# RealWorld, a #)
2525    { Like {\texttt compactAdd\#}, but retains sharing and cycles
2526    during compaction. }
2527    with
2528    has_side_effects = True
2529    out_of_line      = True
2530
2531 primop CompactSize "compactSize#" GenPrimOp
2532    Compact# -> State# RealWorld -> (# State# RealWorld, Word# #)
2533    { Return the size (in bytes) of the total amount of data in the Compact# }
2534    with
2535    has_side_effects = True
2536    out_of_line      = True
2537
2538 ------------------------------------------------------------------------
2539 section "Unsafe pointer equality"
2540 --  (#1 Bad Guy: Alastair Reid :)
2541 ------------------------------------------------------------------------
2542
2543 primop  ReallyUnsafePtrEqualityOp "reallyUnsafePtrEquality#" GenPrimOp
2544    a -> a -> Int#
2545
2546 ------------------------------------------------------------------------
2547 section "Parallelism"
2548 ------------------------------------------------------------------------
2549
2550 primop  ParOp "par#" GenPrimOp
2551    a -> Int#
2552    with
2553       -- Note that Par is lazy to avoid that the sparked thing
2554       -- gets evaluated strictly, which it should *not* be
2555    has_side_effects = True
2556    code_size = { primOpCodeSizeForeignCall }
2557
2558 primop SparkOp "spark#" GenPrimOp
2559    a -> State# s -> (# State# s, a #)
2560    with has_side_effects = True
2561    code_size = { primOpCodeSizeForeignCall }
2562
2563 primop SeqOp "seq#" GenPrimOp
2564    a -> State# s -> (# State# s, a #)
2565
2566    -- why return the value?  So that we can control sharing of seq'd
2567    -- values: in
2568    --    let x = e in x `seq` ... x ...
2569    -- we don't want to inline x, so better to represent it as
2570    --    let x = e in case seq# x RW of (# _, x' #) -> ... x' ...
2571    -- also it matches the type of rseq in the Eval monad.
2572
2573 primop GetSparkOp "getSpark#" GenPrimOp
2574    State# s -> (# State# s, Int#, a #)
2575    with
2576    has_side_effects = True
2577    out_of_line = True
2578
2579 primop NumSparks "numSparks#" GenPrimOp
2580    State# s -> (# State# s, Int# #)
2581    { Returns the number of sparks in the local spark pool. }
2582    with
2583    has_side_effects = True
2584    out_of_line = True
2585
2586 ------------------------------------------------------------------------
2587 section "Tag to enum stuff"
2588         {Convert back and forth between values of enumerated types
2589         and small integers.}
2590 ------------------------------------------------------------------------
2591
2592 primop  DataToTagOp "dataToTag#" GenPrimOp
2593    a -> Int#
2594    with
2595    can_fail   = True -- See Note [dataToTag#]
2596    strictness = { \ _arity -> mkClosedStrictSig [evalDmd] topRes }
2597                 -- dataToTag# must have an evaluated argument
2598
2599 primop  TagToEnumOp "tagToEnum#" GenPrimOp
2600    Int# -> a
2601
2602 {- Note [dataToTag#]
2603 ~~~~~~~~~~~~~~~~~~~~
2604 The dataToTag# primop should always be applied to an evaluated argument.
2605 The way to ensure this is to invoke it via the 'getTag' wrapper in GHC.Base:
2606    getTag :: a -> Int#
2607    getTag !x = dataToTag# x
2608
2609 But now consider
2610     \z. case x of y -> let v = dataToTag# y in ...
2611
2612 To improve floating, the FloatOut pass (deliberately) does a
2613 binder-swap on the case, to give
2614     \z. case x of y -> let v = dataToTag# x in ...
2615
2616 Now FloatOut might float that v-binding outside the \z.  But that is
2617 bad because that might mean x gest evaluated much too early!  (CorePrep
2618 adds an eval to a dataToTag# call, to ensure that the argument really is
2619 evaluated; see CorePrep Note [dataToTag magic].)
2620
2621 Solution: make DataToTag into a can_fail primop.  That will stop it floating
2622 (see Note [PrimOp can_fail and has_side_effects] in PrimOp).  It's a bit of
2623 a hack but never mind.
2624 -}
2625
2626 ------------------------------------------------------------------------
2627 section "Bytecode operations"
2628         {Support for manipulating bytecode objects used by the interpreter and
2629         linker.
2630
2631         Bytecode objects are heap objects which represent top-level bindings and
2632         contain a list of instructions and data needed by these instructions.}
2633 ------------------------------------------------------------------------
2634
2635 primtype BCO#
2636    { Primitive bytecode type. }
2637
2638 primop   AddrToAnyOp "addrToAny#" GenPrimOp
2639    Addr# -> (# a #)
2640    { Convert an {\tt Addr\#} to a followable Any type. }
2641    with
2642    code_size = 0
2643
2644 primop   AnyToAddrOp "anyToAddr#" GenPrimOp
2645    a -> State# RealWorld -> (# State# RealWorld, Addr# #)
2646    { Retrive the address of any Haskell value. This is
2647      essentially an {\texttt unsafeCoerce\#}, but if implemented as such
2648      the core lint pass complains and fails to compile.
2649      As a primop, it is opaque to core/stg, and only appears
2650      in cmm (where the copy propagation pass will get rid of it).
2651      Note that "a" must be a value, not a thunk! It's too late
2652      for strictness analysis to enforce this, so you're on your
2653      own to guarantee this. Also note that {\texttt Addr\#} is not a GC
2654      pointer - up to you to guarantee that it does not become
2655      a dangling pointer immediately after you get it.}
2656    with
2657    code_size = 0
2658
2659 primop   MkApUpd0_Op "mkApUpd0#" GenPrimOp
2660    BCO# -> (# a #)
2661    { Wrap a BCO in a {\tt AP_UPD} thunk which will be updated with the value of
2662      the BCO when evaluated. }
2663    with
2664    out_of_line = True
2665
2666 primop  NewBCOOp "newBCO#" GenPrimOp
2667    ByteArray# -> ByteArray# -> Array# a -> Int# -> ByteArray# -> State# s -> (# State# s, BCO# #)
2668    { {\tt newBCO\# instrs lits ptrs arity bitmap} creates a new bytecode object. The
2669      resulting object encodes a function of the given arity with the instructions
2670      encoded in {\tt instrs}, and a static reference table usage bitmap given by
2671      {\tt bitmap}. }
2672    with
2673    has_side_effects = True
2674    out_of_line      = True
2675
2676 primop  UnpackClosureOp "unpackClosure#" GenPrimOp
2677    a -> (# Addr#, Array# b, ByteArray# #)
2678    { {\tt unpackClosure\# closure} copies non-pointers and pointers in the
2679      payload of the given closure into two new arrays, and returns a pointer to
2680      the first word of the closure's info table, a pointer array for the
2681      pointers in the payload, and a non-pointer array for the non-pointers in
2682      the payload. }
2683    with
2684    out_of_line = True
2685
2686 primop  GetApStackValOp "getApStackVal#" GenPrimOp
2687    a -> Int# -> (# Int#, b #)
2688    with
2689    out_of_line = True
2690
2691 ------------------------------------------------------------------------
2692 section "Misc"
2693         {These aren't nearly as wired in as Etc...}
2694 ------------------------------------------------------------------------
2695
2696 primop  GetCCSOfOp "getCCSOf#" GenPrimOp
2697    a -> State# s -> (# State# s, Addr# #)
2698
2699 primop  GetCurrentCCSOp "getCurrentCCS#" GenPrimOp
2700    a -> State# s -> (# State# s, Addr# #)
2701    { Returns the current {\tt CostCentreStack} (value is {\tt NULL} if
2702      not profiling).  Takes a dummy argument which can be used to
2703      avoid the call to {\tt getCCCS\#} being floated out by the
2704      simplifier, which would result in an uninformative stack
2705      ("CAF"). }
2706
2707 primop  ClearCCSOp "clearCCS#" GenPrimOp
2708    (State# s -> (# State# s, a #)) -> State# s -> (# State# s, a #)
2709    { Run the supplied IO action with an empty CCS.  For example, this
2710      is used by the interpreter to run an interpreted computation
2711      without the call stack showing that it was invoked from GHC. }
2712    with
2713    out_of_line = True
2714
2715 ------------------------------------------------------------------------
2716 section "Etc"
2717         {Miscellaneous built-ins}
2718 ------------------------------------------------------------------------
2719
2720 primtype Proxy# a
2721    { The type constructor {\tt Proxy#} is used to bear witness to some
2722    type variable. It's used when you want to pass around proxy values
2723    for doing things like modelling type applications. A {\tt Proxy#}
2724    is not only unboxed, it also has a polymorphic kind, and has no
2725    runtime representation, being totally free. }
2726
2727 pseudoop "proxy#"
2728    Proxy# a
2729    { Witness for an unboxed {\tt Proxy#} value, which has no runtime
2730    representation. }
2731
2732 pseudoop   "seq"
2733    a -> b -> b
2734    { The value of {\tt seq a b} is bottom if {\tt a} is bottom, and
2735      otherwise equal to {\tt b}. {\tt seq} is usually introduced to
2736      improve performance by avoiding unneeded laziness.
2737
2738      A note on evaluation order: the expression {\tt seq a b} does
2739      {\it not} guarantee that {\tt a} will be evaluated before {\tt b}.
2740      The only guarantee given by {\tt seq} is that the both {\tt a}
2741      and {\tt b} will be evaluated before {\tt seq} returns a value.
2742      In particular, this means that {\tt b} may be evaluated before
2743      {\tt a}. If you need to guarantee a specific order of evaluation,
2744      you must use the function {\tt pseq} from the "parallel" package. }
2745
2746 pseudoop   "unsafeCoerce#"
2747    a -> b
2748    { The function {\tt unsafeCoerce\#} allows you to side-step the typechecker entirely. That
2749         is, it allows you to coerce any type into any other type. If you use this function,
2750         you had better get it right, otherwise segmentation faults await. It is generally
2751         used when you want to write a program that you know is well-typed, but where Haskell's
2752         type system is not expressive enough to prove that it is well typed.
2753
2754         The following uses of {\tt unsafeCoerce\#} are supposed to work (i.e. not lead to
2755         spurious compile-time or run-time crashes):
2756
2757          * Casting any lifted type to {\tt Any}
2758
2759          * Casting {\tt Any} back to the real type
2760
2761          * Casting an unboxed type to another unboxed type of the same size
2762            (but not coercions between floating-point and integral types)
2763
2764          * Casting between two types that have the same runtime representation.  One case is when
2765            the two types differ only in "phantom" type parameters, for example
2766            {\tt Ptr Int} to {\tt Ptr Float}, or {\tt [Int]} to {\tt [Float]} when the list is
2767            known to be empty.  Also, a {\tt newtype} of a type {\tt T} has the same representation
2768            at runtime as {\tt T}.
2769
2770         Other uses of {\tt unsafeCoerce\#} are undefined.  In particular, you should not use
2771         {\tt unsafeCoerce\#} to cast a T to an algebraic data type D, unless T is also
2772         an algebraic data type.  For example, do not cast {\tt Int->Int} to {\tt Bool}, even if
2773         you later cast that {\tt Bool} back to {\tt Int->Int} before applying it.  The reasons
2774         have to do with GHC's internal representation details (for the congnoscenti, data values
2775         can be entered but function closures cannot).  If you want a safe type to cast things
2776         to, use {\tt Any}, which is not an algebraic data type.
2777
2778         }
2779
2780 -- NB. It is tempting to think that casting a value to a type that it doesn't have is safe
2781 -- as long as you don't "do anything" with the value in its cast form, such as seq on it.  This
2782 -- isn't the case: the compiler can insert seqs itself, and if these happen at the wrong type,
2783 -- Bad Things Might Happen.  See bug #1616: in this case we cast a function of type (a,b) -> (a,b)
2784 -- to () -> () and back again.  The strictness analyser saw that the function was strict, but
2785 -- the wrapper had type () -> (), and hence the wrapper de-constructed the (), the worker re-constructed
2786 -- a new (), with the result that the code ended up with "case () of (a,b) -> ...".
2787
2788 primop  TraceEventOp "traceEvent#" GenPrimOp
2789    Addr# -> State# s -> State# s
2790    { Emits an event via the RTS tracing framework.  The contents
2791      of the event is the zero-terminated byte string passed as the first
2792      argument.  The event will be emitted either to the .eventlog file,
2793      or to stderr, depending on the runtime RTS flags. }
2794    with
2795    has_side_effects = True
2796    out_of_line      = True
2797
2798 primop  TraceMarkerOp "traceMarker#" GenPrimOp
2799    Addr# -> State# s -> State# s
2800    { Emits a marker event via the RTS tracing framework.  The contents
2801      of the event is the zero-terminated byte string passed as the first
2802      argument.  The event will be emitted either to the .eventlog file,
2803      or to stderr, depending on the runtime RTS flags. }
2804    with
2805    has_side_effects = True
2806    out_of_line      = True
2807
2808 ------------------------------------------------------------------------
2809 section "Safe coercions"
2810 ------------------------------------------------------------------------
2811
2812 pseudoop   "coerce"
2813    Coercible a b => a -> b
2814    { The function {\tt coerce} allows you to safely convert between values of
2815      types that have the same representation with no run-time overhead. In the
2816      simplest case you can use it instead of a newtype constructor, to go from
2817      the newtype's concrete type to the abstract type. But it also works in
2818      more complicated settings, e.g. converting a list of newtypes to a list of
2819      concrete types.
2820    }
2821
2822 ------------------------------------------------------------------------
2823 section "SIMD Vectors"
2824         {Operations on SIMD vectors.}
2825 ------------------------------------------------------------------------
2826
2827 #define ALL_VECTOR_TYPES \
2828   [<Int8,Int#,16>,<Int16,Int#,8>,<Int32,INT32,4>,<Int64,INT64,2> \
2829   ,<Int8,Int#,32>,<Int16,Int#,16>,<Int32,INT32,8>,<Int64,INT64,4> \
2830   ,<Int8,Int#,64>,<Int16,Int#,32>,<Int32,INT32,16>,<Int64,INT64,8> \
2831   ,<Word8,Word#,16>,<Word16,Word#,8>,<Word32,WORD32,4>,<Word64,WORD64,2> \
2832   ,<Word8,Word#,32>,<Word16,Word#,16>,<Word32,WORD32,8>,<Word64,WORD64,4> \
2833   ,<Word8,Word#,64>,<Word16,Word#,32>,<Word32,WORD32,16>,<Word64,WORD64,8> \
2834   ,<Float,Float#,4>,<Double,Double#,2> \
2835   ,<Float,Float#,8>,<Double,Double#,4> \
2836   ,<Float,Float#,16>,<Double,Double#,8>]
2837
2838 #define SIGNED_VECTOR_TYPES \
2839   [<Int8,Int#,16>,<Int16,Int#,8>,<Int32,INT32,4>,<Int64,INT64,2> \
2840   ,<Int8,Int#,32>,<Int16,Int#,16>,<Int32,INT32,8>,<Int64,INT64,4> \
2841   ,<Int8,Int#,64>,<Int16,Int#,32>,<Int32,INT32,16>,<Int64,INT64,8> \
2842   ,<Float,Float#,4>,<Double,Double#,2> \
2843   ,<Float,Float#,8>,<Double,Double#,4> \
2844   ,<Float,Float#,16>,<Double,Double#,8>]
2845
2846 #define FLOAT_VECTOR_TYPES \
2847   [<Float,Float#,4>,<Double,Double#,2> \
2848   ,<Float,Float#,8>,<Double,Double#,4> \
2849   ,<Float,Float#,16>,<Double,Double#,8>]
2850
2851 #define INT_VECTOR_TYPES \
2852   [<Int8,Int#,16>,<Int16,Int#,8>,<Int32,INT32,4>,<Int64,INT64,2> \
2853   ,<Int8,Int#,32>,<Int16,Int#,16>,<Int32,INT32,8>,<Int64,INT64,4> \
2854   ,<Int8,Int#,64>,<Int16,Int#,32>,<Int32,INT32,16>,<Int64,INT64,8> \
2855   ,<Word8,Word#,16>,<Word16,Word#,8>,<Word32,WORD32,4>,<Word64,WORD64,2> \
2856   ,<Word8,Word#,32>,<Word16,Word#,16>,<Word32,WORD32,8>,<Word64,WORD64,4> \
2857   ,<Word8,Word#,64>,<Word16,Word#,32>,<Word32,WORD32,16>,<Word64,WORD64,8>]
2858
2859 primtype VECTOR
2860    with llvm_only = True
2861         vector = ALL_VECTOR_TYPES
2862
2863 primop VecBroadcastOp "broadcast#" GenPrimOp
2864    SCALAR -> VECTOR
2865    { Broadcast a scalar to all elements of a vector. }
2866    with llvm_only = True
2867         vector = ALL_VECTOR_TYPES
2868
2869 primop VecPackOp "pack#" GenPrimOp
2870    VECTUPLE -> VECTOR
2871    { Pack the elements of an unboxed tuple into a vector. }
2872    with llvm_only = True
2873         vector = ALL_VECTOR_TYPES
2874
2875 primop VecUnpackOp "unpack#" GenPrimOp
2876    VECTOR -> VECTUPLE
2877    { Unpack the elements of a vector into an unboxed tuple. #}
2878    with llvm_only = True
2879         vector = ALL_VECTOR_TYPES
2880
2881 primop VecInsertOp "insert#" GenPrimOp
2882    VECTOR -> SCALAR -> Int# -> VECTOR
2883    { Insert a scalar at the given position in a vector. }
2884    with can_fail = True
2885         llvm_only = True
2886         vector = ALL_VECTOR_TYPES
2887
2888 primop VecAddOp "plus#" Dyadic
2889    VECTOR -> VECTOR -> VECTOR
2890    { Add two vectors element-wise. }
2891    with commutable = True
2892         llvm_only = True
2893         vector = ALL_VECTOR_TYPES
2894
2895 primop VecSubOp "minus#" Dyadic
2896    VECTOR -> VECTOR -> VECTOR
2897    { Subtract two vectors element-wise. }
2898    with llvm_only = True
2899         vector = ALL_VECTOR_TYPES
2900
2901 primop VecMulOp "times#" Dyadic
2902    VECTOR -> VECTOR -> VECTOR
2903    { Multiply two vectors element-wise. }
2904    with commutable = True
2905         llvm_only = True
2906         vector = ALL_VECTOR_TYPES
2907
2908 primop VecDivOp "divide#" Dyadic
2909    VECTOR -> VECTOR -> VECTOR
2910    { Divide two vectors element-wise. }
2911    with can_fail = True
2912         llvm_only = True
2913         vector = FLOAT_VECTOR_TYPES
2914
2915 primop VecQuotOp "quot#" Dyadic
2916    VECTOR -> VECTOR -> VECTOR
2917    { Rounds towards zero element-wise. }
2918    with can_fail = True
2919         llvm_only = True
2920         vector = INT_VECTOR_TYPES
2921
2922 primop VecRemOp "rem#" Dyadic
2923    VECTOR -> VECTOR -> VECTOR
2924    { Satisfies \texttt{(quot\# x y) times\# y plus\# (rem\# x y) == x}. }
2925    with can_fail = True
2926         llvm_only = True
2927         vector = INT_VECTOR_TYPES
2928
2929 primop VecNegOp "negate#" Monadic
2930    VECTOR -> VECTOR
2931    { Negate element-wise. }
2932    with llvm_only = True
2933         vector = SIGNED_VECTOR_TYPES
2934
2935 primop VecIndexByteArrayOp "indexArray#" GenPrimOp
2936    ByteArray# -> Int# -> VECTOR
2937    { Read a vector from specified index of immutable array. }
2938    with can_fail = True
2939         llvm_only = True
2940         vector = ALL_VECTOR_TYPES
2941
2942 primop VecReadByteArrayOp "readArray#" GenPrimOp
2943    MutableByteArray# s -> Int# -> State# s -> (# State# s, VECTOR #)
2944    { Read a vector from specified index of mutable array. }
2945    with has_side_effects = True
2946         can_fail = True
2947         llvm_only = True
2948         vector = ALL_VECTOR_TYPES
2949
2950 primop VecWriteByteArrayOp "writeArray#" GenPrimOp
2951    MutableByteArray# s -> Int# -> VECTOR -> State# s -> State# s
2952    { Write a vector to specified index of mutable array. }
2953    with has_side_effects = True
2954         can_fail = True
2955         llvm_only = True
2956         vector = ALL_VECTOR_TYPES
2957
2958 primop VecIndexOffAddrOp "indexOffAddr#" GenPrimOp
2959    Addr# -> Int# -> VECTOR
2960    { Reads vector; offset in bytes. }
2961    with can_fail = True
2962         llvm_only = True
2963         vector = ALL_VECTOR_TYPES
2964
2965 primop VecReadOffAddrOp "readOffAddr#" GenPrimOp
2966    Addr# -> Int# -> State# s -> (# State# s, VECTOR #)
2967    { Reads vector; offset in bytes. }
2968    with has_side_effects = True
2969         can_fail = True
2970         llvm_only = True
2971         vector = ALL_VECTOR_TYPES
2972
2973 primop VecWriteOffAddrOp "writeOffAddr#" GenPrimOp
2974    Addr# -> Int# -> VECTOR -> State# s -> State# s
2975    { Write vector; offset in bytes. }
2976    with has_side_effects = True
2977         can_fail = True
2978         llvm_only = True
2979         vector = ALL_VECTOR_TYPES
2980
2981
2982 primop VecIndexScalarByteArrayOp "indexArrayAs#" GenPrimOp
2983    ByteArray# -> Int# -> VECTOR
2984    { Read a vector from specified index of immutable array of scalars; offset is in scalar elements. }
2985    with can_fail = True
2986         llvm_only = True
2987         vector = ALL_VECTOR_TYPES
2988
2989 primop VecReadScalarByteArrayOp "readArrayAs#" GenPrimOp
2990    MutableByteArray# s -> Int# -> State# s -> (# State# s, VECTOR #)
2991    { Read a vector from specified index of mutable array of scalars; offset is in scalar elements. }
2992    with has_side_effects = True
2993         can_fail = True
2994         llvm_only = True
2995         vector = ALL_VECTOR_TYPES
2996
2997 primop VecWriteScalarByteArrayOp "writeArrayAs#" GenPrimOp
2998    MutableByteArray# s -> Int# -> VECTOR -> State# s -> State# s
2999    { Write a vector to specified index of mutable array of scalars; offset is in scalar elements. }
3000    with has_side_effects = True
3001         can_fail = True
3002         llvm_only = True
3003         vector = ALL_VECTOR_TYPES
3004
3005 primop VecIndexScalarOffAddrOp "indexOffAddrAs#" GenPrimOp
3006    Addr# -> Int# -> VECTOR
3007    { Reads vector; offset in scalar elements. }
3008    with can_fail = True
3009         llvm_only = True
3010         vector = ALL_VECTOR_TYPES
3011
3012 primop VecReadScalarOffAddrOp "readOffAddrAs#" GenPrimOp
3013    Addr# -> Int# -> State# s -> (# State# s, VECTOR #)
3014    { Reads vector; offset in scalar elements. }
3015    with has_side_effects = True
3016         can_fail = True
3017         llvm_only = True
3018         vector = ALL_VECTOR_TYPES
3019
3020 primop VecWriteScalarOffAddrOp "writeOffAddrAs#" GenPrimOp
3021    Addr# -> Int# -> VECTOR -> State# s -> State# s
3022    { Write vector; offset in scalar elements. }
3023    with has_side_effects = True
3024         can_fail = True
3025         llvm_only = True
3026         vector = ALL_VECTOR_TYPES
3027
3028 ------------------------------------------------------------------------
3029
3030 section "Prefetch"
3031         {Prefetch operations: Note how every prefetch operation has a name
3032   with the pattern prefetch*N#, where N is either 0,1,2, or 3.
3033
3034   This suffix number, N, is the "locality level" of the prefetch, following the
3035   convention in GCC and other compilers.
3036   Higher locality numbers correspond to the memory being loaded in more
3037   levels of the cpu cache, and being retained after initial use. The naming
3038   convention follows the naming convention of the prefetch intrinsic found
3039   in the GCC and Clang C compilers.
3040
3041   On the LLVM backend, prefetch*N# uses the LLVM prefetch intrinsic
3042   with locality level N. The code generated by LLVM is target architecture
3043   dependent, but should agree with the GHC NCG on x86 systems.
3044
3045   On the Sparc and PPC native backends, prefetch*N is a No-Op.
3046
3047   On the x86 NCG, N=0 will generate prefetchNTA,
3048   N=1 generates prefetcht2, N=2 generates prefetcht1, and
3049   N=3 generates prefetcht0.
3050
3051   For streaming workloads, the prefetch*0 operations are recommended.
3052   For workloads which do many reads or writes to a memory location in a short period of time,
3053   prefetch*3 operations are recommended.
3054
3055   For further reading about prefetch and associated systems performance optimization,
3056   the instruction set and optimization manuals by Intel and other CPU vendors are
3057   excellent starting place.
3058
3059
3060   The "Intel 64 and IA-32 Architectures Optimization Reference Manual" is
3061   especially a helpful read, even if your software is meant for other CPU
3062   architectures or vendor hardware. The manual can be found at
3063   http://www.intel.com/content/www/us/en/architecture-and-technology/64-ia-32-architectures-optimization-manual.html .
3064
3065   The {\tt prefetch*} family of operations has the order of operations
3066   determined by passing around the {\tt State#} token.
3067
3068   To get a "pure" version of these operations, use {\tt inlinePerformIO} which is quite safe in this context.
3069
3070   It is important to note that while the prefetch operations will never change the
3071   answer to a pure computation, They CAN change the memory locations resident
3072   in a CPU cache and that may change the performance and timing characteristics
3073   of an application. The prefetch operations are marked has_side_effects=True
3074   to reflect that these operations have side effects with respect to the runtime
3075   performance characteristics of the resulting code. Additionally, if the prefetchValue
3076   operations did not have this attribute, GHC does a float out transformation that
3077   results in a let/app violation, at least with the current design.
3078   }
3079
3080
3081
3082 ------------------------------------------------------------------------
3083
3084
3085 --- the Int# argument for prefetch is the byte offset on the byteArray or  Addr#
3086
3087 ---
3088 primop PrefetchByteArrayOp3 "prefetchByteArray3#" GenPrimOp
3089   ByteArray# -> Int# ->  State# s -> State# s
3090   with has_side_effects =  True
3091
3092 primop PrefetchMutableByteArrayOp3 "prefetchMutableByteArray3#" GenPrimOp
3093   MutableByteArray# s -> Int# -> State# s -> State# s
3094   with has_side_effects =  True
3095
3096 primop PrefetchAddrOp3 "prefetchAddr3#" GenPrimOp
3097   Addr# -> Int# -> State# s -> State# s
3098   with has_side_effects =  True
3099
3100 primop PrefetchValueOp3 "prefetchValue3#" GenPrimOp
3101    a -> State# s -> State# s
3102    with strictness  = { \ _arity -> mkClosedStrictSig [botDmd, topDmd] topRes }
3103         has_side_effects =  True
3104 ----
3105
3106 primop PrefetchByteArrayOp2 "prefetchByteArray2#" GenPrimOp
3107   ByteArray# -> Int# ->  State# s -> State# s
3108   with has_side_effects =  True
3109
3110 primop PrefetchMutableByteArrayOp2 "prefetchMutableByteArray2#" GenPrimOp
3111   MutableByteArray# s -> Int# -> State# s -> State# s
3112   with has_side_effects =  True
3113
3114 primop PrefetchAddrOp2 "prefetchAddr2#" GenPrimOp
3115   Addr# -> Int# ->  State# s -> State# s
3116   with has_side_effects =  True
3117
3118 primop PrefetchValueOp2 "prefetchValue2#" GenPrimOp
3119    a ->  State# s -> State# s
3120    with strictness  = { \ _arity -> mkClosedStrictSig [botDmd, topDmd] topRes }
3121         has_side_effects =  True
3122 ----
3123
3124 primop PrefetchByteArrayOp1 "prefetchByteArray1#" GenPrimOp
3125    ByteArray# -> Int# -> State# s -> State# s
3126    with has_side_effects =  True
3127
3128 primop PrefetchMutableByteArrayOp1 "prefetchMutableByteArray1#" GenPrimOp
3129   MutableByteArray# s -> Int# -> State# s -> State# s
3130   with has_side_effects =  True
3131
3132 primop PrefetchAddrOp1 "prefetchAddr1#" GenPrimOp
3133   Addr# -> Int# -> State# s -> State# s
3134   with has_side_effects =  True
3135
3136 primop PrefetchValueOp1 "prefetchValue1#" GenPrimOp
3137    a -> State# s -> State# s
3138    with strictness  = { \ _arity -> mkClosedStrictSig [botDmd, topDmd] topRes }
3139         has_side_effects =  True
3140 ----
3141
3142 primop PrefetchByteArrayOp0 "prefetchByteArray0#" GenPrimOp
3143   ByteArray# -> Int# ->  State# s -> State# s
3144   with has_side_effects =  True
3145
3146 primop PrefetchMutableByteArrayOp0 "prefetchMutableByteArray0#" GenPrimOp
3147   MutableByteArray# s -> Int# -> State# s -> State# s
3148   with has_side_effects =  True
3149
3150 primop PrefetchAddrOp0 "prefetchAddr0#" GenPrimOp
3151   Addr# -> Int# -> State# s -> State# s
3152   with has_side_effects =  True
3153
3154 primop PrefetchValueOp0 "prefetchValue0#" GenPrimOp
3155    a -> State# s -> State# s
3156    with strictness  = { \ _arity -> mkClosedStrictSig [botDmd, topDmd] topRes }
3157         has_side_effects =  True
3158
3159 ------------------------------------------------------------------------
3160 ---                                                                  ---
3161 ------------------------------------------------------------------------
3162
3163 thats_all_folks