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