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