Update documentation concerning prefetch ops
[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 -> mkStrictSig (mkTopDmdType (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.}
225    with can_fail = True
226
227 primop   IntRemOp    "remInt#"    Dyadic
228    Int# -> Int# -> Int#
229    {Satisfies \texttt{(quotInt\# x y) *\# y +\# (remInt\# x y) == x}.}
230    with can_fail = True
231
232 primop   IntQuotRemOp "quotRemInt#"    GenPrimOp
233    Int# -> Int# -> (# Int#, Int# #)
234    {Rounds towards zero.}
235    with can_fail = True
236
237 primop   AndIOp   "andI#"   Dyadic    Int# -> Int# -> Int#
238    with commutable = True
239
240 primop   OrIOp   "orI#"     Dyadic    Int# -> Int# -> Int#
241    with commutable = True
242
243 primop   XorIOp   "xorI#"   Dyadic    Int# -> Int# -> Int#
244    with commutable = True
245
246 primop   NotIOp   "notI#"   Monadic   Int# -> Int#
247
248 primop   IntNegOp    "negateInt#"    Monadic   Int# -> Int#
249 primop   IntAddCOp   "addIntC#"    GenPrimOp   Int# -> Int# -> (# Int#, Int# #)
250          {Add with carry.  First member of result is (wrapped) sum;
251           second member is 0 iff no overflow occured.}
252    with code_size = 2
253
254 primop   IntSubCOp   "subIntC#"    GenPrimOp   Int# -> Int# -> (# Int#, Int# #)
255          {Subtract with carry.  First member of result is (wrapped) difference;
256           second member is 0 iff no overflow occured.}
257    with code_size = 2
258
259 primop   IntGtOp  ">#"   Compare   Int# -> Int# -> Int#
260    with fixity = infix 4
261
262 primop   IntGeOp  ">=#"   Compare   Int# -> Int# -> Int#
263    with fixity = infix 4
264
265 primop   IntEqOp  "==#"   Compare
266    Int# -> Int# -> Int#
267    with commutable = True
268         fixity = infix 4
269
270 primop   IntNeOp  "/=#"   Compare
271    Int# -> Int# -> Int#
272    with commutable = True
273         fixity = infix 4
274
275 primop   IntLtOp  "<#"   Compare   Int# -> Int# -> Int#
276    with fixity = infix 4
277
278 primop   IntLeOp  "<=#"   Compare   Int# -> Int# -> Int#
279    with fixity = infix 4
280
281 primop   ChrOp   "chr#"   GenPrimOp   Int# -> Char#
282    with code_size = 0
283
284 primop   Int2WordOp "int2Word#" GenPrimOp Int# -> Word#
285    with code_size = 0
286
287 primop   Int2FloatOp   "int2Float#"      GenPrimOp  Int# -> Float#
288 primop   Int2DoubleOp   "int2Double#"          GenPrimOp  Int# -> Double#
289
290 primop   Word2FloatOp   "word2Float#"      GenPrimOp  Word# -> Float#
291 primop   Word2DoubleOp   "word2Double#"          GenPrimOp  Word# -> Double#
292
293 primop   ISllOp   "uncheckedIShiftL#" GenPrimOp  Int# -> Int# -> Int#
294          {Shift left.  Result undefined if shift amount is not
295           in the range 0 to word size - 1 inclusive.}
296 primop   ISraOp   "uncheckedIShiftRA#" GenPrimOp Int# -> Int# -> Int#
297          {Shift right arithmetic.  Result undefined if shift amount is not
298           in the range 0 to word size - 1 inclusive.}
299 primop   ISrlOp   "uncheckedIShiftRL#" GenPrimOp Int# -> Int# -> Int#
300          {Shift right logical.  Result undefined if shift amount is not
301           in the range 0 to word size - 1 inclusive.}
302
303 ------------------------------------------------------------------------
304 section "Word#"
305         {Operations on native-sized unsigned words (30+ bits).}
306 ------------------------------------------------------------------------
307
308 primtype Word#
309
310 primop   WordAddOp   "plusWord#"   Dyadic   Word# -> Word# -> Word#
311    with commutable = True
312
313 -- Returns (# high, low #) (or equivalently, (# carry, low #))
314 primop   WordAdd2Op  "plusWord2#"  GenPrimOp
315    Word# -> Word# -> (# Word#, Word# #)
316    with commutable = True
317
318 primop   WordSubOp   "minusWord#"   Dyadic   Word# -> Word# -> Word#
319
320 primop   WordMulOp   "timesWord#"   Dyadic   Word# -> Word# -> Word#
321    with commutable = True
322
323 -- Returns (# high, low #)
324 primop   WordMul2Op  "timesWord2#"   GenPrimOp
325    Word# -> Word# -> (# Word#, Word# #)
326    with commutable = True
327
328 primop   WordQuotOp   "quotWord#"   Dyadic   Word# -> Word# -> Word#
329    with can_fail = True
330
331 primop   WordRemOp   "remWord#"   Dyadic   Word# -> Word# -> Word#
332    with can_fail = True
333
334 primop   WordQuotRemOp "quotRemWord#" GenPrimOp
335    Word# -> Word# -> (# Word#, Word# #)
336    with can_fail = True
337
338 -- Takes high word of dividend, then low word of dividend, then divisor.
339 -- Requires that high word is not divisible by divisor.
340 primop   WordQuotRem2Op "quotRemWord2#" GenPrimOp
341    Word# -> Word# -> Word# -> (# Word#, Word# #)
342    with can_fail = True
343
344 primop   AndOp   "and#"   Dyadic   Word# -> Word# -> Word#
345    with commutable = True
346
347 primop   OrOp   "or#"   Dyadic   Word# -> Word# -> Word#
348    with commutable = True
349
350 primop   XorOp   "xor#"   Dyadic   Word# -> Word# -> Word#
351    with commutable = True
352
353 primop   NotOp   "not#"   Monadic   Word# -> Word#
354
355 primop   SllOp   "uncheckedShiftL#"   GenPrimOp   Word# -> Int# -> Word#
356          {Shift left logical.   Result undefined if shift amount is not
357           in the range 0 to word size - 1 inclusive.}
358 primop   SrlOp   "uncheckedShiftRL#"   GenPrimOp   Word# -> Int# -> Word#
359          {Shift right logical.   Result undefined if shift  amount is not
360           in the range 0 to word size - 1 inclusive.}
361
362 primop   Word2IntOp   "word2Int#"   GenPrimOp   Word# -> Int#
363    with code_size = 0
364
365 primop   WordGtOp   "gtWord#"   Compare   Word# -> Word# -> Int#
366 primop   WordGeOp   "geWord#"   Compare   Word# -> Word# -> Int#
367 primop   WordEqOp   "eqWord#"   Compare   Word# -> Word# -> Int#
368 primop   WordNeOp   "neWord#"   Compare   Word# -> Word# -> Int#
369 primop   WordLtOp   "ltWord#"   Compare   Word# -> Word# -> Int#
370 primop   WordLeOp   "leWord#"   Compare   Word# -> Word# -> Int#
371
372 primop   PopCnt8Op   "popCnt8#"   Monadic   Word# -> Word#
373     {Count the number of set bits in the lower 8 bits of a word.}
374 primop   PopCnt16Op   "popCnt16#"   Monadic   Word# -> Word#
375     {Count the number of set bits in the lower 16 bits of a word.}
376 primop   PopCnt32Op   "popCnt32#"   Monadic   Word# -> Word#
377     {Count the number of set bits in the lower 32 bits of a word.}
378 primop   PopCnt64Op   "popCnt64#"   GenPrimOp   WORD64 -> Word#
379     {Count the number of set bits in a 64-bit word.}
380 primop   PopCntOp   "popCnt#"   Monadic   Word# -> Word#
381     {Count the number of set bits in a word.}
382
383 primop   BSwap16Op   "byteSwap16#"   Monadic   Word# -> Word#
384     {Swap bytes in the lower 16 bits of a word. The higher bytes are undefined. }
385 primop   BSwap32Op   "byteSwap32#"   Monadic   Word# -> Word#
386     {Swap bytes in the lower 32 bits of a word. The higher bytes are undefined. }
387 primop   BSwap64Op   "byteSwap64#"   Monadic   WORD64 -> WORD64
388     {Swap bytes in a 64 bits of a word.}
389 primop   BSwapOp     "byteSwap#"     Monadic   Word# -> Word#
390     {Swap bytes in a word.}
391
392 ------------------------------------------------------------------------
393 section "Narrowings"
394         {Explicit narrowing of native-sized ints or words.}
395 ------------------------------------------------------------------------
396
397 primop   Narrow8IntOp      "narrow8Int#"      Monadic   Int# -> Int#
398 primop   Narrow16IntOp     "narrow16Int#"     Monadic   Int# -> Int#
399 primop   Narrow32IntOp     "narrow32Int#"     Monadic   Int# -> Int#
400 primop   Narrow8WordOp     "narrow8Word#"     Monadic   Word# -> Word#
401 primop   Narrow16WordOp    "narrow16Word#"    Monadic   Word# -> Word#
402 primop   Narrow32WordOp    "narrow32Word#"    Monadic   Word# -> Word#
403
404
405 #if WORD_SIZE_IN_BITS < 32
406 ------------------------------------------------------------------------
407 section "Int32#"
408         {Operations on 32-bit integers ({\tt Int32\#}).  This type is only used
409          if plain {\tt Int\#} has less than 32 bits.  In any case, the operations
410          are not primops; they are implemented (if needed) as ccalls instead.}
411 ------------------------------------------------------------------------
412
413 primtype Int32#
414
415 ------------------------------------------------------------------------
416 section "Word32#"
417         {Operations on 32-bit unsigned words. This type is only used
418          if plain {\tt Word\#} has less than 32 bits. In any case, the operations
419          are not primops; they are implemented (if needed) as ccalls instead.}
420 ------------------------------------------------------------------------
421
422 primtype Word32#
423
424 #endif
425
426
427 #if WORD_SIZE_IN_BITS < 64
428 ------------------------------------------------------------------------
429 section "Int64#"
430         {Operations on 64-bit unsigned words. This type is only used
431          if plain {\tt Int\#} has less than 64 bits. In any case, the operations
432          are not primops; they are implemented (if needed) as ccalls instead.}
433 ------------------------------------------------------------------------
434
435 primtype Int64#
436
437 ------------------------------------------------------------------------
438 section "Word64#"
439         {Operations on 64-bit unsigned words. This type is only used
440          if plain {\tt Word\#} has less than 64 bits. In any case, the operations
441          are not primops; they are implemented (if needed) as ccalls instead.}
442 ------------------------------------------------------------------------
443
444 primtype Word64#
445
446 #endif
447
448 ------------------------------------------------------------------------
449 section "Double#"
450         {Operations on double-precision (64 bit) floating-point numbers.}
451 ------------------------------------------------------------------------
452
453 primtype Double#
454
455 primop   DoubleGtOp ">##"   Compare   Double# -> Double# -> Int#
456    with fixity = infix 4
457
458 primop   DoubleGeOp ">=##"   Compare   Double# -> Double# -> Int#
459    with fixity = infix 4
460
461 primop DoubleEqOp "==##"   Compare
462    Double# -> Double# -> Int#
463    with commutable = True
464         fixity = infix 4
465
466 primop DoubleNeOp "/=##"   Compare
467    Double# -> Double# -> Int#
468    with commutable = True
469         fixity = infix 4
470
471 primop   DoubleLtOp "<##"   Compare   Double# -> Double# -> Int#
472    with fixity = infix 4
473
474 primop   DoubleLeOp "<=##"   Compare   Double# -> Double# -> Int#
475    with fixity = infix 4
476
477 primop   DoubleAddOp   "+##"   Dyadic
478    Double# -> Double# -> Double#
479    with commutable = True
480         fixity = infixl 6
481
482 primop   DoubleSubOp   "-##"   Dyadic   Double# -> Double# -> Double#
483    with fixity = infixl 6
484
485 primop   DoubleMulOp   "*##"   Dyadic
486    Double# -> Double# -> Double#
487    with commutable = True
488         fixity = infixl 7
489
490 primop   DoubleDivOp   "/##"   Dyadic
491    Double# -> Double# -> Double#
492    with can_fail = True
493         fixity = infixl 7
494
495 primop   DoubleNegOp   "negateDouble#"  Monadic   Double# -> Double#
496
497 primop   Double2IntOp   "double2Int#"          GenPrimOp  Double# -> Int#
498    {Truncates a {\tt Double#} value to the nearest {\tt Int#}.
499     Results are undefined if the truncation if truncation yields
500     a value outside the range of {\tt Int#}.}
501
502 primop   Double2FloatOp   "double2Float#" GenPrimOp Double# -> Float#
503
504 primop   DoubleExpOp   "expDouble#"      Monadic
505    Double# -> Double#
506    with
507    code_size = { primOpCodeSizeForeignCall }
508
509 primop   DoubleLogOp   "logDouble#"      Monadic
510    Double# -> Double#
511    with
512    code_size = { primOpCodeSizeForeignCall }
513    can_fail = True
514
515 primop   DoubleSqrtOp   "sqrtDouble#"      Monadic
516    Double# -> Double#
517    with
518    code_size = { primOpCodeSizeForeignCall }
519
520 primop   DoubleSinOp   "sinDouble#"      Monadic
521    Double# -> Double#
522    with
523    code_size = { primOpCodeSizeForeignCall }
524
525 primop   DoubleCosOp   "cosDouble#"      Monadic
526    Double# -> Double#
527    with
528    code_size = { primOpCodeSizeForeignCall }
529
530 primop   DoubleTanOp   "tanDouble#"      Monadic
531    Double# -> Double#
532    with
533    code_size = { primOpCodeSizeForeignCall }
534
535 primop   DoubleAsinOp   "asinDouble#"      Monadic
536    Double# -> Double#
537    with
538    code_size = { primOpCodeSizeForeignCall }
539    can_fail = True
540
541 primop   DoubleAcosOp   "acosDouble#"      Monadic
542    Double# -> Double#
543    with
544    code_size = { primOpCodeSizeForeignCall }
545    can_fail = True
546
547 primop   DoubleAtanOp   "atanDouble#"      Monadic
548    Double# -> Double#
549    with
550    code_size = { primOpCodeSizeForeignCall }
551
552 primop   DoubleSinhOp   "sinhDouble#"      Monadic
553    Double# -> Double#
554    with
555    code_size = { primOpCodeSizeForeignCall }
556
557 primop   DoubleCoshOp   "coshDouble#"      Monadic
558    Double# -> Double#
559    with
560    code_size = { primOpCodeSizeForeignCall }
561
562 primop   DoubleTanhOp   "tanhDouble#"      Monadic
563    Double# -> Double#
564    with
565    code_size = { primOpCodeSizeForeignCall }
566
567 primop   DoublePowerOp   "**##" Dyadic
568    Double# -> Double# -> Double#
569    {Exponentiation.}
570    with
571    code_size = { primOpCodeSizeForeignCall }
572
573 primop   DoubleDecode_2IntOp   "decodeDouble_2Int#" GenPrimOp
574    Double# -> (# Int#, Word#, Word#, Int# #)
575    {Convert to integer.
576     First component of the result is -1 or 1, indicating the sign of the
577     mantissa. The next two are the high and low 32 bits of the mantissa
578     respectively, and the last is the exponent.}
579    with out_of_line = True
580
581 ------------------------------------------------------------------------
582 section "Float#"
583         {Operations on single-precision (32-bit) floating-point numbers.}
584 ------------------------------------------------------------------------
585
586 primtype Float#
587
588 primop   FloatGtOp  "gtFloat#"   Compare   Float# -> Float# -> Int#
589 primop   FloatGeOp  "geFloat#"   Compare   Float# -> Float# -> Int#
590
591 primop   FloatEqOp  "eqFloat#"   Compare
592    Float# -> Float# -> Int#
593    with commutable = True
594
595 primop   FloatNeOp  "neFloat#"   Compare
596    Float# -> Float# -> Int#
597    with commutable = True
598
599 primop   FloatLtOp  "ltFloat#"   Compare   Float# -> Float# -> Int#
600 primop   FloatLeOp  "leFloat#"   Compare   Float# -> Float# -> Int#
601
602 primop   FloatAddOp   "plusFloat#"      Dyadic
603    Float# -> Float# -> Float#
604    with commutable = True
605
606 primop   FloatSubOp   "minusFloat#"      Dyadic      Float# -> Float# -> Float#
607
608 primop   FloatMulOp   "timesFloat#"      Dyadic
609    Float# -> Float# -> Float#
610    with commutable = True
611
612 primop   FloatDivOp   "divideFloat#"      Dyadic
613    Float# -> Float# -> Float#
614    with can_fail = True
615
616 primop   FloatNegOp   "negateFloat#"      Monadic    Float# -> Float#
617
618 primop   Float2IntOp   "float2Int#"      GenPrimOp  Float# -> Int#
619    {Truncates a {\tt Float#} value to the nearest {\tt Int#}.
620     Results are undefined if the truncation if truncation yields
621     a value outside the range of {\tt Int#}.}
622
623 primop   FloatExpOp   "expFloat#"      Monadic
624    Float# -> Float#
625    with
626    code_size = { primOpCodeSizeForeignCall }
627
628 primop   FloatLogOp   "logFloat#"      Monadic
629    Float# -> Float#
630    with
631    code_size = { primOpCodeSizeForeignCall }
632    can_fail = True
633
634 primop   FloatSqrtOp   "sqrtFloat#"      Monadic
635    Float# -> Float#
636    with
637    code_size = { primOpCodeSizeForeignCall }
638
639 primop   FloatSinOp   "sinFloat#"      Monadic
640    Float# -> Float#
641    with
642    code_size = { primOpCodeSizeForeignCall }
643
644 primop   FloatCosOp   "cosFloat#"      Monadic
645    Float# -> Float#
646    with
647    code_size = { primOpCodeSizeForeignCall }
648
649 primop   FloatTanOp   "tanFloat#"      Monadic
650    Float# -> Float#
651    with
652    code_size = { primOpCodeSizeForeignCall }
653
654 primop   FloatAsinOp   "asinFloat#"      Monadic
655    Float# -> Float#
656    with
657    code_size = { primOpCodeSizeForeignCall }
658    can_fail = True
659
660 primop   FloatAcosOp   "acosFloat#"      Monadic
661    Float# -> Float#
662    with
663    code_size = { primOpCodeSizeForeignCall }
664    can_fail = True
665
666 primop   FloatAtanOp   "atanFloat#"      Monadic
667    Float# -> Float#
668    with
669    code_size = { primOpCodeSizeForeignCall }
670
671 primop   FloatSinhOp   "sinhFloat#"      Monadic
672    Float# -> Float#
673    with
674    code_size = { primOpCodeSizeForeignCall }
675
676 primop   FloatCoshOp   "coshFloat#"      Monadic
677    Float# -> Float#
678    with
679    code_size = { primOpCodeSizeForeignCall }
680
681 primop   FloatTanhOp   "tanhFloat#"      Monadic
682    Float# -> Float#
683    with
684    code_size = { primOpCodeSizeForeignCall }
685
686 primop   FloatPowerOp   "powerFloat#"      Dyadic
687    Float# -> Float# -> Float#
688    with
689    code_size = { primOpCodeSizeForeignCall }
690
691 primop   Float2DoubleOp   "float2Double#" GenPrimOp  Float# -> Double#
692
693 primop   FloatDecode_IntOp   "decodeFloat_Int#" GenPrimOp
694    Float# -> (# Int#, Int# #)
695    {Convert to integers.
696     First {\tt Int\#} in result is the mantissa; second is the exponent.}
697    with out_of_line = True
698
699 ------------------------------------------------------------------------
700 section "Arrays"
701         {Operations on {\tt Array\#}.}
702 ------------------------------------------------------------------------
703
704 primtype Array# a
705
706 primtype MutableArray# s a
707
708 primop  NewArrayOp "newArray#" GenPrimOp
709    Int# -> a -> State# s -> (# State# s, MutableArray# s a #)
710    {Create a new mutable array with the specified number of elements,
711     in the specified state thread,
712     with each element containing the specified initial value.}
713    with
714    out_of_line = True
715    has_side_effects = True
716
717 primop  SameMutableArrayOp "sameMutableArray#" GenPrimOp
718    MutableArray# s a -> MutableArray# s a -> Int#
719
720 primop  ReadArrayOp "readArray#" GenPrimOp
721    MutableArray# s a -> Int# -> State# s -> (# State# s, a #)
722    {Read from specified index of mutable array. Result is not yet evaluated.}
723    with
724    has_side_effects = True
725    can_fail         = True
726
727 primop  WriteArrayOp "writeArray#" GenPrimOp
728    MutableArray# s a -> Int# -> a -> State# s -> State# s
729    {Write to specified index of mutable array.}
730    with
731    has_side_effects = True
732    can_fail         = True
733    code_size        = 2 -- card update too
734
735 primop  SizeofArrayOp "sizeofArray#" GenPrimOp
736    Array# a -> Int#
737    {Return the number of elements in the array.}
738
739 primop  SizeofMutableArrayOp "sizeofMutableArray#" GenPrimOp
740    MutableArray# s a -> Int#
741    {Return the number of elements in the array.}
742
743 primop  IndexArrayOp "indexArray#" GenPrimOp
744    Array# a -> Int# -> (# a #)
745    {Read from specified index of immutable array. Result is packaged into
746     an unboxed singleton; the result itself is not yet evaluated.}
747    with
748    can_fail         = True
749
750 primop  UnsafeFreezeArrayOp "unsafeFreezeArray#" GenPrimOp
751    MutableArray# s a -> State# s -> (# State# s, Array# a #)
752    {Make a mutable array immutable, without copying.}
753    with
754    has_side_effects = True
755
756 primop  UnsafeThawArrayOp  "unsafeThawArray#" GenPrimOp
757    Array# a -> State# s -> (# State# s, MutableArray# s a #)
758    {Make an immutable array mutable, without copying.}
759    with
760    out_of_line = True
761    has_side_effects = True
762
763 primop  CopyArrayOp "copyArray#" GenPrimOp
764   Array# a -> Int# -> MutableArray# s a -> Int# -> Int# -> State# s -> State# s
765   {Copy a range of the Array# to the specified region in the MutableArray#.
766    Both arrays must fully contain the specified ranges, but this is not checked.
767    The two arrays must not be the same array in different states, but this is not checked either.}
768   with
769   has_side_effects = True
770   can_fail         = True
771   code_size = { primOpCodeSizeForeignCall + 4 }
772
773 primop  CopyMutableArrayOp "copyMutableArray#" GenPrimOp
774   MutableArray# s a -> Int# -> MutableArray# s a -> Int# -> Int# -> State# s -> State# s
775   {Copy a range of the first MutableArray# to the specified region in the second MutableArray#.
776    Both arrays must fully contain the specified ranges, but this is not checked.}
777   with
778   has_side_effects = True
779   can_fail         = True
780   code_size = { primOpCodeSizeForeignCall + 4 }
781
782 primop  CloneArrayOp "cloneArray#" GenPrimOp
783   Array# a -> Int# -> Int# -> Array# a
784   {Return a newly allocated Array# with the specified subrange of the provided Array#.
785    The provided Array# should contain the full subrange specified by the two Int#s, but this is not checked.}
786   with
787   has_side_effects = True
788   code_size = { primOpCodeSizeForeignCall + 4 }
789
790 primop  CloneMutableArrayOp "cloneMutableArray#" GenPrimOp
791   MutableArray# s a -> Int# -> Int# -> State# s -> (# State# s, MutableArray# s a #)
792   {Return a newly allocated Array# with the specified subrange of the provided Array#.
793    The provided MutableArray# should contain the full subrange specified by the two Int#s, but this is not checked.}
794   with
795   has_side_effects = True
796   code_size = { primOpCodeSizeForeignCall + 4 }
797
798 primop  FreezeArrayOp "freezeArray#" GenPrimOp
799   MutableArray# s a -> Int# -> Int# -> State# s -> (# State# s, Array# a #)
800   {Return a newly allocated Array# with the specified subrange of the provided MutableArray#.
801    The provided MutableArray# should contain the full subrange specified by the two Int#s, but this is not checked.}
802   with
803   has_side_effects = True
804   code_size = { primOpCodeSizeForeignCall + 4 }
805
806 primop  ThawArrayOp "thawArray#" GenPrimOp
807   Array# a -> Int# -> Int# -> State# s -> (# State# s, MutableArray# s a #)
808   {Return a newly allocated Array# with the specified subrange of the provided MutableArray#.
809    The provided Array# should contain the full subrange specified by the two Int#s, but this is not checked.}
810   with
811   has_side_effects = True
812   code_size = { primOpCodeSizeForeignCall + 4 }
813
814 primop CasArrayOp  "casArray#" GenPrimOp
815    MutableArray# s a -> Int# -> a -> a -> State# s -> (# State# s, Int#, a #)
816    {Unsafe, machine-level atomic compare and swap on an element within an Array.}
817    with
818    out_of_line = True
819    has_side_effects = True
820
821
822 ------------------------------------------------------------------------
823 section "Byte Arrays"
824         {Operations on {\tt ByteArray\#}. A {\tt ByteArray\#} is a just a region of
825          raw memory in the garbage-collected heap, which is not
826          scanned for pointers. It carries its own size (in bytes).
827          There are
828          three sets of operations for accessing byte array contents:
829          index for reading from immutable byte arrays, and read/write
830          for mutable byte arrays.  Each set contains operations for a
831          range of useful primitive data types.  Each operation takes
832          an offset measured in terms of the size of the primitive type
833          being read or written.}
834
835 ------------------------------------------------------------------------
836
837 primtype ByteArray#
838
839 primtype MutableByteArray# s
840
841 primop  NewByteArrayOp_Char "newByteArray#" GenPrimOp
842    Int# -> State# s -> (# State# s, MutableByteArray# s #)
843    {Create a new mutable byte array of specified size (in bytes), in
844     the specified state thread.}
845    with out_of_line = True
846         has_side_effects = True
847
848 primop  NewPinnedByteArrayOp_Char "newPinnedByteArray#" GenPrimOp
849    Int# -> State# s -> (# State# s, MutableByteArray# s #)
850    {Create a mutable byte array that the GC guarantees not to move.}
851    with out_of_line = True
852         has_side_effects = True
853
854 primop  NewAlignedPinnedByteArrayOp_Char "newAlignedPinnedByteArray#" GenPrimOp
855    Int# -> Int# -> State# s -> (# State# s, MutableByteArray# s #)
856    {Create a mutable byte array, aligned by the specified amount, that the GC guarantees not to move.}
857    with out_of_line = True
858         has_side_effects = True
859
860 primop  ByteArrayContents_Char "byteArrayContents#" GenPrimOp
861    ByteArray# -> Addr#
862    {Intended for use with pinned arrays; otherwise very unsafe!}
863
864 primop  SameMutableByteArrayOp "sameMutableByteArray#" GenPrimOp
865    MutableByteArray# s -> MutableByteArray# s -> Int#
866
867 primop  UnsafeFreezeByteArrayOp "unsafeFreezeByteArray#" GenPrimOp
868    MutableByteArray# s -> State# s -> (# State# s, ByteArray# #)
869    {Make a mutable byte array immutable, without copying.}
870    with
871    has_side_effects = True
872
873 primop  SizeofByteArrayOp "sizeofByteArray#" GenPrimOp
874    ByteArray# -> Int#
875    {Return the size of the array in bytes.}
876
877 primop  SizeofMutableByteArrayOp "sizeofMutableByteArray#" GenPrimOp
878    MutableByteArray# s -> Int#
879    {Return the size of the array in bytes.}
880
881 primop IndexByteArrayOp_Char "indexCharArray#" GenPrimOp
882    ByteArray# -> Int# -> Char#
883    {Read 8-bit character; offset in bytes.}
884    with can_fail = True
885
886 primop IndexByteArrayOp_WideChar "indexWideCharArray#" GenPrimOp
887    ByteArray# -> Int# -> Char#
888    {Read 31-bit character; offset in 4-byte words.}
889    with can_fail = True
890
891 primop IndexByteArrayOp_Int "indexIntArray#" GenPrimOp
892    ByteArray# -> Int# -> Int#
893    with can_fail = True
894
895 primop IndexByteArrayOp_Word "indexWordArray#" GenPrimOp
896    ByteArray# -> Int# -> Word#
897    with can_fail = True
898
899 primop IndexByteArrayOp_Addr "indexAddrArray#" GenPrimOp
900    ByteArray# -> Int# -> Addr#
901    with can_fail = True
902
903 primop IndexByteArrayOp_Float "indexFloatArray#" GenPrimOp
904    ByteArray# -> Int# -> Float#
905    with can_fail = True
906
907 primop IndexByteArrayOp_Double "indexDoubleArray#" GenPrimOp
908    ByteArray# -> Int# -> Double#
909    with can_fail = True
910
911 primop IndexByteArrayOp_StablePtr "indexStablePtrArray#" GenPrimOp
912    ByteArray# -> Int# -> StablePtr# a
913    with can_fail = True
914
915 primop IndexByteArrayOp_Int8 "indexInt8Array#" GenPrimOp
916    ByteArray# -> Int# -> Int#
917    with can_fail = True
918
919 primop IndexByteArrayOp_Int16 "indexInt16Array#" GenPrimOp
920    ByteArray# -> Int# -> Int#
921    with can_fail = True
922
923 primop IndexByteArrayOp_Int32 "indexInt32Array#" GenPrimOp
924    ByteArray# -> Int# -> INT32
925    with can_fail = True
926
927 primop IndexByteArrayOp_Int64 "indexInt64Array#" GenPrimOp
928    ByteArray# -> Int# -> INT64
929    with can_fail = True
930
931 primop IndexByteArrayOp_Word8 "indexWord8Array#" GenPrimOp
932    ByteArray# -> Int# -> Word#
933    with can_fail = True
934
935 primop IndexByteArrayOp_Word16 "indexWord16Array#" GenPrimOp
936    ByteArray# -> Int# -> Word#
937    with can_fail = True
938
939 primop IndexByteArrayOp_Word32 "indexWord32Array#" GenPrimOp
940    ByteArray# -> Int# -> WORD32
941    with can_fail = True
942
943 primop IndexByteArrayOp_Word64 "indexWord64Array#" GenPrimOp
944    ByteArray# -> Int# -> WORD64
945    with can_fail = True
946
947 primop  ReadByteArrayOp_Char "readCharArray#" GenPrimOp
948    MutableByteArray# s -> Int# -> State# s -> (# State# s, Char# #)
949    {Read 8-bit character; offset in bytes.}
950    with has_side_effects = True
951         can_fail = True
952
953 primop  ReadByteArrayOp_WideChar "readWideCharArray#" GenPrimOp
954    MutableByteArray# s -> Int# -> State# s -> (# State# s, Char# #)
955    {Read 31-bit character; offset in 4-byte words.}
956    with has_side_effects = True
957         can_fail = True
958
959 primop  ReadByteArrayOp_Int "readIntArray#" GenPrimOp
960    MutableByteArray# s -> Int# -> State# s -> (# State# s, Int# #)
961    with has_side_effects = True
962         can_fail = True
963
964 primop  ReadByteArrayOp_Word "readWordArray#" GenPrimOp
965    MutableByteArray# s -> Int# -> State# s -> (# State# s, Word# #)
966    with has_side_effects = True
967         can_fail = True
968
969 primop  ReadByteArrayOp_Addr "readAddrArray#" GenPrimOp
970    MutableByteArray# s -> Int# -> State# s -> (# State# s, Addr# #)
971    with has_side_effects = True
972         can_fail = True
973
974 primop  ReadByteArrayOp_Float "readFloatArray#" GenPrimOp
975    MutableByteArray# s -> Int# -> State# s -> (# State# s, Float# #)
976    with has_side_effects = True
977         can_fail = True
978
979 primop  ReadByteArrayOp_Double "readDoubleArray#" GenPrimOp
980    MutableByteArray# s -> Int# -> State# s -> (# State# s, Double# #)
981    with has_side_effects = True
982         can_fail = True
983
984 primop  ReadByteArrayOp_StablePtr "readStablePtrArray#" GenPrimOp
985    MutableByteArray# s -> Int# -> State# s -> (# State# s, StablePtr# a #)
986    with has_side_effects = True
987         can_fail = True
988
989 primop  ReadByteArrayOp_Int8 "readInt8Array#" GenPrimOp
990    MutableByteArray# s -> Int# -> State# s -> (# State# s, Int# #)
991    with has_side_effects = True
992         can_fail = True
993
994 primop  ReadByteArrayOp_Int16 "readInt16Array#" GenPrimOp
995    MutableByteArray# s -> Int# -> State# s -> (# State# s, Int# #)
996    with has_side_effects = True
997         can_fail = True
998
999 primop  ReadByteArrayOp_Int32 "readInt32Array#" GenPrimOp
1000    MutableByteArray# s -> Int# -> State# s -> (# State# s, INT32 #)
1001    with has_side_effects = True
1002         can_fail = True
1003
1004 primop  ReadByteArrayOp_Int64 "readInt64Array#" GenPrimOp
1005    MutableByteArray# s -> Int# -> State# s -> (# State# s, INT64 #)
1006    with has_side_effects = True
1007         can_fail = True
1008
1009 primop  ReadByteArrayOp_Word8 "readWord8Array#" GenPrimOp
1010    MutableByteArray# s -> Int# -> State# s -> (# State# s, Word# #)
1011    with has_side_effects = True
1012         can_fail = True
1013
1014 primop  ReadByteArrayOp_Word16 "readWord16Array#" GenPrimOp
1015    MutableByteArray# s -> Int# -> State# s -> (# State# s, Word# #)
1016    with has_side_effects = True
1017         can_fail = True
1018
1019 primop  ReadByteArrayOp_Word32 "readWord32Array#" GenPrimOp
1020    MutableByteArray# s -> Int# -> State# s -> (# State# s, WORD32 #)
1021    with has_side_effects = True
1022         can_fail = True
1023
1024 primop  ReadByteArrayOp_Word64 "readWord64Array#" GenPrimOp
1025    MutableByteArray# s -> Int# -> State# s -> (# State# s, WORD64 #)
1026    with has_side_effects = True
1027         can_fail = True
1028
1029 primop  WriteByteArrayOp_Char "writeCharArray#" GenPrimOp
1030    MutableByteArray# s -> Int# -> Char# -> State# s -> State# s
1031    {Write 8-bit character; offset in bytes.}
1032    with has_side_effects = True
1033         can_fail = True
1034
1035 primop  WriteByteArrayOp_WideChar "writeWideCharArray#" GenPrimOp
1036    MutableByteArray# s -> Int# -> Char# -> State# s -> State# s
1037    {Write 31-bit character; offset in 4-byte words.}
1038    with has_side_effects = True
1039         can_fail = True
1040
1041 primop  WriteByteArrayOp_Int "writeIntArray#" GenPrimOp
1042    MutableByteArray# s -> Int# -> Int# -> State# s -> State# s
1043    with has_side_effects = True
1044         can_fail = True
1045
1046 primop  WriteByteArrayOp_Word "writeWordArray#" GenPrimOp
1047    MutableByteArray# s -> Int# -> Word# -> State# s -> State# s
1048    with has_side_effects = True
1049         can_fail = True
1050
1051 primop  WriteByteArrayOp_Addr "writeAddrArray#" GenPrimOp
1052    MutableByteArray# s -> Int# -> Addr# -> State# s -> State# s
1053    with has_side_effects = True
1054         can_fail = True
1055
1056 primop  WriteByteArrayOp_Float "writeFloatArray#" GenPrimOp
1057    MutableByteArray# s -> Int# -> Float# -> State# s -> State# s
1058    with has_side_effects = True
1059         can_fail = True
1060
1061 primop  WriteByteArrayOp_Double "writeDoubleArray#" GenPrimOp
1062    MutableByteArray# s -> Int# -> Double# -> State# s -> State# s
1063    with has_side_effects = True
1064         can_fail = True
1065
1066 primop  WriteByteArrayOp_StablePtr "writeStablePtrArray#" GenPrimOp
1067    MutableByteArray# s -> Int# -> StablePtr# a -> State# s -> State# s
1068    with has_side_effects = True
1069         can_fail = True
1070
1071 primop  WriteByteArrayOp_Int8 "writeInt8Array#" GenPrimOp
1072    MutableByteArray# s -> Int# -> Int# -> State# s -> State# s
1073    with has_side_effects = True
1074         can_fail = True
1075
1076 primop  WriteByteArrayOp_Int16 "writeInt16Array#" GenPrimOp
1077    MutableByteArray# s -> Int# -> Int# -> State# s -> State# s
1078    with has_side_effects = True
1079         can_fail = True
1080
1081 primop  WriteByteArrayOp_Int32 "writeInt32Array#" GenPrimOp
1082    MutableByteArray# s -> Int# -> INT32 -> State# s -> State# s
1083    with has_side_effects = True
1084         can_fail = True
1085
1086 primop  WriteByteArrayOp_Int64 "writeInt64Array#" GenPrimOp
1087    MutableByteArray# s -> Int# -> INT64 -> State# s -> State# s
1088    with can_fail = True
1089         has_side_effects = True
1090
1091 primop  WriteByteArrayOp_Word8 "writeWord8Array#" GenPrimOp
1092    MutableByteArray# s -> Int# -> Word# -> State# s -> State# s
1093    with has_side_effects = True
1094         can_fail = True
1095
1096 primop  WriteByteArrayOp_Word16 "writeWord16Array#" GenPrimOp
1097    MutableByteArray# s -> Int# -> Word# -> State# s -> State# s
1098    with has_side_effects = True
1099         can_fail = True
1100
1101 primop  WriteByteArrayOp_Word32 "writeWord32Array#" GenPrimOp
1102    MutableByteArray# s -> Int# -> WORD32 -> State# s -> State# s
1103    with has_side_effects = True
1104         can_fail = True
1105
1106 primop  WriteByteArrayOp_Word64 "writeWord64Array#" GenPrimOp
1107    MutableByteArray# s -> Int# -> WORD64 -> State# s -> State# s
1108    with has_side_effects = True
1109         can_fail = True
1110
1111 primop  CopyByteArrayOp "copyByteArray#" GenPrimOp
1112   ByteArray# -> Int# -> MutableByteArray# s -> Int# -> Int# -> State# s -> State# s
1113   {Copy a range of the ByteArray# to the specified region in the MutableByteArray#.
1114    Both arrays must fully contain the specified ranges, but this is not checked.
1115    The two arrays must not be the same array in different states, but this is not checked either.}
1116   with
1117   has_side_effects = True
1118   code_size = { primOpCodeSizeForeignCall + 4}
1119   can_fail = True
1120
1121 primop  CopyMutableByteArrayOp "copyMutableByteArray#" GenPrimOp
1122   MutableByteArray# s -> Int# -> MutableByteArray# s -> Int# -> Int# -> State# s -> State# s
1123   {Copy a range of the first MutableByteArray# to the specified region in the second MutableByteArray#.
1124    Both arrays must fully contain the specified ranges, but this is not checked.}
1125   with
1126   has_side_effects = True
1127   code_size = { primOpCodeSizeForeignCall + 4 }
1128   can_fail = True
1129
1130 primop  CopyByteArrayToAddrOp "copyByteArrayToAddr#" GenPrimOp
1131   ByteArray# -> Int# -> Addr# -> Int# -> State# s -> State# s
1132   {Copy a range of the ByteArray# to the memory range starting at the Addr#.
1133    The ByteArray# and the memory region at Addr# must fully contain the
1134    specified ranges, but this is not checked. The Addr# must not point into the
1135    ByteArray# (e.g. if the ByteArray# were pinned), but this is not checked
1136    either.}
1137   with
1138   has_side_effects = True
1139   code_size = { primOpCodeSizeForeignCall + 4}
1140   can_fail = True
1141
1142 primop  CopyMutableByteArrayToAddrOp "copyMutableByteArrayToAddr#" GenPrimOp
1143   MutableByteArray# s -> Int# -> Addr# -> Int# -> State# s -> State# s
1144   {Copy a range of the MutableByteArray# to the memory range starting at the
1145    Addr#. The MutableByteArray# and the memory region at Addr# must fully
1146    contain the specified ranges, but this is not checked. The Addr# must not
1147    point into the MutableByteArray# (e.g. if the MutableByteArray# were
1148    pinned), but this is not checked either.}
1149   with
1150   has_side_effects = True
1151   code_size = { primOpCodeSizeForeignCall + 4}
1152   can_fail = True
1153
1154 primop  CopyAddrToByteArrayOp "copyAddrToByteArray#" GenPrimOp
1155   Addr# -> MutableByteArray# s -> Int# -> Int# -> State# s -> State# s
1156   {Copy a memory range starting at the Addr# to the specified range in the
1157    MutableByteArray#. The memory region at Addr# and the ByteArray# must fully
1158    contain the specified ranges, but this is not checked. The Addr# must not
1159    point into the MutableByteArray# (e.g. if the MutableByteArray# were pinned),
1160    but this is not checked either.}
1161   with
1162   has_side_effects = True
1163   code_size = { primOpCodeSizeForeignCall + 4}
1164   can_fail = True
1165
1166 primop  SetByteArrayOp "setByteArray#" GenPrimOp
1167   MutableByteArray# s -> Int# -> Int# -> Int# -> State# s -> State# s
1168   {Set the range of the MutableByteArray# to the specified character.}
1169   with
1170   has_side_effects = True
1171   code_size = { primOpCodeSizeForeignCall + 4 }
1172   can_fail = True
1173
1174 primop CasByteArrayOp_Int "casIntArray#" GenPrimOp
1175    MutableByteArray# s -> Int# -> Int# -> Int# -> State# s -> (# State# s, Int# #)
1176    {Machine-level atomic compare and swap on a word within a ByteArray.}
1177    with
1178    out_of_line = True
1179    has_side_effects = True
1180
1181 primop FetchAddByteArrayOp_Int "fetchAddIntArray#" GenPrimOp
1182    MutableByteArray# s -> Int# -> Int# -> State# s -> (# State# s, Int# #)
1183    {Machine-level word-sized fetch-and-add within a ByteArray.}
1184    with
1185    out_of_line = True
1186    has_side_effects = True
1187
1188
1189 ------------------------------------------------------------------------
1190 section "Arrays of arrays"
1191         {Operations on {\tt ArrayArray\#}. An {\tt ArrayArray\#} contains references to {\em unpointed}
1192          arrays, such as {\tt ByteArray\#s}. Hence, it is not parameterised by the element types,
1193          just like a {\tt ByteArray\#}, but it needs to be scanned during GC, just like an {\tt Array#}.
1194          We represent an {\tt ArrayArray\#} exactly as a {\tt Array\#}, but provide element-type-specific
1195          indexing, reading, and writing.}
1196 ------------------------------------------------------------------------
1197
1198 primtype ArrayArray#
1199
1200 primtype MutableArrayArray# s
1201
1202 primop  NewArrayArrayOp "newArrayArray#" GenPrimOp
1203    Int# -> State# s -> (# State# s, MutableArrayArray# s #)
1204    {Create a new mutable array of arrays with the specified number of elements,
1205     in the specified state thread, with each element recursively referring to the
1206     newly created array.}
1207    with
1208    out_of_line = True
1209    has_side_effects = True
1210
1211 primop  SameMutableArrayArrayOp "sameMutableArrayArray#" GenPrimOp
1212    MutableArrayArray# s -> MutableArrayArray# s -> Int#
1213
1214 primop  UnsafeFreezeArrayArrayOp "unsafeFreezeArrayArray#" GenPrimOp
1215    MutableArrayArray# s -> State# s -> (# State# s, ArrayArray# #)
1216    {Make a mutable array of arrays immutable, without copying.}
1217    with
1218    has_side_effects = True
1219
1220 primop  SizeofArrayArrayOp "sizeofArrayArray#" GenPrimOp
1221    ArrayArray# -> Int#
1222    {Return the number of elements in the array.}
1223
1224 primop  SizeofMutableArrayArrayOp "sizeofMutableArrayArray#" GenPrimOp
1225    MutableArrayArray# s -> Int#
1226    {Return the number of elements in the array.}
1227
1228 primop IndexArrayArrayOp_ByteArray "indexByteArrayArray#" GenPrimOp
1229    ArrayArray# -> Int# -> ByteArray#
1230    with can_fail = True
1231
1232 primop IndexArrayArrayOp_ArrayArray "indexArrayArrayArray#" GenPrimOp
1233    ArrayArray# -> Int# -> ArrayArray#
1234    with can_fail = True
1235
1236 primop  ReadArrayArrayOp_ByteArray "readByteArrayArray#" GenPrimOp
1237    MutableArrayArray# s -> Int# -> State# s -> (# State# s, ByteArray# #)
1238    with has_side_effects = True
1239         can_fail = True
1240
1241 primop  ReadArrayArrayOp_MutableByteArray "readMutableByteArrayArray#" GenPrimOp
1242    MutableArrayArray# s -> Int# -> State# s -> (# State# s, MutableByteArray# s #)
1243    with has_side_effects = True
1244         can_fail = True
1245
1246 primop  ReadArrayArrayOp_ArrayArray "readArrayArrayArray#" GenPrimOp
1247    MutableArrayArray# s -> Int# -> State# s -> (# State# s, ArrayArray# #)
1248    with has_side_effects = True
1249         can_fail = True
1250
1251 primop  ReadArrayArrayOp_MutableArrayArray "readMutableArrayArrayArray#" GenPrimOp
1252    MutableArrayArray# s -> Int# -> State# s -> (# State# s, MutableArrayArray# s #)
1253    with has_side_effects = True
1254         can_fail = True
1255
1256 primop  WriteArrayArrayOp_ByteArray "writeByteArrayArray#" GenPrimOp
1257    MutableArrayArray# s -> Int# -> ByteArray# -> State# s -> State# s
1258    with has_side_effects = True
1259         can_fail = True
1260
1261 primop  WriteArrayArrayOp_MutableByteArray "writeMutableByteArrayArray#" GenPrimOp
1262    MutableArrayArray# s -> Int# -> MutableByteArray# s -> State# s -> State# s
1263    with has_side_effects = True
1264         can_fail = True
1265
1266 primop  WriteArrayArrayOp_ArrayArray "writeArrayArrayArray#" GenPrimOp
1267    MutableArrayArray# s -> Int# -> ArrayArray# -> State# s -> State# s
1268    with has_side_effects = True
1269         can_fail = True
1270
1271 primop  WriteArrayArrayOp_MutableArrayArray "writeMutableArrayArrayArray#" GenPrimOp
1272    MutableArrayArray# s -> Int# -> MutableArrayArray# s -> State# s -> State# s
1273    with has_side_effects = True
1274         can_fail = True
1275
1276 primop  CopyArrayArrayOp "copyArrayArray#" GenPrimOp
1277   ArrayArray# -> Int# -> MutableArrayArray# s -> Int# -> Int# -> State# s -> State# s
1278   {Copy a range of the ArrayArray# to the specified region in the MutableArrayArray#.
1279    Both arrays must fully contain the specified ranges, but this is not checked.
1280    The two arrays must not be the same array in different states, but this is not checked either.}
1281   with
1282   has_side_effects = True
1283   can_fail = True
1284   code_size = { primOpCodeSizeForeignCall }
1285
1286 primop  CopyMutableArrayArrayOp "copyMutableArrayArray#" GenPrimOp
1287   MutableArrayArray# s -> Int# -> MutableArrayArray# s -> Int# -> Int# -> State# s -> State# s
1288   {Copy a range of the first MutableArrayArray# to the specified region in the second
1289    MutableArrayArray#.
1290    Both arrays must fully contain the specified ranges, but this is not checked.}
1291   with
1292   has_side_effects = True
1293   code_size = { primOpCodeSizeForeignCall }
1294   can_fail = True
1295
1296 ------------------------------------------------------------------------
1297 section "Addr#"
1298 ------------------------------------------------------------------------
1299
1300 primtype Addr#
1301         { An arbitrary machine address assumed to point outside
1302          the garbage-collected heap. }
1303
1304 pseudoop "nullAddr#" Addr#
1305         { The null address. }
1306
1307 primop   AddrAddOp "plusAddr#" GenPrimOp Addr# -> Int# -> Addr#
1308 primop   AddrSubOp "minusAddr#" GenPrimOp Addr# -> Addr# -> Int#
1309          {Result is meaningless if two {\tt Addr\#}s are so far apart that their
1310          difference doesn't fit in an {\tt Int\#}.}
1311 primop   AddrRemOp "remAddr#" GenPrimOp Addr# -> Int# -> Int#
1312          {Return the remainder when the {\tt Addr\#} arg, treated like an {\tt Int\#},
1313           is divided by the {\tt Int\#} arg.}
1314 #if (WORD_SIZE_IN_BITS == 32 || WORD_SIZE_IN_BITS == 64)
1315 primop   Addr2IntOp  "addr2Int#"     GenPrimOp   Addr# -> Int#
1316         {Coerce directly from address to int. Strongly deprecated.}
1317    with code_size = 0
1318 primop   Int2AddrOp   "int2Addr#"    GenPrimOp  Int# -> Addr#
1319         {Coerce directly from int to address. Strongly deprecated.}
1320    with code_size = 0
1321 #endif
1322
1323 primop   AddrGtOp  "gtAddr#"   Compare   Addr# -> Addr# -> Int#
1324 primop   AddrGeOp  "geAddr#"   Compare   Addr# -> Addr# -> Int#
1325 primop   AddrEqOp  "eqAddr#"   Compare   Addr# -> Addr# -> Int#
1326 primop   AddrNeOp  "neAddr#"   Compare   Addr# -> Addr# -> Int#
1327 primop   AddrLtOp  "ltAddr#"   Compare   Addr# -> Addr# -> Int#
1328 primop   AddrLeOp  "leAddr#"   Compare   Addr# -> Addr# -> Int#
1329
1330 primop IndexOffAddrOp_Char "indexCharOffAddr#" GenPrimOp
1331    Addr# -> Int# -> Char#
1332    {Reads 8-bit character; offset in bytes.}
1333    with can_fail = True
1334
1335 primop IndexOffAddrOp_WideChar "indexWideCharOffAddr#" GenPrimOp
1336    Addr# -> Int# -> Char#
1337    {Reads 31-bit character; offset in 4-byte words.}
1338    with can_fail = True
1339
1340 primop IndexOffAddrOp_Int "indexIntOffAddr#" GenPrimOp
1341    Addr# -> Int# -> Int#
1342    with can_fail = True
1343
1344 primop IndexOffAddrOp_Word "indexWordOffAddr#" GenPrimOp
1345    Addr# -> Int# -> Word#
1346    with can_fail = True
1347
1348 primop IndexOffAddrOp_Addr "indexAddrOffAddr#" GenPrimOp
1349    Addr# -> Int# -> Addr#
1350    with can_fail = True
1351
1352 primop IndexOffAddrOp_Float "indexFloatOffAddr#" GenPrimOp
1353    Addr# -> Int# -> Float#
1354    with can_fail = True
1355
1356 primop IndexOffAddrOp_Double "indexDoubleOffAddr#" GenPrimOp
1357    Addr# -> Int# -> Double#
1358    with can_fail = True
1359
1360 primop IndexOffAddrOp_StablePtr "indexStablePtrOffAddr#" GenPrimOp
1361    Addr# -> Int# -> StablePtr# a
1362    with can_fail = True
1363
1364 primop IndexOffAddrOp_Int8 "indexInt8OffAddr#" GenPrimOp
1365    Addr# -> Int# -> Int#
1366    with can_fail = True
1367
1368 primop IndexOffAddrOp_Int16 "indexInt16OffAddr#" GenPrimOp
1369    Addr# -> Int# -> Int#
1370    with can_fail = True
1371
1372 primop IndexOffAddrOp_Int32 "indexInt32OffAddr#" GenPrimOp
1373    Addr# -> Int# -> INT32
1374    with can_fail = True
1375
1376 primop IndexOffAddrOp_Int64 "indexInt64OffAddr#" GenPrimOp
1377    Addr# -> Int# -> INT64
1378    with can_fail = True
1379
1380 primop IndexOffAddrOp_Word8 "indexWord8OffAddr#" GenPrimOp
1381    Addr# -> Int# -> Word#
1382    with can_fail = True
1383
1384 primop IndexOffAddrOp_Word16 "indexWord16OffAddr#" GenPrimOp
1385    Addr# -> Int# -> Word#
1386    with can_fail = True
1387
1388 primop IndexOffAddrOp_Word32 "indexWord32OffAddr#" GenPrimOp
1389    Addr# -> Int# -> WORD32
1390    with can_fail = True
1391
1392 primop IndexOffAddrOp_Word64 "indexWord64OffAddr#" GenPrimOp
1393    Addr# -> Int# -> WORD64
1394    with can_fail = True
1395
1396 primop ReadOffAddrOp_Char "readCharOffAddr#" GenPrimOp
1397    Addr# -> Int# -> State# s -> (# State# s, Char# #)
1398    {Reads 8-bit character; offset in bytes.}
1399    with has_side_effects = True
1400         can_fail         = True
1401
1402 primop ReadOffAddrOp_WideChar "readWideCharOffAddr#" GenPrimOp
1403    Addr# -> Int# -> State# s -> (# State# s, Char# #)
1404    {Reads 31-bit character; offset in 4-byte words.}
1405    with has_side_effects = True
1406         can_fail         = True
1407
1408 primop ReadOffAddrOp_Int "readIntOffAddr#" GenPrimOp
1409    Addr# -> Int# -> State# s -> (# State# s, Int# #)
1410    with has_side_effects = True
1411         can_fail         = True
1412
1413 primop ReadOffAddrOp_Word "readWordOffAddr#" GenPrimOp
1414    Addr# -> Int# -> State# s -> (# State# s, Word# #)
1415    with has_side_effects = True
1416         can_fail         = True
1417
1418 primop ReadOffAddrOp_Addr "readAddrOffAddr#" GenPrimOp
1419    Addr# -> Int# -> State# s -> (# State# s, Addr# #)
1420    with has_side_effects = True
1421         can_fail         = True
1422
1423 primop ReadOffAddrOp_Float "readFloatOffAddr#" GenPrimOp
1424    Addr# -> Int# -> State# s -> (# State# s, Float# #)
1425    with has_side_effects = True
1426         can_fail         = True
1427
1428 primop ReadOffAddrOp_Double "readDoubleOffAddr#" GenPrimOp
1429    Addr# -> Int# -> State# s -> (# State# s, Double# #)
1430    with has_side_effects = True
1431         can_fail         = True
1432
1433 primop ReadOffAddrOp_StablePtr "readStablePtrOffAddr#" GenPrimOp
1434    Addr# -> Int# -> State# s -> (# State# s, StablePtr# a #)
1435    with has_side_effects = True
1436         can_fail         = True
1437
1438 primop ReadOffAddrOp_Int8 "readInt8OffAddr#" GenPrimOp
1439    Addr# -> Int# -> State# s -> (# State# s, Int# #)
1440    with has_side_effects = True
1441         can_fail         = True
1442
1443 primop ReadOffAddrOp_Int16 "readInt16OffAddr#" GenPrimOp
1444    Addr# -> Int# -> State# s -> (# State# s, Int# #)
1445    with has_side_effects = True
1446         can_fail         = True
1447
1448 primop ReadOffAddrOp_Int32 "readInt32OffAddr#" GenPrimOp
1449    Addr# -> Int# -> State# s -> (# State# s, INT32 #)
1450    with has_side_effects = True
1451         can_fail         = True
1452
1453 primop ReadOffAddrOp_Int64 "readInt64OffAddr#" GenPrimOp
1454    Addr# -> Int# -> State# s -> (# State# s, INT64 #)
1455    with has_side_effects = True
1456         can_fail         = True
1457
1458 primop ReadOffAddrOp_Word8 "readWord8OffAddr#" GenPrimOp
1459    Addr# -> Int# -> State# s -> (# State# s, Word# #)
1460    with has_side_effects = True
1461         can_fail         = True
1462
1463 primop ReadOffAddrOp_Word16 "readWord16OffAddr#" GenPrimOp
1464    Addr# -> Int# -> State# s -> (# State# s, Word# #)
1465    with has_side_effects = True
1466         can_fail         = True
1467
1468 primop ReadOffAddrOp_Word32 "readWord32OffAddr#" GenPrimOp
1469    Addr# -> Int# -> State# s -> (# State# s, WORD32 #)
1470    with has_side_effects = True
1471         can_fail         = True
1472
1473 primop ReadOffAddrOp_Word64 "readWord64OffAddr#" GenPrimOp
1474    Addr# -> Int# -> State# s -> (# State# s, WORD64 #)
1475    with has_side_effects = True
1476         can_fail         = True
1477
1478 primop  WriteOffAddrOp_Char "writeCharOffAddr#" GenPrimOp
1479    Addr# -> Int# -> Char# -> State# s -> State# s
1480    with has_side_effects = True
1481         can_fail         = True
1482
1483 primop  WriteOffAddrOp_WideChar "writeWideCharOffAddr#" GenPrimOp
1484    Addr# -> Int# -> Char# -> State# s -> State# s
1485    with has_side_effects = True
1486         can_fail         = True
1487
1488 primop  WriteOffAddrOp_Int "writeIntOffAddr#" GenPrimOp
1489    Addr# -> Int# -> Int# -> State# s -> State# s
1490    with has_side_effects = True
1491         can_fail         = True
1492
1493 primop  WriteOffAddrOp_Word "writeWordOffAddr#" GenPrimOp
1494    Addr# -> Int# -> Word# -> State# s -> State# s
1495    with has_side_effects = True
1496         can_fail         = True
1497
1498 primop  WriteOffAddrOp_Addr "writeAddrOffAddr#" GenPrimOp
1499    Addr# -> Int# -> Addr# -> State# s -> State# s
1500    with has_side_effects = True
1501         can_fail         = True
1502
1503 primop  WriteOffAddrOp_Float "writeFloatOffAddr#" GenPrimOp
1504    Addr# -> Int# -> Float# -> State# s -> State# s
1505    with has_side_effects = True
1506         can_fail         = True
1507
1508 primop  WriteOffAddrOp_Double "writeDoubleOffAddr#" GenPrimOp
1509    Addr# -> Int# -> Double# -> State# s -> State# s
1510    with has_side_effects = True
1511         can_fail         = True
1512
1513 primop  WriteOffAddrOp_StablePtr "writeStablePtrOffAddr#" GenPrimOp
1514    Addr# -> Int# -> StablePtr# a -> State# s -> State# s
1515    with has_side_effects = True
1516         can_fail         = True
1517
1518 primop  WriteOffAddrOp_Int8 "writeInt8OffAddr#" GenPrimOp
1519    Addr# -> Int# -> Int# -> State# s -> State# s
1520    with has_side_effects = True
1521         can_fail         = True
1522
1523 primop  WriteOffAddrOp_Int16 "writeInt16OffAddr#" GenPrimOp
1524    Addr# -> Int# -> Int# -> State# s -> State# s
1525    with has_side_effects = True
1526         can_fail         = True
1527
1528 primop  WriteOffAddrOp_Int32 "writeInt32OffAddr#" GenPrimOp
1529    Addr# -> Int# -> INT32 -> State# s -> State# s
1530    with has_side_effects = True
1531         can_fail         = True
1532
1533 primop  WriteOffAddrOp_Int64 "writeInt64OffAddr#" GenPrimOp
1534    Addr# -> Int# -> INT64 -> State# s -> State# s
1535    with has_side_effects = True
1536         can_fail         = True
1537
1538 primop  WriteOffAddrOp_Word8 "writeWord8OffAddr#" GenPrimOp
1539    Addr# -> Int# -> Word# -> State# s -> State# s
1540    with has_side_effects = True
1541         can_fail         = True
1542
1543 primop  WriteOffAddrOp_Word16 "writeWord16OffAddr#" GenPrimOp
1544    Addr# -> Int# -> Word# -> State# s -> State# s
1545    with has_side_effects = True
1546         can_fail         = True
1547
1548 primop  WriteOffAddrOp_Word32 "writeWord32OffAddr#" GenPrimOp
1549    Addr# -> Int# -> WORD32 -> State# s -> State# s
1550    with has_side_effects = True
1551         can_fail         = True
1552
1553 primop  WriteOffAddrOp_Word64 "writeWord64OffAddr#" GenPrimOp
1554    Addr# -> Int# -> WORD64 -> State# s -> State# s
1555    with has_side_effects = True
1556         can_fail         = True
1557
1558 ------------------------------------------------------------------------
1559 section "Mutable variables"
1560         {Operations on MutVar\#s.}
1561 ------------------------------------------------------------------------
1562
1563 primtype MutVar# s a
1564         {A {\tt MutVar\#} behaves like a single-element mutable array.}
1565
1566 primop  NewMutVarOp "newMutVar#" GenPrimOp
1567    a -> State# s -> (# State# s, MutVar# s a #)
1568    {Create {\tt MutVar\#} with specified initial value in specified state thread.}
1569    with
1570    out_of_line = True
1571    has_side_effects = True
1572
1573 primop  ReadMutVarOp "readMutVar#" GenPrimOp
1574    MutVar# s a -> State# s -> (# State# s, a #)
1575    {Read contents of {\tt MutVar\#}. Result is not yet evaluated.}
1576    with
1577    has_side_effects = True
1578    can_fail         = True
1579
1580 primop  WriteMutVarOp "writeMutVar#"  GenPrimOp
1581    MutVar# s a -> a -> State# s -> State# s
1582    {Write contents of {\tt MutVar\#}.}
1583    with
1584    has_side_effects = True
1585    code_size = { primOpCodeSizeForeignCall } -- for the write barrier
1586    can_fail         = True
1587
1588 primop  SameMutVarOp "sameMutVar#" GenPrimOp
1589    MutVar# s a -> MutVar# s a -> Int#
1590
1591 -- not really the right type, but we don't know about pairs here.  The
1592 -- correct type is
1593 --
1594 --   MutVar# s a -> (a -> (a,b)) -> State# s -> (# State# s, b #)
1595 --
1596 primop  AtomicModifyMutVarOp "atomicModifyMutVar#" GenPrimOp
1597    MutVar# s a -> (a -> b) -> State# s -> (# State# s, c #)
1598    with
1599    out_of_line = True
1600    has_side_effects = True
1601    can_fail         = True
1602
1603 primop  CasMutVarOp "casMutVar#" GenPrimOp
1604   MutVar# s a -> a -> a -> State# s -> (# State# s, Int#, a #)
1605    with
1606    out_of_line = True
1607    has_side_effects = True
1608
1609 ------------------------------------------------------------------------
1610 section "Exceptions"
1611 ------------------------------------------------------------------------
1612
1613 primop  CatchOp "catch#" GenPrimOp
1614           (State# RealWorld -> (# State# RealWorld, a #) )
1615        -> (b -> State# RealWorld -> (# State# RealWorld, a #) )
1616        -> State# RealWorld
1617        -> (# State# RealWorld, a #)
1618    with
1619         -- Catch is actually strict in its first argument
1620         -- but we don't want to tell the strictness
1621         -- analyser about that!
1622         -- might use caught action multiply
1623    out_of_line = True
1624    has_side_effects = True
1625
1626 primop  RaiseOp "raise#" GenPrimOp
1627    a -> b
1628    with
1629    strictness  = { \ _arity -> mkStrictSig (mkTopDmdType [topDmd] botRes) }
1630       -- NB: result is bottom
1631    out_of_line = True
1632
1633 -- raiseIO# needs to be a primop, because exceptions in the IO monad
1634 -- must be *precise* - we don't want the strictness analyser turning
1635 -- one kind of bottom into another, as it is allowed to do in pure code.
1636 --
1637 -- But we *do* want to know that it returns bottom after
1638 -- being applied to two arguments, so that this function is strict in y
1639 --     f x y | x>0       = raiseIO blah
1640 --           | y>0       = return 1
1641 --           | otherwise = return 2
1642
1643 primop  RaiseIOOp "raiseIO#" GenPrimOp
1644    a -> State# RealWorld -> (# State# RealWorld, b #)
1645    with
1646    strictness  = { \ _arity -> mkStrictSig (mkTopDmdType [topDmd, topDmd] botRes) }
1647    out_of_line = True
1648    has_side_effects = True
1649
1650 primop  MaskAsyncExceptionsOp "maskAsyncExceptions#" GenPrimOp
1651         (State# RealWorld -> (# State# RealWorld, a #))
1652      -> (State# RealWorld -> (# State# RealWorld, a #))
1653    with
1654    out_of_line = True
1655    has_side_effects = True
1656
1657 primop  MaskUninterruptibleOp "maskUninterruptible#" GenPrimOp
1658         (State# RealWorld -> (# State# RealWorld, a #))
1659      -> (State# RealWorld -> (# State# RealWorld, a #))
1660    with
1661    out_of_line = True
1662    has_side_effects = True
1663
1664 primop  UnmaskAsyncExceptionsOp "unmaskAsyncExceptions#" GenPrimOp
1665         (State# RealWorld -> (# State# RealWorld, a #))
1666      -> (State# RealWorld -> (# State# RealWorld, a #))
1667    with
1668    out_of_line = True
1669    has_side_effects = True
1670
1671 primop  MaskStatus "getMaskingState#" GenPrimOp
1672         State# RealWorld -> (# State# RealWorld, Int# #)
1673    with
1674    out_of_line = True
1675    has_side_effects = True
1676
1677 ------------------------------------------------------------------------
1678 section "STM-accessible Mutable Variables"
1679 ------------------------------------------------------------------------
1680
1681 primtype TVar# s a
1682
1683 primop  AtomicallyOp "atomically#" GenPrimOp
1684       (State# RealWorld -> (# State# RealWorld, a #) )
1685    -> State# RealWorld -> (# State# RealWorld, a #)
1686    with
1687    out_of_line = True
1688    has_side_effects = True
1689
1690 -- NB: retry#'s strictness information specifies it to return bottom.
1691 -- This lets the compiler perform some extra simplifications, since retry#
1692 -- will technically never return.
1693 --
1694 -- This allows the simplifier to replace things like:
1695 --   case retry# s1
1696 --     (# s2, a #) -> e
1697 -- with:
1698 --   retry# s1
1699 -- where 'e' would be unreachable anyway.  See Trac #8091.
1700 primop  RetryOp "retry#" GenPrimOp
1701    State# RealWorld -> (# State# RealWorld, a #)
1702    with
1703    strictness  = { \ _arity -> mkStrictSig (mkTopDmdType [topDmd] botRes) }
1704    out_of_line = True
1705    has_side_effects = True
1706
1707 primop  CatchRetryOp "catchRetry#" GenPrimOp
1708       (State# RealWorld -> (# State# RealWorld, a #) )
1709    -> (State# RealWorld -> (# State# RealWorld, a #) )
1710    -> (State# RealWorld -> (# State# RealWorld, a #) )
1711    with
1712    out_of_line = True
1713    has_side_effects = True
1714
1715 primop  CatchSTMOp "catchSTM#" GenPrimOp
1716       (State# RealWorld -> (# State# RealWorld, a #) )
1717    -> (b -> State# RealWorld -> (# State# RealWorld, a #) )
1718    -> (State# RealWorld -> (# State# RealWorld, a #) )
1719    with
1720    out_of_line = True
1721    has_side_effects = True
1722
1723 primop  Check "check#" GenPrimOp
1724       (State# RealWorld -> (# State# RealWorld, a #) )
1725    -> (State# RealWorld -> (# State# RealWorld, () #) )
1726    with
1727    out_of_line = True
1728    has_side_effects = True
1729
1730 primop  NewTVarOp "newTVar#" GenPrimOp
1731        a
1732     -> State# s -> (# State# s, TVar# s a #)
1733    {Create a new {\tt TVar\#} holding a specified initial value.}
1734    with
1735    out_of_line  = True
1736    has_side_effects = True
1737
1738 primop  ReadTVarOp "readTVar#" GenPrimOp
1739        TVar# s a
1740     -> State# s -> (# State# s, a #)
1741    {Read contents of {\tt TVar\#}.  Result is not yet evaluated.}
1742    with
1743    out_of_line  = True
1744    has_side_effects = True
1745
1746 primop ReadTVarIOOp "readTVarIO#" GenPrimOp
1747        TVar# s a
1748     -> State# s -> (# State# s, a #)
1749    {Read contents of {\tt TVar\#} outside an STM transaction}
1750    with
1751    out_of_line  = True
1752    has_side_effects = True
1753
1754 primop  WriteTVarOp "writeTVar#" GenPrimOp
1755        TVar# s a
1756     -> a
1757     -> State# s -> State# s
1758    {Write contents of {\tt TVar\#}.}
1759    with
1760    out_of_line      = True
1761    has_side_effects = True
1762
1763 primop  SameTVarOp "sameTVar#" GenPrimOp
1764    TVar# s a -> TVar# s a -> Int#
1765
1766
1767 ------------------------------------------------------------------------
1768 section "Synchronized Mutable Variables"
1769         {Operations on {\tt MVar\#}s. }
1770 ------------------------------------------------------------------------
1771
1772 primtype MVar# s a
1773         { A shared mutable variable ({\it not} the same as a {\tt MutVar\#}!).
1774         (Note: in a non-concurrent implementation, {\tt (MVar\# a)} can be
1775         represented by {\tt (MutVar\# (Maybe a))}.) }
1776
1777 primop  NewMVarOp "newMVar#"  GenPrimOp
1778    State# s -> (# State# s, MVar# s a #)
1779    {Create new {\tt MVar\#}; initially empty.}
1780    with
1781    out_of_line = True
1782    has_side_effects = True
1783
1784 primop  TakeMVarOp "takeMVar#" GenPrimOp
1785    MVar# s a -> State# s -> (# State# s, a #)
1786    {If {\tt MVar\#} is empty, block until it becomes full.
1787    Then remove and return its contents, and set it empty.}
1788    with
1789    out_of_line      = True
1790    has_side_effects = True
1791
1792 primop  TryTakeMVarOp "tryTakeMVar#" GenPrimOp
1793    MVar# s a -> State# s -> (# State# s, Int#, a #)
1794    {If {\tt MVar\#} is empty, immediately return with integer 0 and value undefined.
1795    Otherwise, return with integer 1 and contents of {\tt MVar\#}, and set {\tt MVar\#} empty.}
1796    with
1797    out_of_line      = True
1798    has_side_effects = True
1799
1800 primop  PutMVarOp "putMVar#" GenPrimOp
1801    MVar# s a -> a -> State# s -> State# s
1802    {If {\tt MVar\#} is full, block until it becomes empty.
1803    Then store value arg as its new contents.}
1804    with
1805    out_of_line      = True
1806    has_side_effects = True
1807
1808 primop  TryPutMVarOp "tryPutMVar#" GenPrimOp
1809    MVar# s a -> a -> State# s -> (# State# s, Int# #)
1810    {If {\tt MVar\#} is full, immediately return with integer 0.
1811     Otherwise, store value arg as {\tt MVar\#}'s new contents, and return with integer 1.}
1812    with
1813    out_of_line      = True
1814    has_side_effects = True
1815
1816 primop  ReadMVarOp "readMVar#" GenPrimOp
1817    MVar# s a -> State# s -> (# State# s, a #)
1818    {If {\tt MVar\#} is empty, block until it becomes full.
1819    Then read its contents without modifying the MVar, without possibility
1820    of intervention from other threads.}
1821    with
1822    out_of_line      = True
1823    has_side_effects = True
1824
1825 primop  TryReadMVarOp "tryReadMVar#" GenPrimOp
1826    MVar# s a -> State# s -> (# State# s, Int#, a #)
1827    {If {\tt MVar\#} is empty, immediately return with integer 0 and value undefined.
1828    Otherwise, return with integer 1 and contents of {\tt MVar\#}.}
1829    with
1830    out_of_line      = True
1831    has_side_effects = True
1832
1833 primop  SameMVarOp "sameMVar#" GenPrimOp
1834    MVar# s a -> MVar# s a -> Int#
1835
1836 primop  IsEmptyMVarOp "isEmptyMVar#" GenPrimOp
1837    MVar# s a -> State# s -> (# State# s, Int# #)
1838    {Return 1 if {\tt MVar\#} is empty; 0 otherwise.}
1839    with
1840    out_of_line = True
1841    has_side_effects = True
1842
1843 ------------------------------------------------------------------------
1844 section "Delay/wait operations"
1845 ------------------------------------------------------------------------
1846
1847 primop  DelayOp "delay#" GenPrimOp
1848    Int# -> State# s -> State# s
1849    {Sleep specified number of microseconds.}
1850    with
1851    has_side_effects = True
1852    out_of_line      = True
1853
1854 primop  WaitReadOp "waitRead#" GenPrimOp
1855    Int# -> State# s -> State# s
1856    {Block until input is available on specified file descriptor.}
1857    with
1858    has_side_effects = True
1859    out_of_line      = True
1860
1861 primop  WaitWriteOp "waitWrite#" GenPrimOp
1862    Int# -> State# s -> State# s
1863    {Block until output is possible on specified file descriptor.}
1864    with
1865    has_side_effects = True
1866    out_of_line      = True
1867
1868 #ifdef mingw32_TARGET_OS
1869 primop  AsyncReadOp "asyncRead#" GenPrimOp
1870    Int# -> Int# -> Int# -> Addr# -> State# RealWorld-> (# State# RealWorld, Int#, Int# #)
1871    {Asynchronously read bytes from specified file descriptor.}
1872    with
1873    has_side_effects = True
1874    out_of_line      = True
1875
1876 primop  AsyncWriteOp "asyncWrite#" GenPrimOp
1877    Int# -> Int# -> Int# -> Addr# -> State# RealWorld-> (# State# RealWorld, Int#, Int# #)
1878    {Asynchronously write bytes from specified file descriptor.}
1879    with
1880    has_side_effects = True
1881    out_of_line      = True
1882
1883 primop  AsyncDoProcOp "asyncDoProc#" GenPrimOp
1884    Addr# -> Addr# -> State# RealWorld-> (# State# RealWorld, Int#, Int# #)
1885    {Asynchronously perform procedure (first arg), passing it 2nd arg.}
1886    with
1887    has_side_effects = True
1888    out_of_line      = True
1889
1890 #endif
1891
1892 ------------------------------------------------------------------------
1893 section "Concurrency primitives"
1894 ------------------------------------------------------------------------
1895
1896 primtype State# s
1897         { {\tt State\#} is the primitive, unlifted type of states.  It has
1898         one type parameter, thus {\tt State\# RealWorld}, or {\tt State\# s},
1899         where s is a type variable. The only purpose of the type parameter
1900         is to keep different state threads separate.  It is represented by
1901         nothing at all. }
1902
1903 primtype RealWorld
1904         { {\tt RealWorld} is deeply magical.  It is {\it primitive}, but it is not
1905         {\it unlifted} (hence {\tt ptrArg}).  We never manipulate values of type
1906         {\tt RealWorld}; it's only used in the type system, to parameterise {\tt State\#}. }
1907
1908 primtype ThreadId#
1909         {(In a non-concurrent implementation, this can be a singleton
1910         type, whose (unique) value is returned by {\tt myThreadId\#}.  The
1911         other operations can be omitted.)}
1912
1913 primop  ForkOp "fork#" GenPrimOp
1914    a -> State# RealWorld -> (# State# RealWorld, ThreadId# #)
1915    with
1916    has_side_effects = True
1917    out_of_line      = True
1918
1919 primop  ForkOnOp "forkOn#" GenPrimOp
1920    Int# -> a -> State# RealWorld -> (# State# RealWorld, ThreadId# #)
1921    with
1922    has_side_effects = True
1923    out_of_line      = True
1924
1925 primop  KillThreadOp "killThread#"  GenPrimOp
1926    ThreadId# -> a -> State# RealWorld -> State# RealWorld
1927    with
1928    has_side_effects = True
1929    out_of_line      = True
1930
1931 primop  YieldOp "yield#" GenPrimOp
1932    State# RealWorld -> State# RealWorld
1933    with
1934    has_side_effects = True
1935    out_of_line      = True
1936
1937 primop  MyThreadIdOp "myThreadId#" GenPrimOp
1938    State# RealWorld -> (# State# RealWorld, ThreadId# #)
1939    with
1940    out_of_line = True
1941    has_side_effects = True
1942
1943 primop LabelThreadOp "labelThread#" GenPrimOp
1944    ThreadId# -> Addr# -> State# RealWorld -> State# RealWorld
1945    with
1946    has_side_effects = True
1947    out_of_line      = True
1948
1949 primop  IsCurrentThreadBoundOp "isCurrentThreadBound#" GenPrimOp
1950    State# RealWorld -> (# State# RealWorld, Int# #)
1951    with
1952    out_of_line = True
1953    has_side_effects = True
1954
1955 primop  NoDuplicateOp "noDuplicate#" GenPrimOp
1956    State# RealWorld -> State# RealWorld
1957    with
1958    out_of_line = True
1959    has_side_effects = True
1960
1961 primop  ThreadStatusOp "threadStatus#" GenPrimOp
1962    ThreadId# -> State# RealWorld -> (# State# RealWorld, Int#, Int#, Int# #)
1963    with
1964    out_of_line = True
1965    has_side_effects = True
1966
1967 ------------------------------------------------------------------------
1968 section "Weak pointers"
1969 ------------------------------------------------------------------------
1970
1971 primtype Weak# b
1972
1973 -- note that tyvar "o" denotes openAlphaTyVar
1974
1975 primop  MkWeakOp "mkWeak#" GenPrimOp
1976    o -> b -> c -> State# RealWorld -> (# State# RealWorld, Weak# b #)
1977    with
1978    has_side_effects = True
1979    out_of_line      = True
1980
1981 primop  MkWeakNoFinalizerOp "mkWeakNoFinalizer#" GenPrimOp
1982    o -> b -> State# RealWorld -> (# State# RealWorld, Weak# b #)
1983    with
1984    has_side_effects = True
1985    out_of_line      = True
1986
1987 primop  AddCFinalizerToWeakOp "addCFinalizerToWeak#" GenPrimOp
1988    Addr# -> Addr# -> Int# -> Addr# -> Weak# b
1989           -> State# RealWorld -> (# State# RealWorld, Int# #)
1990    { {\tt addCFinalizerToWeak# fptr ptr flag eptr w} attaches a C
1991      function pointer {\tt fptr} to a weak pointer {\tt w} as a finalizer. If
1992      {\tt flag} is zero, {\tt fptr} will be called with one argument,
1993      {\tt ptr}. Otherwise, it will be called with two arguments,
1994      {\tt eptr} and {\tt ptr}. {\tt addCFinalizerToWeak#} returns
1995      1 on success, or 0 if {\tt w} is already dead. }
1996    with
1997    has_side_effects = True
1998    out_of_line      = True
1999
2000 primop  DeRefWeakOp "deRefWeak#" GenPrimOp
2001    Weak# a -> State# RealWorld -> (# State# RealWorld, Int#, a #)
2002    with
2003    has_side_effects = True
2004    out_of_line      = True
2005
2006 primop  FinalizeWeakOp "finalizeWeak#" GenPrimOp
2007    Weak# a -> State# RealWorld -> (# State# RealWorld, Int#,
2008               (State# RealWorld -> (# State# RealWorld, () #)) #)
2009    with
2010    has_side_effects = True
2011    out_of_line      = True
2012
2013 primop TouchOp "touch#" GenPrimOp
2014    o -> State# RealWorld -> State# RealWorld
2015    with
2016    code_size = { 0 }
2017    has_side_effects = True
2018
2019 ------------------------------------------------------------------------
2020 section "Stable pointers and names"
2021 ------------------------------------------------------------------------
2022
2023 primtype StablePtr# a
2024
2025 primtype StableName# a
2026
2027 primop  MakeStablePtrOp "makeStablePtr#" GenPrimOp
2028    a -> State# RealWorld -> (# State# RealWorld, StablePtr# a #)
2029    with
2030    has_side_effects = True
2031    out_of_line      = True
2032
2033 primop  DeRefStablePtrOp "deRefStablePtr#" GenPrimOp
2034    StablePtr# a -> State# RealWorld -> (# State# RealWorld, a #)
2035    with
2036    has_side_effects = True
2037    out_of_line      = True
2038
2039 primop  EqStablePtrOp "eqStablePtr#" GenPrimOp
2040    StablePtr# a -> StablePtr# a -> Int#
2041    with
2042    has_side_effects = True
2043
2044 primop  MakeStableNameOp "makeStableName#" GenPrimOp
2045    a -> State# RealWorld -> (# State# RealWorld, StableName# a #)
2046    with
2047    has_side_effects = True
2048    out_of_line      = True
2049
2050 primop  EqStableNameOp "eqStableName#" GenPrimOp
2051    StableName# a -> StableName# b -> Int#
2052
2053 primop  StableNameToIntOp "stableNameToInt#" GenPrimOp
2054    StableName# a -> Int#
2055
2056 ------------------------------------------------------------------------
2057 section "Unsafe pointer equality"
2058 --  (#1 Bad Guy: Alistair Reid :)
2059 ------------------------------------------------------------------------
2060
2061 primop  ReallyUnsafePtrEqualityOp "reallyUnsafePtrEquality#" GenPrimOp
2062    a -> a -> Int#
2063
2064 ------------------------------------------------------------------------
2065 section "Parallelism"
2066 ------------------------------------------------------------------------
2067
2068 primop  ParOp "par#" GenPrimOp
2069    a -> Int#
2070    with
2071       -- Note that Par is lazy to avoid that the sparked thing
2072       -- gets evaluted strictly, which it should *not* be
2073    has_side_effects = True
2074    code_size = { primOpCodeSizeForeignCall }
2075
2076 primop SparkOp "spark#" GenPrimOp
2077    a -> State# s -> (# State# s, a #)
2078    with has_side_effects = True
2079    code_size = { primOpCodeSizeForeignCall }
2080
2081 primop SeqOp "seq#" GenPrimOp
2082    a -> State# s -> (# State# s, a #)
2083
2084    -- why return the value?  So that we can control sharing of seq'd
2085    -- values: in
2086    --    let x = e in x `seq` ... x ...
2087    -- we don't want to inline x, so better to represent it as
2088    --    let x = e in case seq# x RW of (# _, x' #) -> ... x' ...
2089    -- also it matches the type of rseq in the Eval monad.
2090
2091 primop GetSparkOp "getSpark#" GenPrimOp
2092    State# s -> (# State# s, Int#, a #)
2093    with
2094    has_side_effects = True
2095    out_of_line = True
2096
2097 primop NumSparks "numSparks#" GenPrimOp
2098    State# s -> (# State# s, Int# #)
2099    { Returns the number of sparks in the local spark pool. }
2100    with
2101    has_side_effects = True
2102    out_of_line = True
2103
2104 -- HWL: The first 4 Int# in all par... annotations denote:
2105 --   name, granularity info, size of result, degree of parallelism
2106 --      Same  structure as _seq_ i.e. returns Int#
2107 -- KSW: v, the second arg in parAt# and parAtForNow#, is used only to determine
2108 --   `the processor containing the expression v'; it is not evaluated
2109
2110 primop  ParGlobalOp  "parGlobal#"  GenPrimOp
2111    a -> Int# -> Int# -> Int# -> Int# -> b -> Int#
2112    with
2113    has_side_effects = True
2114
2115 primop  ParLocalOp  "parLocal#"  GenPrimOp
2116    a -> Int# -> Int# -> Int# -> Int# -> b -> Int#
2117    with
2118    has_side_effects = True
2119
2120 primop  ParAtOp  "parAt#"  GenPrimOp
2121    b -> a -> Int# -> Int# -> Int# -> Int# -> c -> Int#
2122    with
2123    has_side_effects = True
2124
2125 primop  ParAtAbsOp  "parAtAbs#"  GenPrimOp
2126    a -> Int# -> Int# -> Int# -> Int# -> Int# -> b -> Int#
2127    with
2128    has_side_effects = True
2129
2130 primop  ParAtRelOp  "parAtRel#" GenPrimOp
2131    a -> Int# -> Int# -> Int# -> Int# -> Int# -> b -> Int#
2132    with
2133    has_side_effects = True
2134
2135 primop  ParAtForNowOp  "parAtForNow#" GenPrimOp
2136    b -> a -> Int# -> Int# -> Int# -> Int# -> c -> Int#
2137    with
2138    has_side_effects = True
2139
2140 -- copyable# and noFollow# are yet to be implemented (for GpH)
2141 --
2142 --primop  CopyableOp  "copyable#" GenPrimOp
2143 --   a -> Int#
2144 --   with
2145 --   has_side_effects = True
2146 --
2147 --primop  NoFollowOp "noFollow#" GenPrimOp
2148 --   a -> Int#
2149 --   with
2150 --   has_side_effects = True
2151
2152
2153 ------------------------------------------------------------------------
2154 section "Tag to enum stuff"
2155         {Convert back and forth between values of enumerated types
2156         and small integers.}
2157 ------------------------------------------------------------------------
2158
2159 primop  DataToTagOp "dataToTag#" GenPrimOp
2160    a -> Int#
2161    with
2162    strictness  = { \ _arity -> mkStrictSig (mkTopDmdType [evalDmd] topRes) }
2163
2164         -- dataToTag# must have an evaluated argument
2165
2166 primop  TagToEnumOp "tagToEnum#" GenPrimOp
2167    Int# -> a
2168
2169 ------------------------------------------------------------------------
2170 section "Bytecode operations"
2171         {Support for the bytecode interpreter and linker.}
2172 ------------------------------------------------------------------------
2173
2174 primtype BCO#
2175    {Primitive bytecode type.}
2176
2177 primop   AddrToAnyOp "addrToAny#" GenPrimOp
2178    Addr# -> (# a #)
2179    {Convert an {\tt Addr\#} to a followable Any type.}
2180    with
2181    code_size = 0
2182
2183 primop   MkApUpd0_Op "mkApUpd0#" GenPrimOp
2184    BCO# -> (# a #)
2185    with
2186    out_of_line = True
2187
2188 primop  NewBCOOp "newBCO#" GenPrimOp
2189    ByteArray# -> ByteArray# -> Array# a -> Int# -> ByteArray# -> State# s -> (# State# s, BCO# #)
2190    with
2191    has_side_effects = True
2192    out_of_line      = True
2193
2194 primop  UnpackClosureOp "unpackClosure#" GenPrimOp
2195    a -> (# Addr#, Array# b, ByteArray# #)
2196    with
2197    out_of_line = True
2198
2199 primop  GetApStackValOp "getApStackVal#" GenPrimOp
2200    a -> Int# -> (# Int#, b #)
2201    with
2202    out_of_line = True
2203
2204 ------------------------------------------------------------------------
2205 section "Misc"
2206         {These aren't nearly as wired in as Etc...}
2207 ------------------------------------------------------------------------
2208
2209 primop  GetCCSOfOp "getCCSOf#" GenPrimOp
2210    a -> State# s -> (# State# s, Addr# #)
2211
2212 primop  GetCurrentCCSOp "getCurrentCCS#" GenPrimOp
2213    a -> State# s -> (# State# s, Addr# #)
2214    { Returns the current {\tt CostCentreStack} (value is {\tt NULL} if
2215      not profiling).  Takes a dummy argument which can be used to
2216      avoid the call to {\tt getCCCS\#} being floated out by the
2217      simplifier, which would result in an uninformative stack
2218      ("CAF"). }
2219
2220 ------------------------------------------------------------------------
2221 section "Etc"
2222         {Miscellaneous built-ins}
2223 ------------------------------------------------------------------------
2224
2225 pseudoop   "seq"
2226    a -> b -> b
2227    { Evaluates its first argument to head normal form, and then returns its second
2228         argument as the result. }
2229
2230 primtype Any k
2231         { The type constructor {\tt Any} is type to which you can unsafely coerce any
2232         lifted type, and back.
2233
2234           * It is lifted, and hence represented by a pointer
2235
2236           * It does not claim to be a {\it data} type, and that's important for
2237             the code generator, because the code gen may {\it enter} a data value
2238             but never enters a function value.
2239
2240         It's also used to instantiate un-constrained type variables after type
2241         checking.  For example, {\tt length} has type
2242
2243         {\tt length :: forall a. [a] -> Int}
2244
2245         and the list datacon for the empty list has type
2246
2247         {\tt [] :: forall a. [a]}
2248
2249         In order to compose these two terms as {\tt length []} a type
2250         application is required, but there is no constraint on the
2251         choice.  In this situation GHC uses {\tt Any}:
2252
2253         {\tt length (Any *) ([] (Any *))}
2254
2255         Note that {\tt Any} is kind polymorphic, and takes a kind {\tt k} as its
2256         first argument. The kind of {\tt Any} is thus {\tt forall k. k -> k}.}
2257
2258 primtype AnyK
2259         { The kind {\tt AnyK} is the kind level counterpart to {\tt Any}. In a
2260         kind polymorphic setting, a similar example to the length of the empty
2261         list can be given at the type level:
2262
2263         {\tt type family Length (l :: [k]) :: Nat}
2264         {\tt type instance Length [] = Zero}
2265
2266         When {\tt Length} is applied to the empty (promoted) list it will have
2267         the kind {\tt Length AnyK []}.
2268
2269         {\tt AnyK} is currently not exported and cannot be used directly, but
2270         you might see it in debug output from the compiler.
2271         }
2272
2273 pseudoop   "unsafeCoerce#"
2274    a -> b
2275    { The function {\tt unsafeCoerce\#} allows you to side-step the typechecker entirely. That
2276         is, it allows you to coerce any type into any other type. If you use this function,
2277         you had better get it right, otherwise segmentation faults await. It is generally
2278         used when you want to write a program that you know is well-typed, but where Haskell's
2279         type system is not expressive enough to prove that it is well typed.
2280
2281         The following uses of {\tt unsafeCoerce\#} are supposed to work (i.e. not lead to
2282         spurious compile-time or run-time crashes):
2283
2284          * Casting any lifted type to {\tt Any}
2285
2286          * Casting {\tt Any} back to the real type
2287
2288          * Casting an unboxed type to another unboxed type of the same size
2289            (but not coercions between floating-point and integral types)
2290
2291          * Casting between two types that have the same runtime representation.  One case is when
2292            the two types differ only in "phantom" type parameters, for example
2293            {\tt Ptr Int} to {\tt Ptr Float}, or {\tt [Int]} to {\tt [Float]} when the list is
2294            known to be empty.  Also, a {\tt newtype} of a type {\tt T} has the same representation
2295            at runtime as {\tt T}.
2296
2297         Other uses of {\tt unsafeCoerce\#} are undefined.  In particular, you should not use
2298         {\tt unsafeCoerce\#} to cast a T to an algebraic data type D, unless T is also
2299         an algebraic data type.  For example, do not cast {\tt Int->Int} to {\tt Bool}, even if
2300         you later cast that {\tt Bool} back to {\tt Int->Int} before applying it.  The reasons
2301         have to do with GHC's internal representation details (for the congnoscenti, data values
2302         can be entered but function closures cannot).  If you want a safe type to cast things
2303         to, use {\tt Any}, which is not an algebraic data type.
2304
2305         }
2306
2307 -- NB. It is tempting to think that casting a value to a type that it doesn't have is safe
2308 -- as long as you don't "do anything" with the value in its cast form, such as seq on it.  This
2309 -- isn't the case: the compiler can insert seqs itself, and if these happen at the wrong type,
2310 -- Bad Things Might Happen.  See bug #1616: in this case we cast a function of type (a,b) -> (a,b)
2311 -- to () -> () and back again.  The strictness analyser saw that the function was strict, but
2312 -- the wrapper had type () -> (), and hence the wrapper de-constructed the (), the worker re-constructed
2313 -- a new (), with the result that the code ended up with "case () of (a,b) -> ...".
2314
2315 primop  TraceEventOp "traceEvent#" GenPrimOp
2316    Addr# -> State# s -> State# s
2317    { Emits an event via the RTS tracing framework.  The contents
2318      of the event is the zero-terminated byte string passed as the first
2319      argument.  The event will be emitted either to the .eventlog file,
2320      or to stderr, depending on the runtime RTS flags. }
2321    with
2322    has_side_effects = True
2323    out_of_line      = True
2324
2325 primop  TraceMarkerOp "traceMarker#" GenPrimOp
2326    Addr# -> State# s -> State# s
2327    { Emits a marker event via the RTS tracing framework.  The contents
2328      of the event is the zero-terminated byte string passed as the first
2329      argument.  The event will be emitted either to the .eventlog file,
2330      or to stderr, depending on the runtime RTS flags. }
2331    with
2332    has_side_effects = True
2333    out_of_line      = True
2334
2335 ------------------------------------------------------------------------
2336 section "Safe coercions"
2337 ------------------------------------------------------------------------
2338
2339 pseudoop   "coerce"
2340    Coercible a b => a -> b
2341    { The function {\tt coerce} allows you to safely convert between values of
2342      types that have the same representation with no run-time overhead. In the
2343      simplest case you can use it instead of a newtype constructor, to go from
2344      the newtype's concrete type to the abstract type. But it also works in
2345      more complicated settings, e.g. converting a list of newtypes to a list of
2346      concrete types.
2347    }
2348
2349 primclass Coercible a b
2350    { This two-parameter class has instances for types {\tt a} and {\tt b} if
2351      the compiler can infer that they have the same representation. This class
2352      does not have regular instances; instead they are created on-the-fly during
2353      type-checking. Trying to manually declare an instance of {\tt Coercible}
2354      is an error.
2355
2356      Nevertheless one can pretend that the following three kinds of instances
2357      exist. First, as a trivial base-case:
2358
2359      {\tt instance a a}
2360
2361      Furthermore, for every type constructor there is
2362      an instance that allows to coerce under the type constructor. For
2363      example, let {\tt D} be a prototypical type constructor ({\tt data} or {\tt
2364      newtype}) with three type arguments, which have roles Nominal,
2365      Representational resp. Phantom. Then there is an instance of the form
2366
2367      {\tt instance Coercible b b' => Coercible (D a b c) (D a b' c')}
2368
2369      Note that the nominal type arguments are equal, the representational type
2370      arguments can differ, but need to have a {\tt Coercible} instance
2371      themself, and the phantom type arguments can be changed arbitrarily.
2372
2373      In SafeHaskell code, this instance is only usable if the constructors of
2374      every type constructor used in the definition of {\tt D} (including
2375      those of {\tt D} itself) is in scope.
2376
2377      The third kind of instance exists for every {\tt newtype NT = MkNT T} and
2378      comes in two variants, namely
2379
2380      {\tt instance Coercible a T => Coercible a NT}
2381
2382      {\tt instance Coercible T b => Coercible NT b}
2383
2384      This instance is only usable if the constructor {\tt MkNT} is in scope.
2385
2386      If, as a library author of a type constructor like {\tt Set a}, you
2387      want to prevent a user of your module to write
2388      {\tt coerce :: Set T -> Set NT},
2389      you need to set the role of {\tt Set}'s type parameter to Nominal.
2390    }
2391
2392 ------------------------------------------------------------------------
2393 section "SIMD Vectors"
2394         {Operations on SIMD vectors.}
2395 ------------------------------------------------------------------------
2396
2397 #define ALL_VECTOR_TYPES \
2398   [<Int8,Int#,16>,<Int16,Int#,8>,<Int32,INT32,4>,<Int64,INT64,2> \
2399   ,<Int8,Int#,32>,<Int16,Int#,16>,<Int32,INT32,8>,<Int64,INT64,4> \
2400   ,<Int8,Int#,64>,<Int16,Int#,32>,<Int32,INT32,16>,<Int64,INT64,8> \
2401   ,<Word8,Word#,16>,<Word16,Word#,8>,<Word32,WORD32,4>,<Word64,WORD64,2> \
2402   ,<Word8,Word#,32>,<Word16,Word#,16>,<Word32,WORD32,8>,<Word64,WORD64,4> \
2403   ,<Word8,Word#,64>,<Word16,Word#,32>,<Word32,WORD32,16>,<Word64,WORD64,8> \
2404   ,<Float,Float#,4>,<Double,Double#,2> \
2405   ,<Float,Float#,8>,<Double,Double#,4> \
2406   ,<Float,Float#,16>,<Double,Double#,8>]
2407
2408 #define SIGNED_VECTOR_TYPES \
2409   [<Int8,Int#,16>,<Int16,Int#,8>,<Int32,INT32,4>,<Int64,INT64,2> \
2410   ,<Int8,Int#,32>,<Int16,Int#,16>,<Int32,INT32,8>,<Int64,INT64,4> \
2411   ,<Int8,Int#,64>,<Int16,Int#,32>,<Int32,INT32,16>,<Int64,INT64,8> \
2412   ,<Float,Float#,4>,<Double,Double#,2> \
2413   ,<Float,Float#,8>,<Double,Double#,4> \
2414   ,<Float,Float#,16>,<Double,Double#,8>]
2415
2416 #define FLOAT_VECTOR_TYPES \
2417   [<Float,Float#,4>,<Double,Double#,2> \
2418   ,<Float,Float#,8>,<Double,Double#,4> \
2419   ,<Float,Float#,16>,<Double,Double#,8>]
2420
2421 #define INT_VECTOR_TYPES \
2422   [<Int8,Int#,16>,<Int16,Int#,8>,<Int32,INT32,4>,<Int64,INT64,2> \
2423   ,<Int8,Int#,32>,<Int16,Int#,16>,<Int32,INT32,8>,<Int64,INT64,4> \
2424   ,<Int8,Int#,64>,<Int16,Int#,32>,<Int32,INT32,16>,<Int64,INT64,8> \
2425   ,<Word8,Word#,16>,<Word16,Word#,8>,<Word32,WORD32,4>,<Word64,WORD64,2> \
2426   ,<Word8,Word#,32>,<Word16,Word#,16>,<Word32,WORD32,8>,<Word64,WORD64,4> \
2427   ,<Word8,Word#,64>,<Word16,Word#,32>,<Word32,WORD32,16>,<Word64,WORD64,8>]
2428
2429 primtype VECTOR
2430    with llvm_only = True
2431         vector = ALL_VECTOR_TYPES
2432
2433 primop VecBroadcastOp "broadcast#" GenPrimOp
2434    SCALAR -> VECTOR
2435    { Broadcast a scalar to all elements of a vector. }
2436    with llvm_only = True
2437         vector = ALL_VECTOR_TYPES
2438
2439 primop VecPackOp "pack#" GenPrimOp
2440    VECTUPLE -> VECTOR
2441    { Pack the elements of an unboxed tuple into a vector. }
2442    with llvm_only = True
2443         vector = ALL_VECTOR_TYPES
2444
2445 primop VecUnpackOp "unpack#" GenPrimOp
2446    VECTOR -> VECTUPLE
2447    { Unpack the elements of a vector into an unboxed tuple. #}
2448    with llvm_only = True
2449         vector = ALL_VECTOR_TYPES
2450
2451 primop VecInsertOp "insert#" GenPrimOp
2452    VECTOR -> SCALAR -> Int# -> VECTOR
2453    { Insert a scalar at the given position in a vector. }
2454    with can_fail = True
2455         llvm_only = True
2456         vector = ALL_VECTOR_TYPES
2457
2458 primop VecAddOp "plus#" Dyadic
2459    VECTOR -> VECTOR -> VECTOR
2460    { Add two vectors element-wise. }
2461    with commutable = True
2462         llvm_only = True
2463         vector = ALL_VECTOR_TYPES
2464
2465 primop VecSubOp "minus#" Dyadic
2466    VECTOR -> VECTOR -> VECTOR
2467    { Subtract two vectors element-wise. }
2468    with llvm_only = True
2469         vector = ALL_VECTOR_TYPES
2470
2471 primop VecMulOp "times#" Dyadic
2472    VECTOR -> VECTOR -> VECTOR
2473    { Multiply two vectors element-wise. }
2474    with commutable = True
2475         llvm_only = True
2476         vector = ALL_VECTOR_TYPES
2477
2478 primop VecDivOp "divide#" Dyadic
2479    VECTOR -> VECTOR -> VECTOR
2480    { Divide two vectors element-wise. }
2481    with can_fail = True
2482         llvm_only = True
2483         vector = FLOAT_VECTOR_TYPES
2484
2485 primop VecQuotOp "quot#" Dyadic
2486    VECTOR -> VECTOR -> VECTOR
2487    { Rounds towards zero element-wise. }
2488    with can_fail = True
2489         llvm_only = True
2490         vector = INT_VECTOR_TYPES
2491
2492 primop VecRemOp "rem#" Dyadic
2493    VECTOR -> VECTOR -> VECTOR
2494    { Satisfies \texttt{(quot\# x y) times\# y plus\# (rem\# x y) == x}. }
2495    with can_fail = True
2496         llvm_only = True
2497         vector = INT_VECTOR_TYPES
2498
2499 primop VecNegOp "negate#" Monadic
2500    VECTOR -> VECTOR
2501    { Negate element-wise. }
2502    with llvm_only = True
2503         vector = SIGNED_VECTOR_TYPES
2504
2505 primop VecIndexByteArrayOp "indexArray#" GenPrimOp
2506    ByteArray# -> Int# -> VECTOR
2507    { Read a vector from specified index of immutable array. }
2508    with can_fail = True
2509         llvm_only = True
2510         vector = ALL_VECTOR_TYPES
2511
2512 primop VecReadByteArrayOp "readArray#" GenPrimOp
2513    MutableByteArray# s -> Int# -> State# s -> (# State# s, VECTOR #)
2514    { Read a vector from specified index of mutable array. }
2515    with has_side_effects = True
2516         can_fail = True
2517         llvm_only = True
2518         vector = ALL_VECTOR_TYPES
2519
2520 primop VecWriteByteArrayOp "writeArray#" GenPrimOp
2521    MutableByteArray# s -> Int# -> VECTOR -> State# s -> State# s
2522    { Write a vector to specified index of mutable array. }
2523    with has_side_effects = True
2524         can_fail = True
2525         llvm_only = True
2526         vector = ALL_VECTOR_TYPES
2527
2528 primop VecIndexOffAddrOp "indexOffAddr#" GenPrimOp
2529    Addr# -> Int# -> VECTOR
2530    { Reads vector; offset in bytes. }
2531    with can_fail = True
2532         llvm_only = True
2533         vector = ALL_VECTOR_TYPES
2534
2535 primop VecReadOffAddrOp "readOffAddr#" GenPrimOp
2536    Addr# -> Int# -> State# s -> (# State# s, VECTOR #)
2537    { Reads vector; offset in bytes. }
2538    with has_side_effects = True
2539         can_fail = True
2540         llvm_only = True
2541         vector = ALL_VECTOR_TYPES
2542
2543 primop VecWriteOffAddrOp "writeOffAddr#" GenPrimOp
2544    Addr# -> Int# -> VECTOR -> State# s -> State# s
2545    { Write vector; offset in bytes. }
2546    with has_side_effects = True
2547         can_fail = True
2548         llvm_only = True
2549         vector = ALL_VECTOR_TYPES
2550
2551
2552 primop VecIndexScalarByteArrayOp "indexArrayAs#" GenPrimOp
2553    ByteArray# -> Int# -> VECTOR
2554    { Read a vector from specified index of immutable array of scalars; offset is in scalar elements. }
2555    with can_fail = True
2556         llvm_only = True
2557         vector = ALL_VECTOR_TYPES
2558
2559 primop VecReadScalarByteArrayOp "readArrayAs#" GenPrimOp
2560    MutableByteArray# s -> Int# -> State# s -> (# State# s, VECTOR #)
2561    { Read a vector from specified index of mutable array of scalars; offset is in scalar elements. }
2562    with has_side_effects = True
2563         can_fail = True
2564         llvm_only = True
2565         vector = ALL_VECTOR_TYPES
2566
2567 primop VecWriteScalarByteArrayOp "writeArrayAs#" GenPrimOp
2568    MutableByteArray# s -> Int# -> VECTOR -> State# s -> State# s
2569    { Write a vector to specified index of mutable array of scalars; offset is in scalar elements. }
2570    with has_side_effects = True
2571         can_fail = True
2572         llvm_only = True
2573         vector = ALL_VECTOR_TYPES
2574
2575 primop VecIndexScalarOffAddrOp "indexOffAddrAs#" GenPrimOp
2576    Addr# -> Int# -> VECTOR
2577    { Reads vector; offset in scalar elements. }
2578    with can_fail = True
2579         llvm_only = True
2580         vector = ALL_VECTOR_TYPES
2581
2582 primop VecReadScalarOffAddrOp "readOffAddrAs#" GenPrimOp
2583    Addr# -> Int# -> State# s -> (# State# s, VECTOR #)
2584    { Reads vector; offset in scalar elements. }
2585    with has_side_effects = True
2586         can_fail = True
2587         llvm_only = True
2588         vector = ALL_VECTOR_TYPES
2589
2590 primop VecWriteScalarOffAddrOp "writeOffAddrAs#" GenPrimOp
2591    Addr# -> Int# -> VECTOR -> State# s -> State# s
2592    { Write vector; offset in scalar elements. }
2593    with has_side_effects = True
2594         can_fail = True
2595         llvm_only = True
2596         vector = ALL_VECTOR_TYPES
2597
2598 ------------------------------------------------------------------------
2599
2600 section "Prefetch"
2601         {Prefetch operations: Note how every prefetch operation has a name
2602   with the pattern prefetch*N#, where N is either 0,1,2, or 3.
2603
2604   This suffix number, N, is the "locality level" of the prefetch, following the
2605   convention in GCC and other compilers.
2606   Higher locality numbers correspond to the memory being loaded in more
2607   levels of the cpu cache, and being retained after initial use. The naming
2608   convention follows the naming convention of the prefetch intrinsic found
2609   in the GCC and Clang C compilers.
2610
2611   On the LLVM backend, prefetch*N# uses the LLVM prefetch intrinsic
2612   with locality level N. The code generated by LLVM is target architecture
2613   dependent, but should agree with the GHC NCG on x86 systems.
2614
2615   On the Sparc and PPC native backends, prefetch*N is a No-Op.
2616
2617   On the x86 NCG, N=0 will generate prefetchNTA,
2618   N=1 generates prefetcht2, N=2 generates prefetcht1, and
2619   N=3 generates prefetcht0.
2620
2621   For streaming workloads, the prefetch*0 operations are recommended.
2622   For workloads which do many reads or writes to a memory location in a short period of time,
2623   prefetch*3 operations are recommended.
2624
2625   For further reading about prefetch and associated systems performance optimization,
2626   the instruction set and optimization manuals by Intel and other CPU vendors are
2627   excellent starting place.
2628
2629
2630   The "Intel 64 and IA-32 Architectures Optimization Reference Manual" is
2631   especially a helpful read, even if your software is meant for other CPU
2632   architectures or vendor hardware. The manual can be found at
2633   http://www.intel.com/content/www/us/en/architecture-and-technology/64-ia-32-architectures-optimization-manual.html .
2634
2635   The {\tt prefetchMutableByteArray} family of operations has the order of operations
2636   determined by passing around the {\tt State#} token.
2637
2638   For the {\tt prefetchByteArray}
2639   and {\tt prefetchAddr} families of operations, consider the following example:
2640
2641   {\tt let a1 = prefetchByteArray2# a n in ...a1... }
2642
2643   In the above fragement, {\tt a} is the input variable for the prefetch
2644   and {\tt a1 == a} will be true. To ensure that the prefetch is not treated as deadcode,
2645   the body of the let should only use {\tt a1} and NOT {\tt a}. The same principle
2646   applies for uses of prefetch in a loop.
2647
2648   }
2649
2650
2651 ------------------------------------------------------------------------
2652
2653
2654 --- the Int# argument for prefetch is the byte offset on the byteArray or  Addr#
2655
2656 ---
2657 primop PrefetchByteArrayOp3 "prefetchByteArray3#" GenPrimOp
2658    ByteArray# -> Int# -> ByteArray#
2659
2660 primop PrefetchMutableByteArrayOp3 "prefetchMutableByteArray3#" GenPrimOp
2661    MutableByteArray# s -> Int# -> State# s -> State# s
2662
2663 primop PrefetchAddrOp3 "prefetchAddr3#" GenPrimOp
2664     Addr# -> Int# -> Addr#
2665
2666 ----
2667
2668 primop PrefetchByteArrayOp2 "prefetchByteArray2#" GenPrimOp
2669    ByteArray# -> Int# -> ByteArray#
2670
2671 primop PrefetchMutableByteArrayOp2 "prefetchMutableByteArray2#" GenPrimOp
2672    MutableByteArray# s -> Int# -> State# s -> State# s
2673
2674 primop PrefetchAddrOp2 "prefetchAddr2#" GenPrimOp
2675    Addr# -> Int# -> Addr#
2676
2677 ----
2678
2679 primop PrefetchByteArrayOp1 "prefetchByteArray1#" GenPrimOp
2680    ByteArray# -> Int# -> ByteArray#
2681
2682 primop PrefetchMutableByteArrayOp1 "prefetchMutableByteArray1#" GenPrimOp
2683    MutableByteArray# s -> Int# -> State# s -> State# s
2684
2685 primop PrefetchAddrOp1 "prefetchAddr1#" GenPrimOp
2686    Addr# -> Int# -> Addr#
2687
2688 ----
2689
2690 primop PrefetchByteArrayOp0 "prefetchByteArray0#" GenPrimOp
2691    ByteArray# -> Int# -> ByteArray#
2692
2693 primop PrefetchMutableByteArrayOp0 "prefetchMutableByteArray0#" GenPrimOp
2694    MutableByteArray# s -> Int# -> State# s -> State# s
2695
2696 primop PrefetchAddrOp0 "prefetchAddr0#" GenPrimOp
2697    Addr# -> Int# -> Addr#
2698
2699
2700
2701 ------------------------------------------------------------------------
2702 ---                                                                  ---
2703 ------------------------------------------------------------------------
2704
2705 thats_all_folks