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