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