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