Add fixity information to primops (ticket #6026)
[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://hackage.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://hackage.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 defaults
43    has_side_effects = False
44    out_of_line      = False   -- See Note Note [PrimOp can_fail and has_side_effects] in PrimOp
45    can_fail         = False   -- See Note Note [PrimOp can_fail and has_side_effects] in PrimOp
46    commutable       = False
47    code_size        = { primOpCodeSizeDefault }
48    strictness       = { \ arity -> mkStrictSig (mkTopDmdType (replicate arity lazyDmd) TopRes) }
49    fixity           = Nothing
50
51
52 -- Currently, documentation is produced using latex, so contents of
53 -- description fields should be legal latex. Descriptions can contain
54 -- matched pairs of embedded curly brackets.
55
56 #include "MachDeps.h"
57
58 -- We need platform defines (tests for mingw32 below).
59 #include "ghc_boot_platform.h"
60
61 section "The word size story."
62         {Haskell98 specifies that signed integers (type {\tt Int})
63          must contain at least 30 bits. GHC always implements {\tt
64          Int} using the primitive type {\tt Int\#}, whose size equals
65          the {\tt MachDeps.h} constant {\tt WORD\_SIZE\_IN\_BITS}.
66          This is normally set based on the {\tt config.h} parameter
67          {\tt SIZEOF\_HSWORD}, i.e., 32 bits on 32-bit machines, 64
68          bits on 64-bit machines.  However, it can also be explicitly
69          set to a smaller number, e.g., 31 bits, to allow the
70          possibility of using tag bits. Currently GHC itself has only
71          32-bit and 64-bit variants, but 30 or 31-bit code can be
72          exported as an external core file for use in other back ends.
73
74          GHC also implements a primitive unsigned integer type {\tt
75          Word\#} which always has the same number of bits as {\tt
76          Int\#}.
77         
78          In addition, GHC supports families of explicit-sized integers
79          and words at 8, 16, 32, and 64 bits, with the usual
80          arithmetic operations, comparisons, and a range of
81          conversions.  The 8-bit and 16-bit sizes are always
82          represented as {\tt Int\#} and {\tt Word\#}, and the
83          operations implemented in terms of the the primops on these
84          types, with suitable range restrictions on the results (using
85          the {\tt narrow$n$Int\#} and {\tt narrow$n$Word\#} families
86          of primops.  The 32-bit sizes are represented using {\tt
87          Int\#} and {\tt Word\#} when {\tt WORD\_SIZE\_IN\_BITS}
88          $\geq$ 32; otherwise, these are represented using distinct
89          primitive types {\tt Int32\#} and {\tt Word32\#}. These (when
90          needed) have a complete set of corresponding operations;
91          however, nearly all of these are implemented as external C
92          functions rather than as primops.  Exactly the same story
93          applies to the 64-bit sizes.  All of these details are hidden
94          under the {\tt PrelInt} and {\tt PrelWord} modules, which use
95          {\tt \#if}-defs to invoke the appropriate types and
96          operators.
97
98          Word size also matters for the families of primops for
99          indexing/reading/writing fixed-size quantities at offsets
100          from an array base, address, or foreign pointer.  Here, a
101          slightly different approach is taken.  The names of these
102          primops are fixed, but their {\it types} vary according to
103          the value of {\tt WORD\_SIZE\_IN\_BITS}. For example, if word
104          size is at least 32 bits then an operator like
105          \texttt{indexInt32Array\#} has type {\tt ByteArray\# -> Int\#
106          -> Int\#}; otherwise it has type {\tt ByteArray\# -> Int\# ->
107          Int32\#}.  This approach confines the necessary {\tt
108          \#if}-defs to this file; no conditional compilation is needed
109          in the files that expose these primops.
110
111          Finally, there are strongly deprecated primops for coercing
112          between {\tt Addr\#}, the primitive type of machine
113          addresses, and {\tt Int\#}.  These are pretty bogus anyway,
114          but will work on existing 32-bit and 64-bit GHC targets; they
115          are completely bogus when tag bits are used in {\tt Int\#},
116          so are not available in this case.  }
117         
118 -- Define synonyms for indexing ops. 
119
120 #if WORD_SIZE_IN_BITS < 32 
121 #define INT32 Int32#
122 #define WORD32 Word32#
123 #else
124 #define INT32 Int#
125 #define WORD32 Word#
126 #endif
127
128 #if WORD_SIZE_IN_BITS < 64
129 #define INT64 Int64#
130 #define WORD64 Word64#
131 #else
132 #define INT64 Int#
133 #define WORD64 Word#
134 #endif
135
136 ------------------------------------------------------------------------
137 section "Char#" 
138         {Operations on 31-bit characters.}
139 ------------------------------------------------------------------------
140
141 primtype Char#
142
143 primop   CharGtOp  "gtChar#"   Compare   Char# -> Char# -> Bool
144 primop   CharGeOp  "geChar#"   Compare   Char# -> Char# -> Bool
145
146 primop   CharEqOp  "eqChar#"   Compare
147    Char# -> Char# -> Bool
148    with commutable = True
149
150 primop   CharNeOp  "neChar#"   Compare
151    Char# -> Char# -> Bool
152    with commutable = True
153
154 primop   CharLtOp  "ltChar#"   Compare   Char# -> Char# -> Bool
155 primop   CharLeOp  "leChar#"   Compare   Char# -> Char# -> Bool
156
157 primop   OrdOp   "ord#"  GenPrimOp   Char# -> Int#
158    with code_size = 0
159
160 ------------------------------------------------------------------------
161 section "Int#"
162         {Operations on native-size integers (30+ bits).}
163 ------------------------------------------------------------------------
164
165 primtype Int#
166
167 primop   IntAddOp    "+#"    Dyadic
168    Int# -> Int# -> Int#
169    with commutable = True
170         fixity = infixl 6
171
172 primop   IntSubOp    "-#"    Dyadic   Int# -> Int# -> Int#
173    with fixity = infixl 6
174
175 primop   IntMulOp    "*#" 
176    Dyadic   Int# -> Int# -> Int#
177    {Low word of signed integer multiply.}
178    with commutable = True
179         fixity = infixl 7
180
181 primop   IntMulMayOfloOp  "mulIntMayOflo#" 
182    Dyadic   Int# -> Int# -> Int#
183    {Return non-zero if there is any possibility that the upper word of a
184     signed integer multiply might contain useful information.  Return
185     zero only if you are completely sure that no overflow can occur.
186     On a 32-bit platform, the recommmended implementation is to do a 
187     32 x 32 -> 64 signed multiply, and subtract result[63:32] from
188     (result[31] >>signed 31).  If this is zero, meaning that the 
189     upper word is merely a sign extension of the lower one, no
190     overflow can occur.
191
192     On a 64-bit platform it is not always possible to 
193     acquire the top 64 bits of the result.  Therefore, a recommended 
194     implementation is to take the absolute value of both operands, and 
195     return 0 iff bits[63:31] of them are zero, since that means that their 
196     magnitudes fit within 31 bits, so the magnitude of the product must fit 
197     into 62 bits.
198
199     If in doubt, return non-zero, but do make an effort to create the
200     correct answer for small args, since otherwise the performance of
201     \texttt{(*) :: Integer -> Integer -> Integer} will be poor.
202    }
203    with commutable = True
204
205 primop   IntQuotOp    "quotInt#"    Dyadic
206    Int# -> Int# -> Int#
207    {Rounds towards zero.}
208    with can_fail = True
209
210 primop   IntRemOp    "remInt#"    Dyadic
211    Int# -> Int# -> Int#
212    {Satisfies \texttt{(quotInt\# x y) *\# y +\# (remInt\# x y) == x}.}
213    with can_fail = True
214
215 primop   IntQuotRemOp "quotRemInt#"    GenPrimOp
216    Int# -> Int# -> (# Int#, Int# #)
217    {Rounds towards zero.}
218    with can_fail = True
219
220 primop   IntNegOp    "negateInt#"    Monadic   Int# -> Int#
221 primop   IntAddCOp   "addIntC#"    GenPrimOp   Int# -> Int# -> (# Int#, Int# #)
222          {Add with carry.  First member of result is (wrapped) sum; 
223           second member is 0 iff no overflow occured.}
224    with code_size = 2
225
226 primop   IntSubCOp   "subIntC#"    GenPrimOp   Int# -> Int# -> (# Int#, Int# #)
227          {Subtract with carry.  First member of result is (wrapped) difference; 
228           second member is 0 iff no overflow occured.}
229    with code_size = 2
230
231 primop   IntGtOp  ">#"   Compare   Int# -> Int# -> Bool
232    with fixity = infix 4
233
234 primop   IntGeOp  ">=#"   Compare   Int# -> Int# -> Bool
235    with fixity = infix 4
236
237 primop   IntEqOp  "==#"   Compare
238    Int# -> Int# -> Bool
239    with commutable = True
240         fixity = infix 4
241
242 primop   IntNeOp  "/=#"   Compare
243    Int# -> Int# -> Bool
244    with commutable = True
245         fixity = infix 4
246
247 primop   IntLtOp  "<#"   Compare   Int# -> Int# -> Bool
248    with fixity = infix 4
249
250 primop   IntLeOp  "<=#"   Compare   Int# -> Int# -> Bool
251    with fixity = infix 4
252
253 primop   ChrOp   "chr#"   GenPrimOp   Int# -> Char#
254    with code_size = 0
255
256 primop   Int2WordOp "int2Word#" GenPrimOp Int# -> Word#
257    with code_size = 0
258
259 primop   Int2FloatOp   "int2Float#"      GenPrimOp  Int# -> Float#
260 primop   Int2DoubleOp   "int2Double#"          GenPrimOp  Int# -> Double#
261
262 primop   ISllOp   "uncheckedIShiftL#" GenPrimOp  Int# -> Int# -> Int#
263          {Shift left.  Result undefined if shift amount is not
264           in the range 0 to word size - 1 inclusive.}
265 primop   ISraOp   "uncheckedIShiftRA#" GenPrimOp Int# -> Int# -> Int#
266          {Shift right arithmetic.  Result undefined if shift amount is not
267           in the range 0 to word size - 1 inclusive.}
268 primop   ISrlOp   "uncheckedIShiftRL#" GenPrimOp Int# -> Int# -> Int#
269          {Shift right logical.  Result undefined if shift amount is not
270           in the range 0 to word size - 1 inclusive.}
271
272 ------------------------------------------------------------------------
273 section "Word#"
274         {Operations on native-sized unsigned words (30+ bits).}
275 ------------------------------------------------------------------------
276
277 primtype Word#
278
279 primop   WordAddOp   "plusWord#"   Dyadic   Word# -> Word# -> Word#
280    with commutable = True
281
282 -- Returns (# high, low #) (or equivalently, (# carry, low #))
283 primop   WordAdd2Op  "plusWord2#"  GenPrimOp
284    Word# -> Word# -> (# Word#, Word# #)
285    with commutable = True
286
287 primop   WordSubOp   "minusWord#"   Dyadic   Word# -> Word# -> Word#
288
289 primop   WordMulOp   "timesWord#"   Dyadic   Word# -> Word# -> Word#
290    with commutable = True
291
292 -- Returns (# high, low #)
293 primop   WordMul2Op  "timesWord2#"   GenPrimOp
294    Word# -> Word# -> (# Word#, Word# #)
295    with commutable = True
296
297 primop   WordQuotOp   "quotWord#"   Dyadic   Word# -> Word# -> Word#
298    with can_fail = True
299
300 primop   WordRemOp   "remWord#"   Dyadic   Word# -> Word# -> Word#
301    with can_fail = True
302
303 primop   WordQuotRemOp "quotRemWord#" GenPrimOp
304    Word# -> Word# -> (# Word#, Word# #)
305    with can_fail = True
306
307 -- Takes high word of dividend, then low word of dividend, then divisor.
308 -- Requires that high word is not divisible by divisor.
309 primop   WordQuotRem2Op "quotRemWord2#" GenPrimOp
310    Word# -> Word# -> Word# -> (# Word#, Word# #)
311    with can_fail = True
312
313 primop   AndOp   "and#"   Dyadic   Word# -> Word# -> Word#
314    with commutable = True
315
316 primop   OrOp   "or#"   Dyadic   Word# -> Word# -> Word#
317    with commutable = True
318
319 primop   XorOp   "xor#"   Dyadic   Word# -> Word# -> Word#
320    with commutable = True
321
322 primop   NotOp   "not#"   Monadic   Word# -> Word#
323
324 primop   SllOp   "uncheckedShiftL#"   GenPrimOp   Word# -> Int# -> Word#
325          {Shift left logical.   Result undefined if shift amount is not
326           in the range 0 to word size - 1 inclusive.}
327 primop   SrlOp   "uncheckedShiftRL#"   GenPrimOp   Word# -> Int# -> Word#
328          {Shift right logical.   Result undefined if shift  amount is not
329           in the range 0 to word size - 1 inclusive.}
330
331 primop   Word2IntOp   "word2Int#"   GenPrimOp   Word# -> Int#
332    with code_size = 0
333
334 primop   WordGtOp   "gtWord#"   Compare   Word# -> Word# -> Bool
335 primop   WordGeOp   "geWord#"   Compare   Word# -> Word# -> Bool
336 primop   WordEqOp   "eqWord#"   Compare   Word# -> Word# -> Bool
337 primop   WordNeOp   "neWord#"   Compare   Word# -> Word# -> Bool
338 primop   WordLtOp   "ltWord#"   Compare   Word# -> Word# -> Bool
339 primop   WordLeOp   "leWord#"   Compare   Word# -> Word# -> Bool
340
341 primop   PopCnt8Op   "popCnt8#"   Monadic   Word# -> Word#
342     {Count the number of set bits in the lower 8 bits of a word.}
343 primop   PopCnt16Op   "popCnt16#"   Monadic   Word# -> Word#
344     {Count the number of set bits in the lower 16 bits of a word.}
345 primop   PopCnt32Op   "popCnt32#"   Monadic   Word# -> Word#
346     {Count the number of set bits in the lower 32 bits of a word.}
347 primop   PopCnt64Op   "popCnt64#"   GenPrimOp   WORD64 -> Word#
348     {Count the number of set bits in a 64-bit word.}
349 primop   PopCntOp   "popCnt#"   Monadic   Word# -> Word#
350     {Count the number of set bits in a word.}
351
352 ------------------------------------------------------------------------
353 section "Narrowings" 
354         {Explicit narrowing of native-sized ints or words.}
355 ------------------------------------------------------------------------
356
357 primop   Narrow8IntOp      "narrow8Int#"      Monadic   Int# -> Int#
358 primop   Narrow16IntOp     "narrow16Int#"     Monadic   Int# -> Int#
359 primop   Narrow32IntOp     "narrow32Int#"     Monadic   Int# -> Int#
360 primop   Narrow8WordOp     "narrow8Word#"     Monadic   Word# -> Word#
361 primop   Narrow16WordOp    "narrow16Word#"    Monadic   Word# -> Word#
362 primop   Narrow32WordOp    "narrow32Word#"    Monadic   Word# -> Word#
363
364
365 #if WORD_SIZE_IN_BITS < 32
366 ------------------------------------------------------------------------
367 section "Int32#"
368         {Operations on 32-bit integers ({\tt Int32\#}).  This type is only used
369          if plain {\tt Int\#} has less than 32 bits.  In any case, the operations
370          are not primops; they are implemented (if needed) as ccalls instead.}
371 ------------------------------------------------------------------------
372
373 primtype Int32#
374
375 ------------------------------------------------------------------------
376 section "Word32#"
377         {Operations on 32-bit unsigned words. This type is only used 
378          if plain {\tt Word\#} has less than 32 bits. In any case, the operations
379          are not primops; they are implemented (if needed) as ccalls instead.}
380 ------------------------------------------------------------------------
381
382 primtype Word32#
383
384 #endif 
385
386
387 #if WORD_SIZE_IN_BITS < 64
388 ------------------------------------------------------------------------
389 section "Int64#"
390         {Operations on 64-bit unsigned words. This type is only used 
391          if plain {\tt Int\#} has less than 64 bits. In any case, the operations
392          are not primops; they are implemented (if needed) as ccalls instead.}
393 ------------------------------------------------------------------------
394
395 primtype Int64#
396
397 ------------------------------------------------------------------------
398 section "Word64#"
399         {Operations on 64-bit unsigned words. This type is only used 
400          if plain {\tt Word\#} has less than 64 bits. In any case, the operations
401          are not primops; they are implemented (if needed) as ccalls instead.}
402 ------------------------------------------------------------------------
403
404 primtype Word64#
405
406 #endif
407
408 ------------------------------------------------------------------------
409 section "Double#"
410         {Operations on double-precision (64 bit) floating-point numbers.}
411 ------------------------------------------------------------------------
412
413 primtype Double#
414
415 primop   DoubleGtOp ">##"   Compare   Double# -> Double# -> Bool
416    with fixity = infix 4
417
418 primop   DoubleGeOp ">=##"   Compare   Double# -> Double# -> Bool
419    with fixity = infix 4
420
421 primop DoubleEqOp "==##"   Compare
422    Double# -> Double# -> Bool
423    with commutable = True
424         fixity = infix 4
425
426 primop DoubleNeOp "/=##"   Compare
427    Double# -> Double# -> Bool
428    with commutable = True
429         fixity = infix 4
430
431 primop   DoubleLtOp "<##"   Compare   Double# -> Double# -> Bool
432    with fixity = infix 4
433
434 primop   DoubleLeOp "<=##"   Compare   Double# -> Double# -> Bool
435    with fixity = infix 4
436
437 primop   DoubleAddOp   "+##"   Dyadic
438    Double# -> Double# -> Double#
439    with commutable = True
440         fixity = infixl 6
441
442 primop   DoubleSubOp   "-##"   Dyadic   Double# -> Double# -> Double#
443    with fixity = infixl 6
444
445 primop   DoubleMulOp   "*##"   Dyadic
446    Double# -> Double# -> Double#
447    with commutable = True
448         fixity = infixl 7
449
450 primop   DoubleDivOp   "/##"   Dyadic
451    Double# -> Double# -> Double#
452    with can_fail = True
453         fixity = infixl 7
454
455 primop   DoubleNegOp   "negateDouble#"  Monadic   Double# -> Double#
456
457 primop   Double2IntOp   "double2Int#"          GenPrimOp  Double# -> Int#
458    {Truncates a {\tt Double#} value to the nearest {\tt Int#}.
459     Results are undefined if the truncation if truncation yields
460     a value outside the range of {\tt Int#}.}
461
462 primop   Double2FloatOp   "double2Float#" GenPrimOp Double# -> Float#
463
464 primop   DoubleExpOp   "expDouble#"      Monadic
465    Double# -> Double#
466    with
467    code_size = { primOpCodeSizeForeignCall }
468
469 primop   DoubleLogOp   "logDouble#"      Monadic         
470    Double# -> Double#
471    with
472    code_size = { primOpCodeSizeForeignCall }
473    can_fail = True
474
475 primop   DoubleSqrtOp   "sqrtDouble#"      Monadic  
476    Double# -> Double#
477    with
478    code_size = { primOpCodeSizeForeignCall }
479
480 primop   DoubleSinOp   "sinDouble#"      Monadic          
481    Double# -> Double#
482    with
483    code_size = { primOpCodeSizeForeignCall }
484
485 primop   DoubleCosOp   "cosDouble#"      Monadic          
486    Double# -> Double#
487    with
488    code_size = { primOpCodeSizeForeignCall }
489
490 primop   DoubleTanOp   "tanDouble#"      Monadic          
491    Double# -> Double#
492    with
493    code_size = { primOpCodeSizeForeignCall }
494
495 primop   DoubleAsinOp   "asinDouble#"      Monadic 
496    Double# -> Double#
497    with
498    code_size = { primOpCodeSizeForeignCall }
499    can_fail = True
500
501 primop   DoubleAcosOp   "acosDouble#"      Monadic  
502    Double# -> Double#
503    with
504    code_size = { primOpCodeSizeForeignCall }
505    can_fail = True
506
507 primop   DoubleAtanOp   "atanDouble#"      Monadic  
508    Double# -> Double#
509    with
510    code_size = { primOpCodeSizeForeignCall }
511
512 primop   DoubleSinhOp   "sinhDouble#"      Monadic  
513    Double# -> Double#
514    with
515    code_size = { primOpCodeSizeForeignCall }
516
517 primop   DoubleCoshOp   "coshDouble#"      Monadic  
518    Double# -> Double#
519    with
520    code_size = { primOpCodeSizeForeignCall }
521
522 primop   DoubleTanhOp   "tanhDouble#"      Monadic  
523    Double# -> Double#
524    with
525    code_size = { primOpCodeSizeForeignCall }
526
527 primop   DoublePowerOp   "**##" Dyadic  
528    Double# -> Double# -> Double#
529    {Exponentiation.}
530    with
531    code_size = { primOpCodeSizeForeignCall }
532
533 primop   DoubleDecode_2IntOp   "decodeDouble_2Int#" GenPrimOp    
534    Double# -> (# Int#, Word#, Word#, Int# #)
535    {Convert to integer.
536     First component of the result is -1 or 1, indicating the sign of the
537     mantissa. The next two are the high and low 32 bits of the mantissa
538     respectively, and the last is the exponent.}
539    with out_of_line = True
540
541 ------------------------------------------------------------------------
542 section "Float#" 
543         {Operations on single-precision (32-bit) floating-point numbers.}
544 ------------------------------------------------------------------------
545
546 primtype Float#
547
548 primop   FloatGtOp  "gtFloat#"   Compare   Float# -> Float# -> Bool
549 primop   FloatGeOp  "geFloat#"   Compare   Float# -> Float# -> Bool
550
551 primop   FloatEqOp  "eqFloat#"   Compare
552    Float# -> Float# -> Bool
553    with commutable = True
554
555 primop   FloatNeOp  "neFloat#"   Compare
556    Float# -> Float# -> Bool
557    with commutable = True
558
559 primop   FloatLtOp  "ltFloat#"   Compare   Float# -> Float# -> Bool
560 primop   FloatLeOp  "leFloat#"   Compare   Float# -> Float# -> Bool
561
562 primop   FloatAddOp   "plusFloat#"      Dyadic            
563    Float# -> Float# -> Float#
564    with commutable = True
565
566 primop   FloatSubOp   "minusFloat#"      Dyadic      Float# -> Float# -> Float#
567
568 primop   FloatMulOp   "timesFloat#"      Dyadic    
569    Float# -> Float# -> Float#
570    with commutable = True
571
572 primop   FloatDivOp   "divideFloat#"      Dyadic  
573    Float# -> Float# -> Float#
574    with can_fail = True
575
576 primop   FloatNegOp   "negateFloat#"      Monadic    Float# -> Float#
577
578 primop   Float2IntOp   "float2Int#"      GenPrimOp  Float# -> Int#
579    {Truncates a {\tt Float#} value to the nearest {\tt Int#}.
580     Results are undefined if the truncation if truncation yields
581     a value outside the range of {\tt Int#}.}
582
583 primop   FloatExpOp   "expFloat#"      Monadic          
584    Float# -> Float#
585    with
586    code_size = { primOpCodeSizeForeignCall }
587
588 primop   FloatLogOp   "logFloat#"      Monadic          
589    Float# -> Float#
590    with
591    code_size = { primOpCodeSizeForeignCall }
592    can_fail = True
593
594 primop   FloatSqrtOp   "sqrtFloat#"      Monadic          
595    Float# -> Float#
596    with
597    code_size = { primOpCodeSizeForeignCall }
598
599 primop   FloatSinOp   "sinFloat#"      Monadic          
600    Float# -> Float#
601    with
602    code_size = { primOpCodeSizeForeignCall }
603
604 primop   FloatCosOp   "cosFloat#"      Monadic          
605    Float# -> Float#
606    with
607    code_size = { primOpCodeSizeForeignCall }
608
609 primop   FloatTanOp   "tanFloat#"      Monadic          
610    Float# -> Float#
611    with
612    code_size = { primOpCodeSizeForeignCall }
613
614 primop   FloatAsinOp   "asinFloat#"      Monadic          
615    Float# -> Float#
616    with
617    code_size = { primOpCodeSizeForeignCall }
618    can_fail = True
619
620 primop   FloatAcosOp   "acosFloat#"      Monadic          
621    Float# -> Float#
622    with
623    code_size = { primOpCodeSizeForeignCall }
624    can_fail = True
625
626 primop   FloatAtanOp   "atanFloat#"      Monadic          
627    Float# -> Float#
628    with
629    code_size = { primOpCodeSizeForeignCall }
630
631 primop   FloatSinhOp   "sinhFloat#"      Monadic          
632    Float# -> Float#
633    with
634    code_size = { primOpCodeSizeForeignCall }
635
636 primop   FloatCoshOp   "coshFloat#"      Monadic          
637    Float# -> Float#
638    with
639    code_size = { primOpCodeSizeForeignCall }
640
641 primop   FloatTanhOp   "tanhFloat#"      Monadic          
642    Float# -> Float#
643    with
644    code_size = { primOpCodeSizeForeignCall }
645
646 primop   FloatPowerOp   "powerFloat#"      Dyadic   
647    Float# -> Float# -> Float#
648    with
649    code_size = { primOpCodeSizeForeignCall }
650
651 primop   Float2DoubleOp   "float2Double#" GenPrimOp  Float# -> Double#
652
653 primop   FloatDecode_IntOp   "decodeFloat_Int#" GenPrimOp
654    Float# -> (# Int#, Int# #)
655    {Convert to integers.
656     First {\tt Int\#} in result is the mantissa; second is the exponent.}
657    with out_of_line = True
658
659 ------------------------------------------------------------------------
660 section "Arrays"
661         {Operations on {\tt Array\#}.}
662 ------------------------------------------------------------------------
663
664 primtype Array# a
665
666 primtype MutableArray# s a
667
668 primop  NewArrayOp "newArray#" GenPrimOp
669    Int# -> a -> State# s -> (# State# s, MutableArray# s a #)
670    {Create a new mutable array with the specified number of elements,
671     in the specified state thread,
672     with each element containing the specified initial value.}
673    with
674    out_of_line = True
675    has_side_effects = True
676
677 primop  SameMutableArrayOp "sameMutableArray#" GenPrimOp
678    MutableArray# s a -> MutableArray# s a -> Bool
679
680 primop  ReadArrayOp "readArray#" GenPrimOp
681    MutableArray# s a -> Int# -> State# s -> (# State# s, a #)
682    {Read from specified index of mutable array. Result is not yet evaluated.}
683    with
684    has_side_effects = True
685    can_fail         = True
686
687 primop  WriteArrayOp "writeArray#" GenPrimOp
688    MutableArray# s a -> Int# -> a -> State# s -> State# s
689    {Write to specified index of mutable array.}
690    with
691    has_side_effects = True
692    can_fail         = True
693    code_size        = 2 -- card update too
694
695 primop  SizeofArrayOp "sizeofArray#" GenPrimOp
696    Array# a -> Int#
697    {Return the number of elements in the array.}
698
699 primop  SizeofMutableArrayOp "sizeofMutableArray#" GenPrimOp
700    MutableArray# s a -> Int#
701    {Return the number of elements in the array.}
702
703 primop  IndexArrayOp "indexArray#" GenPrimOp
704    Array# a -> Int# -> (# a #)
705    {Read from specified index of immutable array. Result is packaged into
706     an unboxed singleton; the result itself is not yet evaluated.}
707    with
708    can_fail         = True
709
710 primop  UnsafeFreezeArrayOp "unsafeFreezeArray#" GenPrimOp
711    MutableArray# s a -> State# s -> (# State# s, Array# a #)
712    {Make a mutable array immutable, without copying.}
713    with
714    has_side_effects = True
715
716 primop  UnsafeThawArrayOp  "unsafeThawArray#" GenPrimOp
717    Array# a -> State# s -> (# State# s, MutableArray# s a #)
718    {Make an immutable array mutable, without copying.}
719    with
720    out_of_line = True
721    has_side_effects = True
722
723 primop  CopyArrayOp "copyArray#" GenPrimOp
724   Array# a -> Int# -> MutableArray# s a -> Int# -> Int# -> State# s -> State# s
725   {Copy a range of the Array# to the specified region in the MutableArray#.
726    Both arrays must fully contain the specified ranges, but this is not checked.
727    The two arrays must not be the same array in different states, but this is not checked either.}
728   with
729   has_side_effects = True
730   can_fail         = True
731   code_size = { primOpCodeSizeForeignCall + 4 }
732
733 primop  CopyMutableArrayOp "copyMutableArray#" GenPrimOp
734   MutableArray# s a -> Int# -> MutableArray# s a -> Int# -> Int# -> State# s -> State# s
735   {Copy a range of the first MutableArray# to the specified region in the second MutableArray#.
736    Both arrays must fully contain the specified ranges, but this is not checked.}
737   with
738   has_side_effects = True
739   can_fail         = True
740   code_size = { primOpCodeSizeForeignCall + 4 }
741
742 primop  CloneArrayOp "cloneArray#" GenPrimOp
743   Array# a -> Int# -> Int# -> Array# a
744   {Return a newly allocated Array# with the specified subrange of the provided Array#. 
745    The provided Array# should contain the full subrange specified by the two Int#s, but this is not checked.}
746   with
747   has_side_effects = True
748   code_size = { primOpCodeSizeForeignCall + 4 }
749
750 primop  CloneMutableArrayOp "cloneMutableArray#" GenPrimOp
751   MutableArray# s a -> Int# -> Int# -> State# s -> (# State# s, MutableArray# s a #)
752   {Return a newly allocated Array# with the specified subrange of the provided Array#.
753    The provided MutableArray# should contain the full subrange specified by the two Int#s, but this is not checked.}
754   with
755   has_side_effects = True
756   code_size = { primOpCodeSizeForeignCall + 4 }
757
758 primop  FreezeArrayOp "freezeArray#" GenPrimOp
759   MutableArray# s a -> Int# -> Int# -> State# s -> (# State# s, Array# a #)
760   {Return a newly allocated Array# with the specified subrange of the provided MutableArray#.
761    The provided MutableArray# should contain the full subrange specified by the two Int#s, but this is not checked.}
762   with
763   has_side_effects = True
764   code_size = { primOpCodeSizeForeignCall + 4 }
765
766 primop  ThawArrayOp "thawArray#" GenPrimOp
767   Array# a -> Int# -> Int# -> State# s -> (# State# s, MutableArray# s a #)
768   {Return a newly allocated Array# with the specified subrange of the provided MutableArray#.
769    The provided Array# should contain the full subrange specified by the two Int#s, but this is not checked.}
770   with
771   has_side_effects = True
772   code_size = { primOpCodeSizeForeignCall + 4 }
773
774 ------------------------------------------------------------------------
775 section "Byte Arrays"
776         {Operations on {\tt ByteArray\#}. A {\tt ByteArray\#} is a just a region of
777          raw memory in the garbage-collected heap, which is not
778          scanned for pointers. It carries its own size (in bytes).
779          There are
780          three sets of operations for accessing byte array contents:
781          index for reading from immutable byte arrays, and read/write
782          for mutable byte arrays.  Each set contains operations for a
783          range of useful primitive data types.  Each operation takes
784          an offset measured in terms of the size of the primitive type
785          being read or written.}
786
787 ------------------------------------------------------------------------
788
789 primtype ByteArray#
790
791 primtype MutableByteArray# s
792
793 primop  NewByteArrayOp_Char "newByteArray#" GenPrimOp
794    Int# -> State# s -> (# State# s, MutableByteArray# s #)
795    {Create a new mutable byte array of specified size (in bytes), in
796     the specified state thread.}
797    with out_of_line = True
798         has_side_effects = True
799
800 primop  NewPinnedByteArrayOp_Char "newPinnedByteArray#" GenPrimOp
801    Int# -> State# s -> (# State# s, MutableByteArray# s #)
802    {Create a mutable byte array that the GC guarantees not to move.}
803    with out_of_line = True
804         has_side_effects = True
805
806 primop  NewAlignedPinnedByteArrayOp_Char "newAlignedPinnedByteArray#" GenPrimOp
807    Int# -> Int# -> State# s -> (# State# s, MutableByteArray# s #)
808    {Create a mutable byte array, aligned by the specified amount, that the GC guarantees not to move.}
809    with out_of_line = True
810         has_side_effects = True
811
812 primop  ByteArrayContents_Char "byteArrayContents#" GenPrimOp
813    ByteArray# -> Addr#
814    {Intended for use with pinned arrays; otherwise very unsafe!}
815
816 primop  SameMutableByteArrayOp "sameMutableByteArray#" GenPrimOp
817    MutableByteArray# s -> MutableByteArray# s -> Bool
818
819 primop  UnsafeFreezeByteArrayOp "unsafeFreezeByteArray#" GenPrimOp
820    MutableByteArray# s -> State# s -> (# State# s, ByteArray# #)
821    {Make a mutable byte array immutable, without copying.}
822    with
823    has_side_effects = True
824
825 primop  SizeofByteArrayOp "sizeofByteArray#" GenPrimOp  
826    ByteArray# -> Int#
827    {Return the size of the array in bytes.}
828
829 primop  SizeofMutableByteArrayOp "sizeofMutableByteArray#" GenPrimOp
830    MutableByteArray# s -> Int#
831    {Return the size of the array in bytes.}
832
833 primop IndexByteArrayOp_Char "indexCharArray#" GenPrimOp
834    ByteArray# -> Int# -> Char#
835    {Read 8-bit character; offset in bytes.}
836    with can_fail = True
837
838 primop IndexByteArrayOp_WideChar "indexWideCharArray#" GenPrimOp
839    ByteArray# -> Int# -> Char#
840    {Read 31-bit character; offset in 4-byte words.}
841    with can_fail = True
842
843 primop IndexByteArrayOp_Int "indexIntArray#" GenPrimOp
844    ByteArray# -> Int# -> Int#
845    with can_fail = True
846
847 primop IndexByteArrayOp_Word "indexWordArray#" GenPrimOp
848    ByteArray# -> Int# -> Word#
849    with can_fail = True
850
851 primop IndexByteArrayOp_Addr "indexAddrArray#" GenPrimOp
852    ByteArray# -> Int# -> Addr#
853    with can_fail = True
854
855 primop IndexByteArrayOp_Float "indexFloatArray#" GenPrimOp
856    ByteArray# -> Int# -> Float#
857    with can_fail = True
858
859 primop IndexByteArrayOp_Double "indexDoubleArray#" GenPrimOp
860    ByteArray# -> Int# -> Double#
861    with can_fail = True
862
863 primop IndexByteArrayOp_StablePtr "indexStablePtrArray#" GenPrimOp
864    ByteArray# -> Int# -> StablePtr# a
865    with can_fail = True
866
867 primop IndexByteArrayOp_Int8 "indexInt8Array#" GenPrimOp
868    ByteArray# -> Int# -> Int#
869    with can_fail = True
870
871 primop IndexByteArrayOp_Int16 "indexInt16Array#" GenPrimOp
872    ByteArray# -> Int# -> Int#
873    with can_fail = True
874
875 primop IndexByteArrayOp_Int32 "indexInt32Array#" GenPrimOp
876    ByteArray# -> Int# -> INT32
877    with can_fail = True
878
879 primop IndexByteArrayOp_Int64 "indexInt64Array#" GenPrimOp
880    ByteArray# -> Int# -> INT64
881    with can_fail = True
882
883 primop IndexByteArrayOp_Word8 "indexWord8Array#" GenPrimOp
884    ByteArray# -> Int# -> Word#
885    with can_fail = True
886
887 primop IndexByteArrayOp_Word16 "indexWord16Array#" GenPrimOp
888    ByteArray# -> Int# -> Word#
889    with can_fail = True
890
891 primop IndexByteArrayOp_Word32 "indexWord32Array#" GenPrimOp
892    ByteArray# -> Int# -> WORD32
893    with can_fail = True
894
895 primop IndexByteArrayOp_Word64 "indexWord64Array#" GenPrimOp
896    ByteArray# -> Int# -> WORD64
897    with can_fail = True
898
899 primop  ReadByteArrayOp_Char "readCharArray#" GenPrimOp
900    MutableByteArray# s -> Int# -> State# s -> (# State# s, Char# #)
901    {Read 8-bit character; offset in bytes.}
902    with has_side_effects = True
903         can_fail = True
904
905 primop  ReadByteArrayOp_WideChar "readWideCharArray#" GenPrimOp
906    MutableByteArray# s -> Int# -> State# s -> (# State# s, Char# #)
907    {Read 31-bit character; offset in 4-byte words.}
908    with has_side_effects = True
909         can_fail = True
910
911 primop  ReadByteArrayOp_Int "readIntArray#" GenPrimOp
912    MutableByteArray# s -> Int# -> State# s -> (# State# s, Int# #)
913    with has_side_effects = True
914         can_fail = True
915
916 primop  ReadByteArrayOp_Word "readWordArray#" GenPrimOp
917    MutableByteArray# s -> Int# -> State# s -> (# State# s, Word# #)
918    with has_side_effects = True
919         can_fail = True
920
921 primop  ReadByteArrayOp_Addr "readAddrArray#" GenPrimOp
922    MutableByteArray# s -> Int# -> State# s -> (# State# s, Addr# #)
923    with has_side_effects = True
924         can_fail = True
925
926 primop  ReadByteArrayOp_Float "readFloatArray#" GenPrimOp
927    MutableByteArray# s -> Int# -> State# s -> (# State# s, Float# #)
928    with has_side_effects = True
929         can_fail = True
930
931 primop  ReadByteArrayOp_Double "readDoubleArray#" GenPrimOp
932    MutableByteArray# s -> Int# -> State# s -> (# State# s, Double# #)
933    with has_side_effects = True
934         can_fail = True
935
936 primop  ReadByteArrayOp_StablePtr "readStablePtrArray#" GenPrimOp
937    MutableByteArray# s -> Int# -> State# s -> (# State# s, StablePtr# a #)
938    with has_side_effects = True
939         can_fail = True
940
941 primop  ReadByteArrayOp_Int8 "readInt8Array#" GenPrimOp
942    MutableByteArray# s -> Int# -> State# s -> (# State# s, Int# #)
943    with has_side_effects = True
944         can_fail = True
945
946 primop  ReadByteArrayOp_Int16 "readInt16Array#" GenPrimOp
947    MutableByteArray# s -> Int# -> State# s -> (# State# s, Int# #)
948    with has_side_effects = True
949         can_fail = True
950
951 primop  ReadByteArrayOp_Int32 "readInt32Array#" GenPrimOp
952    MutableByteArray# s -> Int# -> State# s -> (# State# s, INT32 #)
953    with has_side_effects = True
954         can_fail = True
955
956 primop  ReadByteArrayOp_Int64 "readInt64Array#" GenPrimOp
957    MutableByteArray# s -> Int# -> State# s -> (# State# s, INT64 #)
958    with has_side_effects = True
959         can_fail = True
960
961 primop  ReadByteArrayOp_Word8 "readWord8Array#" GenPrimOp
962    MutableByteArray# s -> Int# -> State# s -> (# State# s, Word# #)
963    with has_side_effects = True
964         can_fail = True
965
966 primop  ReadByteArrayOp_Word16 "readWord16Array#" GenPrimOp
967    MutableByteArray# s -> Int# -> State# s -> (# State# s, Word# #)
968    with has_side_effects = True
969         can_fail = True
970
971 primop  ReadByteArrayOp_Word32 "readWord32Array#" GenPrimOp
972    MutableByteArray# s -> Int# -> State# s -> (# State# s, WORD32 #)
973    with has_side_effects = True
974         can_fail = True
975
976 primop  ReadByteArrayOp_Word64 "readWord64Array#" GenPrimOp
977    MutableByteArray# s -> Int# -> State# s -> (# State# s, WORD64 #)
978    with has_side_effects = True
979         can_fail = True
980
981 primop  WriteByteArrayOp_Char "writeCharArray#" GenPrimOp
982    MutableByteArray# s -> Int# -> Char# -> State# s -> State# s
983    {Write 8-bit character; offset in bytes.}
984    with has_side_effects = True
985         can_fail = True
986
987 primop  WriteByteArrayOp_WideChar "writeWideCharArray#" GenPrimOp
988    MutableByteArray# s -> Int# -> Char# -> State# s -> State# s
989    {Write 31-bit character; offset in 4-byte words.}
990    with has_side_effects = True
991         can_fail = True
992
993 primop  WriteByteArrayOp_Int "writeIntArray#" GenPrimOp
994    MutableByteArray# s -> Int# -> Int# -> State# s -> State# s
995    with has_side_effects = True
996         can_fail = True
997
998 primop  WriteByteArrayOp_Word "writeWordArray#" GenPrimOp
999    MutableByteArray# s -> Int# -> Word# -> State# s -> State# s
1000    with has_side_effects = True
1001         can_fail = True
1002
1003 primop  WriteByteArrayOp_Addr "writeAddrArray#" GenPrimOp
1004    MutableByteArray# s -> Int# -> Addr# -> State# s -> State# s
1005    with has_side_effects = True
1006         can_fail = True
1007
1008 primop  WriteByteArrayOp_Float "writeFloatArray#" GenPrimOp
1009    MutableByteArray# s -> Int# -> Float# -> State# s -> State# s
1010    with has_side_effects = True
1011         can_fail = True
1012
1013 primop  WriteByteArrayOp_Double "writeDoubleArray#" GenPrimOp
1014    MutableByteArray# s -> Int# -> Double# -> State# s -> State# s
1015    with has_side_effects = True
1016         can_fail = True
1017
1018 primop  WriteByteArrayOp_StablePtr "writeStablePtrArray#" GenPrimOp
1019    MutableByteArray# s -> Int# -> StablePtr# a -> State# s -> State# s
1020    with has_side_effects = True
1021         can_fail = True
1022
1023 primop  WriteByteArrayOp_Int8 "writeInt8Array#" GenPrimOp
1024    MutableByteArray# s -> Int# -> Int# -> State# s -> State# s
1025    with has_side_effects = True
1026         can_fail = True
1027
1028 primop  WriteByteArrayOp_Int16 "writeInt16Array#" GenPrimOp
1029    MutableByteArray# s -> Int# -> Int# -> State# s -> State# s
1030    with has_side_effects = True
1031         can_fail = True
1032
1033 primop  WriteByteArrayOp_Int32 "writeInt32Array#" GenPrimOp
1034    MutableByteArray# s -> Int# -> INT32 -> State# s -> State# s
1035    with has_side_effects = True
1036         can_fail = True
1037
1038 primop  WriteByteArrayOp_Int64 "writeInt64Array#" GenPrimOp
1039    MutableByteArray# s -> Int# -> INT64 -> State# s -> State# s
1040    with can_fail = True
1041         has_side_effects = True
1042
1043 primop  WriteByteArrayOp_Word8 "writeWord8Array#" GenPrimOp
1044    MutableByteArray# s -> Int# -> Word# -> State# s -> State# s
1045    with has_side_effects = True
1046         can_fail = True
1047
1048 primop  WriteByteArrayOp_Word16 "writeWord16Array#" GenPrimOp
1049    MutableByteArray# s -> Int# -> Word# -> State# s -> State# s
1050    with has_side_effects = True
1051         can_fail = True
1052
1053 primop  WriteByteArrayOp_Word32 "writeWord32Array#" GenPrimOp
1054    MutableByteArray# s -> Int# -> WORD32 -> State# s -> State# s
1055    with has_side_effects = True
1056         can_fail = True
1057
1058 primop  WriteByteArrayOp_Word64 "writeWord64Array#" GenPrimOp
1059    MutableByteArray# s -> Int# -> WORD64 -> State# s -> State# s
1060    with has_side_effects = True
1061         can_fail = True
1062
1063 primop  CopyByteArrayOp "copyByteArray#" GenPrimOp
1064   ByteArray# -> Int# -> MutableByteArray# s -> Int# -> Int# -> State# s -> State# s
1065   {Copy a range of the ByteArray# to the specified region in the MutableByteArray#.
1066    Both arrays must fully contain the specified ranges, but this is not checked.
1067    The two arrays must not be the same array in different states, but this is not checked either.}
1068   with
1069   has_side_effects = True
1070   code_size = { primOpCodeSizeForeignCall + 4}
1071   can_fail = True
1072
1073 primop  CopyMutableByteArrayOp "copyMutableByteArray#" GenPrimOp
1074   MutableByteArray# s -> Int# -> MutableByteArray# s -> Int# -> Int# -> State# s -> State# s
1075   {Copy a range of the first MutableByteArray# to the specified region in the second MutableByteArray#.
1076    Both arrays must fully contain the specified ranges, but this is not checked.}
1077   with
1078   has_side_effects = True
1079   code_size = { primOpCodeSizeForeignCall + 4 }
1080   can_fail = True
1081
1082 primop  SetByteArrayOp "setByteArray#" GenPrimOp
1083   MutableByteArray# s -> Int# -> Int# -> Int# -> State# s -> State# s
1084   {Set the range of the MutableByteArray# to the specified character.}
1085   with
1086   has_side_effects = True
1087   code_size = { primOpCodeSizeForeignCall + 4 }
1088   can_fail = True
1089
1090 ------------------------------------------------------------------------
1091 section "Arrays of arrays"
1092         {Operations on {\tt ArrayArray\#}. An {\tt ArrayArray\#} contains references to {\em unpointed}
1093          arrays, such as {\tt ByteArray\#s}. Hence, it is not parameterised by the element types,
1094          just like a {\tt ByteArray\#}, but it needs to be scanned during GC, just like an {\tt Array#}.
1095          We represent an {\tt ArrayArray\#} exactly as a {\tt Array\#}, but provide element-type-specific
1096          indexing, reading, and writing.}
1097 ------------------------------------------------------------------------
1098
1099 primtype ArrayArray#
1100
1101 primtype MutableArrayArray# s
1102
1103 primop  NewArrayArrayOp "newArrayArray#" GenPrimOp
1104    Int# -> State# s -> (# State# s, MutableArrayArray# s #)
1105    {Create a new mutable array of arrays with the specified number of elements,
1106     in the specified state thread, with each element recursively referring to the
1107     newly created array.}
1108    with
1109    out_of_line = True
1110    has_side_effects = True
1111
1112 primop  SameMutableArrayArrayOp "sameMutableArrayArray#" GenPrimOp
1113    MutableArrayArray# s -> MutableArrayArray# s -> Bool
1114
1115 primop  UnsafeFreezeArrayArrayOp "unsafeFreezeArrayArray#" GenPrimOp
1116    MutableArrayArray# s -> State# s -> (# State# s, ArrayArray# #)
1117    {Make a mutable array of arrays immutable, without copying.}
1118    with
1119    has_side_effects = True
1120
1121 primop  SizeofArrayArrayOp "sizeofArrayArray#" GenPrimOp
1122    ArrayArray# -> Int#
1123    {Return the number of elements in the array.}
1124
1125 primop  SizeofMutableArrayArrayOp "sizeofMutableArrayArray#" GenPrimOp
1126    MutableArrayArray# s -> Int#
1127    {Return the number of elements in the array.}
1128
1129 primop IndexArrayArrayOp_ByteArray "indexByteArrayArray#" GenPrimOp
1130    ArrayArray# -> Int# -> ByteArray#
1131    with can_fail = True
1132
1133 primop IndexArrayArrayOp_ArrayArray "indexArrayArrayArray#" GenPrimOp
1134    ArrayArray# -> Int# -> ArrayArray#
1135    with can_fail = True
1136
1137 primop  ReadArrayArrayOp_ByteArray "readByteArrayArray#" GenPrimOp
1138    MutableArrayArray# s -> Int# -> State# s -> (# State# s, ByteArray# #)
1139    with has_side_effects = True
1140         can_fail = True
1141
1142 primop  ReadArrayArrayOp_MutableByteArray "readMutableByteArrayArray#" GenPrimOp
1143    MutableArrayArray# s -> Int# -> State# s -> (# State# s, MutableByteArray# s #)
1144    with has_side_effects = True
1145         can_fail = True
1146
1147 primop  ReadArrayArrayOp_ArrayArray "readArrayArrayArray#" GenPrimOp
1148    MutableArrayArray# s -> Int# -> State# s -> (# State# s, ArrayArray# #)
1149    with has_side_effects = True
1150         can_fail = True
1151
1152 primop  ReadArrayArrayOp_MutableArrayArray "readMutableArrayArrayArray#" GenPrimOp
1153    MutableArrayArray# s -> Int# -> State# s -> (# State# s, MutableArrayArray# s #)
1154    with has_side_effects = True
1155         can_fail = True
1156
1157 primop  WriteArrayArrayOp_ByteArray "writeByteArrayArray#" GenPrimOp
1158    MutableArrayArray# s -> Int# -> ByteArray# -> State# s -> State# s
1159    with has_side_effects = True
1160         can_fail = True
1161
1162 primop  WriteArrayArrayOp_MutableByteArray "writeMutableByteArrayArray#" GenPrimOp
1163    MutableArrayArray# s -> Int# -> MutableByteArray# s -> State# s -> State# s
1164    with has_side_effects = True
1165         can_fail = True
1166
1167 primop  WriteArrayArrayOp_ArrayArray "writeArrayArrayArray#" GenPrimOp
1168    MutableArrayArray# s -> Int# -> ArrayArray# -> State# s -> State# s
1169    with has_side_effects = True
1170         can_fail = True
1171
1172 primop  WriteArrayArrayOp_MutableArrayArray "writeMutableArrayArrayArray#" GenPrimOp
1173    MutableArrayArray# s -> Int# -> MutableArrayArray# s -> State# s -> State# s
1174    with has_side_effects = True
1175         can_fail = True
1176
1177 primop  CopyArrayArrayOp "copyArrayArray#" GenPrimOp
1178   ArrayArray# -> Int# -> MutableArrayArray# s -> Int# -> Int# -> State# s -> State# s
1179   {Copy a range of the ArrayArray# to the specified region in the MutableArrayArray#.
1180    Both arrays must fully contain the specified ranges, but this is not checked.
1181    The two arrays must not be the same array in different states, but this is not checked either.}
1182   with
1183   has_side_effects = True
1184   can_fail = True
1185   code_size = { primOpCodeSizeForeignCall }
1186
1187 primop  CopyMutableArrayArrayOp "copyMutableArrayArray#" GenPrimOp
1188   MutableArrayArray# s -> Int# -> MutableArrayArray# s -> Int# -> Int# -> State# s -> State# s
1189   {Copy a range of the first MutableArrayArray# to the specified region in the second
1190    MutableArrayArray#.
1191    Both arrays must fully contain the specified ranges, but this is not checked.}
1192   with
1193   has_side_effects = True
1194   code_size = { primOpCodeSizeForeignCall }
1195   can_fail = True
1196
1197 ------------------------------------------------------------------------
1198 section "Addr#"
1199 ------------------------------------------------------------------------
1200
1201 primtype Addr#
1202         { An arbitrary machine address assumed to point outside
1203          the garbage-collected heap. }
1204
1205 pseudoop "nullAddr#" Addr#
1206         { The null address. }
1207
1208 primop   AddrAddOp "plusAddr#" GenPrimOp Addr# -> Int# -> Addr#
1209 primop   AddrSubOp "minusAddr#" GenPrimOp Addr# -> Addr# -> Int#
1210          {Result is meaningless if two {\tt Addr\#}s are so far apart that their
1211          difference doesn't fit in an {\tt Int\#}.}
1212 primop   AddrRemOp "remAddr#" GenPrimOp Addr# -> Int# -> Int#
1213          {Return the remainder when the {\tt Addr\#} arg, treated like an {\tt Int\#},
1214           is divided by the {\tt Int\#} arg.}
1215 #if (WORD_SIZE_IN_BITS == 32 || WORD_SIZE_IN_BITS == 64)
1216 primop   Addr2IntOp  "addr2Int#"     GenPrimOp   Addr# -> Int#
1217         {Coerce directly from address to int. Strongly deprecated.}
1218    with code_size = 0
1219 primop   Int2AddrOp   "int2Addr#"    GenPrimOp  Int# -> Addr#
1220         {Coerce directly from int to address. Strongly deprecated.}
1221    with code_size = 0
1222 #endif
1223
1224 primop   AddrGtOp  "gtAddr#"   Compare   Addr# -> Addr# -> Bool
1225 primop   AddrGeOp  "geAddr#"   Compare   Addr# -> Addr# -> Bool
1226 primop   AddrEqOp  "eqAddr#"   Compare   Addr# -> Addr# -> Bool
1227 primop   AddrNeOp  "neAddr#"   Compare   Addr# -> Addr# -> Bool
1228 primop   AddrLtOp  "ltAddr#"   Compare   Addr# -> Addr# -> Bool
1229 primop   AddrLeOp  "leAddr#"   Compare   Addr# -> Addr# -> Bool
1230
1231 primop IndexOffAddrOp_Char "indexCharOffAddr#" GenPrimOp
1232    Addr# -> Int# -> Char#
1233    {Reads 8-bit character; offset in bytes.}
1234    with can_fail = True
1235
1236 primop IndexOffAddrOp_WideChar "indexWideCharOffAddr#" GenPrimOp
1237    Addr# -> Int# -> Char#
1238    {Reads 31-bit character; offset in 4-byte words.}
1239    with can_fail = True
1240
1241 primop IndexOffAddrOp_Int "indexIntOffAddr#" GenPrimOp
1242    Addr# -> Int# -> Int#
1243    with can_fail = True
1244
1245 primop IndexOffAddrOp_Word "indexWordOffAddr#" GenPrimOp
1246    Addr# -> Int# -> Word#
1247    with can_fail = True
1248
1249 primop IndexOffAddrOp_Addr "indexAddrOffAddr#" GenPrimOp
1250    Addr# -> Int# -> Addr#
1251    with can_fail = True
1252
1253 primop IndexOffAddrOp_Float "indexFloatOffAddr#" GenPrimOp
1254    Addr# -> Int# -> Float#
1255    with can_fail = True
1256
1257 primop IndexOffAddrOp_Double "indexDoubleOffAddr#" GenPrimOp
1258    Addr# -> Int# -> Double#
1259    with can_fail = True
1260
1261 primop IndexOffAddrOp_StablePtr "indexStablePtrOffAddr#" GenPrimOp
1262    Addr# -> Int# -> StablePtr# a
1263    with can_fail = True
1264
1265 primop IndexOffAddrOp_Int8 "indexInt8OffAddr#" GenPrimOp
1266    Addr# -> Int# -> Int#
1267    with can_fail = True
1268
1269 primop IndexOffAddrOp_Int16 "indexInt16OffAddr#" GenPrimOp
1270    Addr# -> Int# -> Int#
1271    with can_fail = True
1272
1273 primop IndexOffAddrOp_Int32 "indexInt32OffAddr#" GenPrimOp
1274    Addr# -> Int# -> INT32
1275    with can_fail = True
1276
1277 primop IndexOffAddrOp_Int64 "indexInt64OffAddr#" GenPrimOp
1278    Addr# -> Int# -> INT64
1279    with can_fail = True
1280
1281 primop IndexOffAddrOp_Word8 "indexWord8OffAddr#" GenPrimOp
1282    Addr# -> Int# -> Word#
1283    with can_fail = True
1284
1285 primop IndexOffAddrOp_Word16 "indexWord16OffAddr#" GenPrimOp
1286    Addr# -> Int# -> Word#
1287    with can_fail = True
1288
1289 primop IndexOffAddrOp_Word32 "indexWord32OffAddr#" GenPrimOp
1290    Addr# -> Int# -> WORD32
1291    with can_fail = True
1292
1293 primop IndexOffAddrOp_Word64 "indexWord64OffAddr#" GenPrimOp
1294    Addr# -> Int# -> WORD64
1295    with can_fail = True
1296
1297 primop ReadOffAddrOp_Char "readCharOffAddr#" GenPrimOp
1298    Addr# -> Int# -> State# s -> (# State# s, Char# #)
1299    {Reads 8-bit character; offset in bytes.}
1300    with has_side_effects = True
1301         can_fail         = True
1302
1303 primop ReadOffAddrOp_WideChar "readWideCharOffAddr#" GenPrimOp
1304    Addr# -> Int# -> State# s -> (# State# s, Char# #)
1305    {Reads 31-bit character; offset in 4-byte words.}
1306    with has_side_effects = True
1307         can_fail         = True
1308
1309 primop ReadOffAddrOp_Int "readIntOffAddr#" GenPrimOp
1310    Addr# -> Int# -> State# s -> (# State# s, Int# #)
1311    with has_side_effects = True
1312         can_fail         = True
1313
1314 primop ReadOffAddrOp_Word "readWordOffAddr#" GenPrimOp
1315    Addr# -> Int# -> State# s -> (# State# s, Word# #)
1316    with has_side_effects = True
1317         can_fail         = True
1318
1319 primop ReadOffAddrOp_Addr "readAddrOffAddr#" GenPrimOp
1320    Addr# -> Int# -> State# s -> (# State# s, Addr# #)
1321    with has_side_effects = True
1322         can_fail         = True
1323
1324 primop ReadOffAddrOp_Float "readFloatOffAddr#" GenPrimOp
1325    Addr# -> Int# -> State# s -> (# State# s, Float# #)
1326    with has_side_effects = True
1327         can_fail         = True
1328
1329 primop ReadOffAddrOp_Double "readDoubleOffAddr#" GenPrimOp
1330    Addr# -> Int# -> State# s -> (# State# s, Double# #)
1331    with has_side_effects = True
1332         can_fail         = True
1333
1334 primop ReadOffAddrOp_StablePtr "readStablePtrOffAddr#" GenPrimOp
1335    Addr# -> Int# -> State# s -> (# State# s, StablePtr# a #)
1336    with has_side_effects = True
1337         can_fail         = True
1338
1339 primop ReadOffAddrOp_Int8 "readInt8OffAddr#" GenPrimOp
1340    Addr# -> Int# -> State# s -> (# State# s, Int# #)
1341    with has_side_effects = True
1342         can_fail         = True
1343
1344 primop ReadOffAddrOp_Int16 "readInt16OffAddr#" GenPrimOp
1345    Addr# -> Int# -> State# s -> (# State# s, Int# #)
1346    with has_side_effects = True
1347         can_fail         = True
1348
1349 primop ReadOffAddrOp_Int32 "readInt32OffAddr#" GenPrimOp
1350    Addr# -> Int# -> State# s -> (# State# s, INT32 #)
1351    with has_side_effects = True
1352         can_fail         = True
1353
1354 primop ReadOffAddrOp_Int64 "readInt64OffAddr#" GenPrimOp
1355    Addr# -> Int# -> State# s -> (# State# s, INT64 #)
1356    with has_side_effects = True
1357         can_fail         = True
1358
1359 primop ReadOffAddrOp_Word8 "readWord8OffAddr#" GenPrimOp
1360    Addr# -> Int# -> State# s -> (# State# s, Word# #)
1361    with has_side_effects = True
1362         can_fail         = True
1363
1364 primop ReadOffAddrOp_Word16 "readWord16OffAddr#" GenPrimOp
1365    Addr# -> Int# -> State# s -> (# State# s, Word# #)
1366    with has_side_effects = True
1367         can_fail         = True
1368
1369 primop ReadOffAddrOp_Word32 "readWord32OffAddr#" GenPrimOp
1370    Addr# -> Int# -> State# s -> (# State# s, WORD32 #)
1371    with has_side_effects = True
1372         can_fail         = True
1373
1374 primop ReadOffAddrOp_Word64 "readWord64OffAddr#" GenPrimOp
1375    Addr# -> Int# -> State# s -> (# State# s, WORD64 #)
1376    with has_side_effects = True
1377         can_fail         = True
1378
1379 primop  WriteOffAddrOp_Char "writeCharOffAddr#" GenPrimOp
1380    Addr# -> Int# -> Char# -> State# s -> State# s
1381    with has_side_effects = True
1382         can_fail         = True
1383
1384 primop  WriteOffAddrOp_WideChar "writeWideCharOffAddr#" GenPrimOp
1385    Addr# -> Int# -> Char# -> State# s -> State# s
1386    with has_side_effects = True
1387         can_fail         = True
1388
1389 primop  WriteOffAddrOp_Int "writeIntOffAddr#" GenPrimOp
1390    Addr# -> Int# -> Int# -> State# s -> State# s
1391    with has_side_effects = True
1392         can_fail         = True
1393
1394 primop  WriteOffAddrOp_Word "writeWordOffAddr#" GenPrimOp
1395    Addr# -> Int# -> Word# -> State# s -> State# s
1396    with has_side_effects = True
1397         can_fail         = True
1398
1399 primop  WriteOffAddrOp_Addr "writeAddrOffAddr#" GenPrimOp
1400    Addr# -> Int# -> Addr# -> State# s -> State# s
1401    with has_side_effects = True
1402         can_fail         = True
1403
1404 primop  WriteOffAddrOp_Float "writeFloatOffAddr#" GenPrimOp
1405    Addr# -> Int# -> Float# -> State# s -> State# s
1406    with has_side_effects = True
1407         can_fail         = True
1408
1409 primop  WriteOffAddrOp_Double "writeDoubleOffAddr#" GenPrimOp
1410    Addr# -> Int# -> Double# -> State# s -> State# s
1411    with has_side_effects = True
1412         can_fail         = True
1413
1414 primop  WriteOffAddrOp_StablePtr "writeStablePtrOffAddr#" GenPrimOp
1415    Addr# -> Int# -> StablePtr# a -> State# s -> State# s
1416    with has_side_effects = True
1417         can_fail         = True
1418
1419 primop  WriteOffAddrOp_Int8 "writeInt8OffAddr#" GenPrimOp
1420    Addr# -> Int# -> Int# -> State# s -> State# s
1421    with has_side_effects = True
1422         can_fail         = True
1423
1424 primop  WriteOffAddrOp_Int16 "writeInt16OffAddr#" GenPrimOp
1425    Addr# -> Int# -> Int# -> State# s -> State# s
1426    with has_side_effects = True
1427         can_fail         = True
1428
1429 primop  WriteOffAddrOp_Int32 "writeInt32OffAddr#" GenPrimOp
1430    Addr# -> Int# -> INT32 -> State# s -> State# s
1431    with has_side_effects = True
1432         can_fail         = True
1433
1434 primop  WriteOffAddrOp_Int64 "writeInt64OffAddr#" GenPrimOp
1435    Addr# -> Int# -> INT64 -> State# s -> State# s
1436    with has_side_effects = True
1437         can_fail         = True
1438
1439 primop  WriteOffAddrOp_Word8 "writeWord8OffAddr#" GenPrimOp
1440    Addr# -> Int# -> Word# -> State# s -> State# s
1441    with has_side_effects = True
1442         can_fail         = True
1443
1444 primop  WriteOffAddrOp_Word16 "writeWord16OffAddr#" GenPrimOp
1445    Addr# -> Int# -> Word# -> State# s -> State# s
1446    with has_side_effects = True
1447         can_fail         = True
1448
1449 primop  WriteOffAddrOp_Word32 "writeWord32OffAddr#" GenPrimOp
1450    Addr# -> Int# -> WORD32 -> State# s -> State# s
1451    with has_side_effects = True
1452         can_fail         = True
1453
1454 primop  WriteOffAddrOp_Word64 "writeWord64OffAddr#" GenPrimOp
1455    Addr# -> Int# -> WORD64 -> State# s -> State# s
1456    with has_side_effects = True
1457         can_fail         = True
1458
1459 ------------------------------------------------------------------------
1460 section "Mutable variables"
1461         {Operations on MutVar\#s.}
1462 ------------------------------------------------------------------------
1463
1464 primtype MutVar# s a
1465         {A {\tt MutVar\#} behaves like a single-element mutable array.}
1466
1467 primop  NewMutVarOp "newMutVar#" GenPrimOp
1468    a -> State# s -> (# State# s, MutVar# s a #)
1469    {Create {\tt MutVar\#} with specified initial value in specified state thread.}
1470    with
1471    out_of_line = True
1472    has_side_effects = True
1473
1474 primop  ReadMutVarOp "readMutVar#" GenPrimOp
1475    MutVar# s a -> State# s -> (# State# s, a #)
1476    {Read contents of {\tt MutVar\#}. Result is not yet evaluated.}
1477    with
1478    has_side_effects = True
1479    can_fail         = True
1480
1481 primop  WriteMutVarOp "writeMutVar#"  GenPrimOp
1482    MutVar# s a -> a -> State# s -> State# s
1483    {Write contents of {\tt MutVar\#}.}
1484    with
1485    has_side_effects = True
1486    code_size = { primOpCodeSizeForeignCall } -- for the write barrier
1487    can_fail         = True
1488
1489 primop  SameMutVarOp "sameMutVar#" GenPrimOp
1490    MutVar# s a -> MutVar# s a -> Bool
1491
1492 -- not really the right type, but we don't know about pairs here.  The
1493 -- correct type is
1494 --
1495 --   MutVar# s a -> (a -> (a,b)) -> State# s -> (# State# s, b #)
1496 --
1497 primop  AtomicModifyMutVarOp "atomicModifyMutVar#" GenPrimOp
1498    MutVar# s a -> (a -> b) -> State# s -> (# State# s, c #)
1499    with
1500    out_of_line = True
1501    has_side_effects = True
1502    can_fail         = True
1503
1504 primop  CasMutVarOp "casMutVar#" GenPrimOp
1505   MutVar# s a -> a -> a -> State# s -> (# State# s, Int#, a #)
1506    with
1507    out_of_line = True
1508    has_side_effects = True
1509
1510 ------------------------------------------------------------------------
1511 section "Exceptions"
1512 ------------------------------------------------------------------------
1513
1514 primop  CatchOp "catch#" GenPrimOp
1515           (State# RealWorld -> (# State# RealWorld, a #) )
1516        -> (b -> State# RealWorld -> (# State# RealWorld, a #) ) 
1517        -> State# RealWorld
1518        -> (# State# RealWorld, a #)
1519    with
1520         -- Catch is actually strict in its first argument
1521         -- but we don't want to tell the strictness
1522         -- analyser about that!
1523         -- might use caught action multiply
1524    out_of_line = True
1525    has_side_effects = True
1526
1527 primop  RaiseOp "raise#" GenPrimOp
1528    a -> b
1529    with
1530    strictness  = { \ _arity -> mkStrictSig (mkTopDmdType [lazyDmd] BotRes) }
1531       -- NB: result is bottom
1532    out_of_line = True
1533
1534 -- raiseIO# needs to be a primop, because exceptions in the IO monad
1535 -- must be *precise* - we don't want the strictness analyser turning
1536 -- one kind of bottom into another, as it is allowed to do in pure code.
1537 --
1538 -- But we *do* want to know that it returns bottom after 
1539 -- being applied to two arguments, so that this function is strict in y
1540 --     f x y | x>0       = raiseIO blah
1541 --           | y>0       = return 1
1542 --           | otherwise = return 2 
1543
1544 primop  RaiseIOOp "raiseIO#" GenPrimOp
1545    a -> State# RealWorld -> (# State# RealWorld, b #)
1546    with
1547    strictness  = { \ _arity -> mkStrictSig (mkTopDmdType [lazyDmd,lazyDmd] BotRes) }
1548    out_of_line = True
1549    has_side_effects = True
1550
1551 primop  MaskAsyncExceptionsOp "maskAsyncExceptions#" GenPrimOp
1552         (State# RealWorld -> (# State# RealWorld, a #))
1553      -> (State# RealWorld -> (# State# RealWorld, a #))
1554    with
1555    out_of_line = True
1556    has_side_effects = True
1557
1558 primop  MaskUninterruptibleOp "maskUninterruptible#" GenPrimOp
1559         (State# RealWorld -> (# State# RealWorld, a #))
1560      -> (State# RealWorld -> (# State# RealWorld, a #))
1561    with
1562    out_of_line = True
1563    has_side_effects = True
1564
1565 primop  UnmaskAsyncExceptionsOp "unmaskAsyncExceptions#" GenPrimOp
1566         (State# RealWorld -> (# State# RealWorld, a #))
1567      -> (State# RealWorld -> (# State# RealWorld, a #))
1568    with
1569    out_of_line = True
1570    has_side_effects = True
1571
1572 primop  MaskStatus "getMaskingState#" GenPrimOp
1573         State# RealWorld -> (# State# RealWorld, Int# #)
1574    with
1575    out_of_line = True
1576    has_side_effects = True
1577
1578 ------------------------------------------------------------------------
1579 section "STM-accessible Mutable Variables"
1580 ------------------------------------------------------------------------
1581
1582 primtype TVar# s a
1583
1584 primop  AtomicallyOp "atomically#" GenPrimOp
1585       (State# RealWorld -> (# State# RealWorld, a #) )
1586    -> State# RealWorld -> (# State# RealWorld, a #)
1587    with
1588    out_of_line = True
1589    has_side_effects = True
1590
1591 primop  RetryOp "retry#" GenPrimOp
1592    State# RealWorld -> (# State# RealWorld, a #)
1593    with 
1594    out_of_line = True
1595    has_side_effects = True
1596
1597 primop  CatchRetryOp "catchRetry#" GenPrimOp
1598       (State# RealWorld -> (# State# RealWorld, a #) )
1599    -> (State# RealWorld -> (# State# RealWorld, a #) )
1600    -> (State# RealWorld -> (# State# RealWorld, a #) )
1601    with 
1602    out_of_line = True
1603    has_side_effects = True
1604
1605 primop  CatchSTMOp "catchSTM#" GenPrimOp
1606       (State# RealWorld -> (# State# RealWorld, a #) )
1607    -> (b -> State# RealWorld -> (# State# RealWorld, a #) )
1608    -> (State# RealWorld -> (# State# RealWorld, a #) )
1609    with 
1610    out_of_line = True
1611    has_side_effects = True
1612
1613 primop  Check "check#" GenPrimOp
1614       (State# RealWorld -> (# State# RealWorld, a #) )
1615    -> (State# RealWorld -> (# State# RealWorld, () #) )
1616    with 
1617    out_of_line = True
1618    has_side_effects = True
1619
1620 primop  NewTVarOp "newTVar#" GenPrimOp
1621        a
1622     -> State# s -> (# State# s, TVar# s a #)
1623    {Create a new {\tt TVar\#} holding a specified initial value.}
1624    with
1625    out_of_line  = True
1626    has_side_effects = True
1627
1628 primop  ReadTVarOp "readTVar#" GenPrimOp
1629        TVar# s a
1630     -> State# s -> (# State# s, a #)
1631    {Read contents of {\tt TVar\#}.  Result is not yet evaluated.}
1632    with
1633    out_of_line  = True
1634    has_side_effects = True
1635
1636 primop ReadTVarIOOp "readTVarIO#" GenPrimOp
1637        TVar# s a
1638     -> State# s -> (# State# s, a #)
1639    {Read contents of {\tt TVar\#} outside an STM transaction}
1640    with
1641    out_of_line  = True
1642    has_side_effects = True
1643
1644 primop  WriteTVarOp "writeTVar#" GenPrimOp
1645        TVar# s a
1646     -> a
1647     -> State# s -> State# s
1648    {Write contents of {\tt TVar\#}.}
1649    with
1650    out_of_line      = True
1651    has_side_effects = True
1652
1653 primop  SameTVarOp "sameTVar#" GenPrimOp
1654    TVar# s a -> TVar# s a -> Bool
1655
1656
1657 ------------------------------------------------------------------------
1658 section "Synchronized Mutable Variables"
1659         {Operations on {\tt MVar\#}s. }
1660 ------------------------------------------------------------------------
1661
1662 primtype MVar# s a
1663         { A shared mutable variable ({\it not} the same as a {\tt MutVar\#}!).
1664         (Note: in a non-concurrent implementation, {\tt (MVar\# a)} can be
1665         represented by {\tt (MutVar\# (Maybe a))}.) }
1666
1667 primop  NewMVarOp "newMVar#"  GenPrimOp
1668    State# s -> (# State# s, MVar# s a #)
1669    {Create new {\tt MVar\#}; initially empty.}
1670    with
1671    out_of_line = True
1672    has_side_effects = True
1673
1674 primop  TakeMVarOp "takeMVar#" GenPrimOp
1675    MVar# s a -> State# s -> (# State# s, a #)
1676    {If {\tt MVar\#} is empty, block until it becomes full.
1677    Then remove and return its contents, and set it empty.}
1678    with
1679    out_of_line      = True
1680    has_side_effects = True
1681
1682 primop  TryTakeMVarOp "tryTakeMVar#" GenPrimOp
1683    MVar# s a -> State# s -> (# State# s, Int#, a #)
1684    {If {\tt MVar\#} is empty, immediately return with integer 0 and value undefined.
1685    Otherwise, return with integer 1 and contents of {\tt MVar\#}, and set {\tt MVar\#} empty.}
1686    with
1687    out_of_line      = True
1688    has_side_effects = True
1689
1690 primop  PutMVarOp "putMVar#" GenPrimOp
1691    MVar# s a -> a -> State# s -> State# s
1692    {If {\tt MVar\#} is full, block until it becomes empty.
1693    Then store value arg as its new contents.}
1694    with
1695    out_of_line      = True
1696    has_side_effects = True
1697
1698 primop  TryPutMVarOp "tryPutMVar#" GenPrimOp
1699    MVar# s a -> a -> State# s -> (# State# s, Int# #)
1700    {If {\tt MVar\#} is full, immediately return with integer 0.
1701     Otherwise, store value arg as {\tt MVar\#}'s new contents, and return with integer 1.}
1702    with
1703    out_of_line      = True
1704    has_side_effects = True
1705
1706 primop  SameMVarOp "sameMVar#" GenPrimOp
1707    MVar# s a -> MVar# s a -> Bool
1708
1709 primop  IsEmptyMVarOp "isEmptyMVar#" GenPrimOp
1710    MVar# s a -> State# s -> (# State# s, Int# #)
1711    {Return 1 if {\tt MVar\#} is empty; 0 otherwise.}
1712    with
1713    out_of_line = True
1714    has_side_effects = True
1715
1716 ------------------------------------------------------------------------
1717 section "Delay/wait operations"
1718 ------------------------------------------------------------------------
1719
1720 primop  DelayOp "delay#" GenPrimOp
1721    Int# -> State# s -> State# s
1722    {Sleep specified number of microseconds.}
1723    with
1724    has_side_effects = True
1725    out_of_line      = True
1726
1727 primop  WaitReadOp "waitRead#" GenPrimOp
1728    Int# -> State# s -> State# s
1729    {Block until input is available on specified file descriptor.}
1730    with
1731    has_side_effects = True
1732    out_of_line      = True
1733
1734 primop  WaitWriteOp "waitWrite#" GenPrimOp
1735    Int# -> State# s -> State# s
1736    {Block until output is possible on specified file descriptor.}
1737    with
1738    has_side_effects = True
1739    out_of_line      = True
1740
1741 #ifdef mingw32_TARGET_OS
1742 primop  AsyncReadOp "asyncRead#" GenPrimOp
1743    Int# -> Int# -> Int# -> Addr# -> State# RealWorld-> (# State# RealWorld, Int#, Int# #)
1744    {Asynchronously read bytes from specified file descriptor.}
1745    with
1746    has_side_effects = True
1747    out_of_line      = True
1748
1749 primop  AsyncWriteOp "asyncWrite#" GenPrimOp
1750    Int# -> Int# -> Int# -> Addr# -> State# RealWorld-> (# State# RealWorld, Int#, Int# #)
1751    {Asynchronously write bytes from specified file descriptor.}
1752    with
1753    has_side_effects = True
1754    out_of_line      = True
1755
1756 primop  AsyncDoProcOp "asyncDoProc#" GenPrimOp
1757    Addr# -> Addr# -> State# RealWorld-> (# State# RealWorld, Int#, Int# #)
1758    {Asynchronously perform procedure (first arg), passing it 2nd arg.}
1759    with
1760    has_side_effects = True
1761    out_of_line      = True
1762
1763 #endif
1764
1765 ------------------------------------------------------------------------
1766 section "Concurrency primitives"
1767 ------------------------------------------------------------------------
1768
1769 primtype State# s
1770         { {\tt State\#} is the primitive, unlifted type of states.  It has
1771         one type parameter, thus {\tt State\# RealWorld}, or {\tt State\# s},
1772         where s is a type variable. The only purpose of the type parameter
1773         is to keep different state threads separate.  It is represented by
1774         nothing at all. }
1775
1776 primtype RealWorld
1777         { {\tt RealWorld} is deeply magical.  It is {\it primitive}, but it is not
1778         {\it unlifted} (hence {\tt ptrArg}).  We never manipulate values of type
1779         {\tt RealWorld}; it's only used in the type system, to parameterise {\tt State\#}. }
1780
1781 primtype ThreadId#
1782         {(In a non-concurrent implementation, this can be a singleton
1783         type, whose (unique) value is returned by {\tt myThreadId\#}.  The 
1784         other operations can be omitted.)}
1785
1786 primop  ForkOp "fork#" GenPrimOp
1787    a -> State# RealWorld -> (# State# RealWorld, ThreadId# #)
1788    with
1789    has_side_effects = True
1790    out_of_line      = True
1791
1792 primop  ForkOnOp "forkOn#" GenPrimOp
1793    Int# -> a -> State# RealWorld -> (# State# RealWorld, ThreadId# #)
1794    with
1795    has_side_effects = True
1796    out_of_line      = True
1797
1798 primop  KillThreadOp "killThread#"  GenPrimOp
1799    ThreadId# -> a -> State# RealWorld -> State# RealWorld
1800    with
1801    has_side_effects = True
1802    out_of_line      = True
1803
1804 primop  YieldOp "yield#" GenPrimOp
1805    State# RealWorld -> State# RealWorld
1806    with
1807    has_side_effects = True
1808    out_of_line      = True
1809
1810 primop  MyThreadIdOp "myThreadId#" GenPrimOp
1811    State# RealWorld -> (# State# RealWorld, ThreadId# #)
1812    with
1813    out_of_line = True
1814    has_side_effects = True
1815
1816 primop LabelThreadOp "labelThread#" GenPrimOp
1817    ThreadId# -> Addr# -> State# RealWorld -> State# RealWorld
1818    with
1819    has_side_effects = True
1820    out_of_line      = True
1821    
1822 primop  IsCurrentThreadBoundOp "isCurrentThreadBound#" GenPrimOp
1823    State# RealWorld -> (# State# RealWorld, Int# #)
1824    with
1825    out_of_line = True
1826    has_side_effects = True
1827
1828 primop  NoDuplicateOp "noDuplicate#" GenPrimOp
1829    State# RealWorld -> State# RealWorld
1830    with
1831    out_of_line = True
1832    has_side_effects = True
1833
1834 primop  ThreadStatusOp "threadStatus#" GenPrimOp
1835    ThreadId# -> State# RealWorld -> (# State# RealWorld, Int#, Int#, Int# #)
1836    with
1837    out_of_line = True
1838    has_side_effects = True
1839
1840 ------------------------------------------------------------------------
1841 section "Weak pointers"
1842 ------------------------------------------------------------------------
1843
1844 primtype Weak# b
1845
1846 -- note that tyvar "o" denotes openAlphaTyVar
1847
1848 primop  MkWeakOp "mkWeak#" GenPrimOp
1849    o -> b -> c -> State# RealWorld -> (# State# RealWorld, Weak# b #)
1850    with
1851    has_side_effects = True
1852    out_of_line      = True
1853
1854 primop  MkWeakNoFinalizerOp "mkWeakNoFinalizer#" GenPrimOp
1855    o -> b -> State# RealWorld -> (# State# RealWorld, Weak# b #)
1856    with
1857    has_side_effects = True
1858    out_of_line      = True
1859
1860 primop  MkWeakForeignEnvOp "mkWeakForeignEnv#" GenPrimOp
1861    o -> b -> Addr# -> Addr# -> Int# -> Addr# -> State# RealWorld -> (# State# RealWorld, Weak# b #)
1862    with
1863    has_side_effects = True
1864    out_of_line      = True
1865
1866 primop  DeRefWeakOp "deRefWeak#" GenPrimOp
1867    Weak# a -> State# RealWorld -> (# State# RealWorld, Int#, a #)
1868    with
1869    has_side_effects = True
1870    out_of_line      = True
1871
1872 primop  FinalizeWeakOp "finalizeWeak#" GenPrimOp
1873    Weak# a -> State# RealWorld -> (# State# RealWorld, Int#, 
1874               (State# RealWorld -> (# State# RealWorld, () #)) #)
1875    with
1876    has_side_effects = True
1877    out_of_line      = True
1878
1879 primop TouchOp "touch#" GenPrimOp
1880    o -> State# RealWorld -> State# RealWorld
1881    with
1882    code_size = { 0 }
1883    has_side_effects = True
1884
1885 ------------------------------------------------------------------------
1886 section "Stable pointers and names"
1887 ------------------------------------------------------------------------
1888
1889 primtype StablePtr# a
1890
1891 primtype StableName# a
1892
1893 primop  MakeStablePtrOp "makeStablePtr#" GenPrimOp
1894    a -> State# RealWorld -> (# State# RealWorld, StablePtr# a #)
1895    with
1896    has_side_effects = True
1897    out_of_line      = True
1898
1899 primop  DeRefStablePtrOp "deRefStablePtr#" GenPrimOp
1900    StablePtr# a -> State# RealWorld -> (# State# RealWorld, a #)
1901    with
1902    has_side_effects = True
1903    out_of_line      = True
1904
1905 primop  EqStablePtrOp "eqStablePtr#" GenPrimOp
1906    StablePtr# a -> StablePtr# a -> Int#
1907    with
1908    has_side_effects = True
1909
1910 primop  MakeStableNameOp "makeStableName#" GenPrimOp
1911    a -> State# RealWorld -> (# State# RealWorld, StableName# a #)
1912    with
1913    has_side_effects = True
1914    out_of_line      = True
1915
1916 primop  EqStableNameOp "eqStableName#" GenPrimOp
1917    StableName# a -> StableName# b -> Int#
1918
1919 primop  StableNameToIntOp "stableNameToInt#" GenPrimOp
1920    StableName# a -> Int#
1921
1922 ------------------------------------------------------------------------
1923 section "Unsafe pointer equality"
1924 --  (#1 Bad Guy: Alistair Reid :)   
1925 ------------------------------------------------------------------------
1926
1927 primop  ReallyUnsafePtrEqualityOp "reallyUnsafePtrEquality#" GenPrimOp
1928    a -> a -> Int#
1929
1930 ------------------------------------------------------------------------
1931 section "Parallelism"
1932 ------------------------------------------------------------------------
1933
1934 primop  ParOp "par#" GenPrimOp
1935    a -> Int#
1936    with
1937       -- Note that Par is lazy to avoid that the sparked thing
1938       -- gets evaluted strictly, which it should *not* be
1939    has_side_effects = True
1940    code_size = { primOpCodeSizeForeignCall }
1941
1942 primop SparkOp "spark#" GenPrimOp
1943    a -> State# s -> (# State# s, a #)
1944    with has_side_effects = True
1945    code_size = { primOpCodeSizeForeignCall }
1946
1947 primop SeqOp "seq#" GenPrimOp
1948    a -> State# s -> (# State# s, a #)
1949
1950    -- why return the value?  So that we can control sharing of seq'd
1951    -- values: in
1952    --    let x = e in x `seq` ... x ...
1953    -- we don't want to inline x, so better to represent it as
1954    --    let x = e in case seq# x RW of (# _, x' #) -> ... x' ...
1955    -- also it matches the type of rseq in the Eval monad.
1956
1957 primop GetSparkOp "getSpark#" GenPrimOp
1958    State# s -> (# State# s, Int#, a #)
1959    with
1960    has_side_effects = True
1961    out_of_line = True
1962
1963 primop NumSparks "numSparks#" GenPrimOp
1964    State# s -> (# State# s, Int# #)
1965    { Returns the number of sparks in the local spark pool. }
1966    with
1967    has_side_effects = True
1968    out_of_line = True
1969
1970 -- HWL: The first 4 Int# in all par... annotations denote:
1971 --   name, granularity info, size of result, degree of parallelism
1972 --      Same  structure as _seq_ i.e. returns Int#
1973 -- KSW: v, the second arg in parAt# and parAtForNow#, is used only to determine
1974 --   `the processor containing the expression v'; it is not evaluated
1975
1976 primop  ParGlobalOp  "parGlobal#"  GenPrimOp
1977    a -> Int# -> Int# -> Int# -> Int# -> b -> Int#
1978    with
1979    has_side_effects = True
1980
1981 primop  ParLocalOp  "parLocal#"  GenPrimOp
1982    a -> Int# -> Int# -> Int# -> Int# -> b -> Int#
1983    with
1984    has_side_effects = True
1985
1986 primop  ParAtOp  "parAt#"  GenPrimOp
1987    b -> a -> Int# -> Int# -> Int# -> Int# -> c -> Int#
1988    with
1989    has_side_effects = True
1990
1991 primop  ParAtAbsOp  "parAtAbs#"  GenPrimOp
1992    a -> Int# -> Int# -> Int# -> Int# -> Int# -> b -> Int#
1993    with
1994    has_side_effects = True
1995
1996 primop  ParAtRelOp  "parAtRel#" GenPrimOp
1997    a -> Int# -> Int# -> Int# -> Int# -> Int# -> b -> Int#
1998    with
1999    has_side_effects = True
2000
2001 primop  ParAtForNowOp  "parAtForNow#" GenPrimOp
2002    b -> a -> Int# -> Int# -> Int# -> Int# -> c -> Int#
2003    with
2004    has_side_effects = True
2005
2006 -- copyable# and noFollow# are yet to be implemented (for GpH)
2007 --
2008 --primop  CopyableOp  "copyable#" GenPrimOp
2009 --   a -> Int#
2010 --   with
2011 --   has_side_effects = True
2012 --
2013 --primop  NoFollowOp "noFollow#" GenPrimOp
2014 --   a -> Int#
2015 --   with
2016 --   has_side_effects = True
2017
2018
2019 ------------------------------------------------------------------------
2020 section "Tag to enum stuff"
2021         {Convert back and forth between values of enumerated types
2022         and small integers.}
2023 ------------------------------------------------------------------------
2024
2025 primop  DataToTagOp "dataToTag#" GenPrimOp
2026    a -> Int#
2027    with
2028    strictness  = { \ _arity -> mkStrictSig (mkTopDmdType [seqDmd] TopRes) }
2029         -- dataToTag# must have an evaluated argument
2030
2031 primop  TagToEnumOp "tagToEnum#" GenPrimOp     
2032    Int# -> a
2033
2034 ------------------------------------------------------------------------
2035 section "Bytecode operations" 
2036         {Support for the bytecode interpreter and linker.}
2037 ------------------------------------------------------------------------
2038
2039 primtype BCO#
2040    {Primitive bytecode type.}
2041
2042 primop   AddrToAnyOp "addrToAny#" GenPrimOp
2043    Addr# -> (# a #)
2044    {Convert an {\tt Addr\#} to a followable Any type.}
2045    with
2046    code_size = 0
2047
2048 primop   MkApUpd0_Op "mkApUpd0#" GenPrimOp
2049    BCO# -> (# a #)
2050    with
2051    out_of_line = True
2052
2053 primop  NewBCOOp "newBCO#" GenPrimOp
2054    ByteArray# -> ByteArray# -> Array# a -> Int# -> ByteArray# -> State# s -> (# State# s, BCO# #)
2055    with
2056    has_side_effects = True
2057    out_of_line      = True
2058
2059 primop  UnpackClosureOp "unpackClosure#" GenPrimOp
2060    a -> (# Addr#, Array# b, ByteArray# #)
2061    with
2062    out_of_line = True
2063
2064 primop  GetApStackValOp "getApStackVal#" GenPrimOp
2065    a -> Int# -> (# Int#, b #)
2066    with
2067    out_of_line = True
2068
2069 ------------------------------------------------------------------------
2070 section "Misc"
2071         {These aren't nearly as wired in as Etc...}
2072 ------------------------------------------------------------------------
2073
2074 primop  GetCCSOfOp "getCCSOf#" GenPrimOp
2075    a -> State# s -> (# State# s, Addr# #)
2076
2077 primop  GetCurrentCCSOp "getCurrentCCS#" GenPrimOp
2078    a -> State# s -> (# State# s, Addr# #)
2079    { Returns the current {\tt CostCentreStack} (value is {\tt NULL} if
2080      not profiling).  Takes a dummy argument which can be used to
2081      avoid the call to {\tt getCCCS\#} being floated out by the
2082      simplifier, which would result in an uninformative stack
2083      ("CAF"). }
2084
2085 ------------------------------------------------------------------------
2086 section "Etc" 
2087         {Miscellaneous built-ins}
2088 ------------------------------------------------------------------------
2089
2090 pseudoop   "seq"
2091    a -> b -> b
2092    { Evaluates its first argument to head normal form, and then returns its second
2093         argument as the result. }
2094
2095 primtype Any k
2096         { The type constructor {\tt Any} is type to which you can unsafely coerce any
2097         lifted type, and back. 
2098
2099           * It is lifted, and hence represented by a pointer
2100
2101           * It does not claim to be a {\it data} type, and that's important for
2102             the code generator, because the code gen may {\it enter} a data value
2103             but never enters a function value.  
2104
2105         It's also used to instantiate un-constrained type variables after type
2106         checking.  For example, {\tt length} has type
2107
2108         {\tt length :: forall a. [a] -> Int}
2109
2110         and the list datacon for the empty list has type
2111
2112         {\tt [] :: forall a. [a]}
2113
2114         In order to compose these two terms as {\tt length []} a type
2115         application is required, but there is no constraint on the
2116         choice.  In this situation GHC uses {\tt Any}:
2117
2118         {\tt length (Any *) ([] (Any *))}
2119
2120         Note that {\tt Any} is kind polymorphic, and takes a kind {\tt k} as its
2121         first argument. The kind of {\tt Any} is thus {\tt forall k. k -> k}.}
2122
2123 primtype AnyK
2124         { The kind {\tt AnyK} is the kind level counterpart to {\tt Any}. In a
2125         kind polymorphic setting, a similar example to the length of the empty
2126         list can be given at the type level:
2127
2128         {\tt type family Length (l :: [k]) :: Nat}
2129         {\tt type instance Length [] = Zero}
2130
2131         When {\tt Length} is applied to the empty (promoted) list it will have
2132         the kind {\tt Length AnyK []}.
2133
2134         {\tt AnyK} is currently not exported and cannot be used directly, but
2135         you might see it in debug output from the compiler.
2136         }
2137
2138 pseudoop   "unsafeCoerce#"
2139    a -> b
2140    { The function {\tt unsafeCoerce\#} allows you to side-step the typechecker entirely. That
2141         is, it allows you to coerce any type into any other type. If you use this function,
2142         you had better get it right, otherwise segmentation faults await. It is generally
2143         used when you want to write a program that you know is well-typed, but where Haskell's
2144         type system is not expressive enough to prove that it is well typed.
2145
2146         The following uses of {\tt unsafeCoerce\#} are supposed to work (i.e. not lead to
2147         spurious compile-time or run-time crashes):
2148
2149          * Casting any lifted type to {\tt Any}
2150
2151          * Casting {\tt Any} back to the real type
2152
2153          * Casting an unboxed type to another unboxed type of the same size
2154            (but not coercions between floating-point and integral types)
2155
2156          * Casting between two types that have the same runtime representation.  One case is when
2157            the two types differ only in "phantom" type parameters, for example
2158            {\tt Ptr Int} to {\tt Ptr Float}, or {\tt [Int]} to {\tt [Float]} when the list is 
2159            known to be empty.  Also, a {\tt newtype} of a type {\tt T} has the same representation
2160            at runtime as {\tt T}.
2161
2162         Other uses of {\tt unsafeCoerce\#} are undefined.  In particular, you should not use
2163         {\tt unsafeCoerce\#} to cast a T to an algebraic data type D, unless T is also
2164         an algebraic data type.  For example, do not cast {\tt Int->Int} to {\tt Bool}, even if
2165         you later cast that {\tt Bool} back to {\tt Int->Int} before applying it.  The reasons
2166         have to do with GHC's internal representation details (for the congnoscenti, data values
2167         can be entered but function closures cannot).  If you want a safe type to cast things
2168         to, use {\tt Any}, which is not an algebraic data type.
2169         
2170         }
2171
2172 -- NB. It is tempting to think that casting a value to a type that it doesn't have is safe
2173 -- as long as you don't "do anything" with the value in its cast form, such as seq on it.  This
2174 -- isn't the case: the compiler can insert seqs itself, and if these happen at the wrong type,
2175 -- Bad Things Might Happen.  See bug #1616: in this case we cast a function of type (a,b) -> (a,b)
2176 -- to () -> () and back again.  The strictness analyser saw that the function was strict, but
2177 -- the wrapper had type () -> (), and hence the wrapper de-constructed the (), the worker re-constructed
2178 -- a new (), with the result that the code ended up with "case () of (a,b) -> ...".
2179
2180 primop  TraceEventOp "traceEvent#" GenPrimOp
2181    Addr# -> State# s -> State# s
2182    { Emits an event via the RTS tracing framework.  The contents
2183      of the event is the zero-terminated byte string passed as the first
2184      argument.  The event will be emitted either to the .eventlog file,
2185      or to stderr, depending on the runtime RTS flags. }
2186    with
2187    has_side_effects = True
2188    out_of_line      = True
2189
2190 primop  TraceMarkerOp "traceMarker#" GenPrimOp
2191    Addr# -> State# s -> State# s
2192    { Emits a marker event via the RTS tracing framework.  The contents
2193      of the event is the zero-terminated byte string passed as the first
2194      argument.  The event will be emitted either to the .eventlog file,
2195      or to stderr, depending on the runtime RTS flags. }
2196    with
2197    has_side_effects = True
2198    out_of_line      = True
2199
2200
2201 ------------------------------------------------------------------------
2202 ---                                                                  ---
2203 ------------------------------------------------------------------------
2204
2205 thats_all_folks