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