0e917f34df035c8e7aa1107d5b6faed65841a579
[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
45    commutable       = False
46    needs_wrapper    = False
47    can_fail         = False
48    strictness       = { \ arity -> mkStrictSig (mkTopDmdType (replicate arity lazyDmd) TopRes) }
49
50 -- Currently, documentation is produced using latex, so contents of
51 -- description fields should be legal latex. Descriptions can contain
52 -- matched pairs of embedded curly brackets.
53
54 #include "MachDeps.h"
55
56 -- We need platform defines (tests for mingw32 below).  However, we only
57 -- test the TARGET platform, which doesn't vary between stages, so the
58 -- stage1 platform defines are fine:
59 #include "../stage1/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
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   IntNegOp    "negateInt#"    Monadic   Int# -> Int#
212 primop   IntAddCOp   "addIntC#"    GenPrimOp   Int# -> Int# -> (# Int#, Int# #)
213          {Add with carry.  First member of result is (wrapped) sum; 
214           second member is 0 iff no overflow occured.}
215 primop   IntSubCOp   "subIntC#"    GenPrimOp   Int# -> Int# -> (# Int#, Int# #)
216          {Subtract with carry.  First member of result is (wrapped) difference; 
217           second member is 0 iff no overflow occured.}
218
219 primop   IntGtOp  ">#"   Compare   Int# -> Int# -> Bool
220 primop   IntGeOp  ">=#"   Compare   Int# -> Int# -> Bool
221
222 primop   IntEqOp  "==#"   Compare
223    Int# -> Int# -> Bool
224    with commutable = True
225
226 primop   IntNeOp  "/=#"   Compare
227    Int# -> Int# -> Bool
228    with commutable = True
229
230 primop   IntLtOp  "<#"   Compare   Int# -> Int# -> Bool
231 primop   IntLeOp  "<=#"   Compare   Int# -> Int# -> Bool
232
233 primop   ChrOp   "chr#"   GenPrimOp   Int# -> Char#
234
235 primop   Int2WordOp "int2Word#" GenPrimOp Int# -> Word#
236 primop   Int2FloatOp   "int2Float#"      GenPrimOp  Int# -> Float#
237 primop   Int2DoubleOp   "int2Double#"          GenPrimOp  Int# -> Double#
238
239 primop   ISllOp   "uncheckedIShiftL#" GenPrimOp  Int# -> Int# -> Int#
240          {Shift left.  Result undefined if shift amount is not
241           in the range 0 to word size - 1 inclusive.}
242 primop   ISraOp   "uncheckedIShiftRA#" GenPrimOp Int# -> Int# -> Int#
243          {Shift right arithmetic.  Result undefined if shift amount is not
244           in the range 0 to word size - 1 inclusive.}
245 primop   ISrlOp   "uncheckedIShiftRL#" GenPrimOp Int# -> Int# -> Int#
246          {Shift right logical.  Result undefined if shift amount is not
247           in the range 0 to word size - 1 inclusive.}
248
249 ------------------------------------------------------------------------
250 section "Word#"
251         {Operations on native-sized unsigned words (30+ bits).}
252 ------------------------------------------------------------------------
253
254 primtype Word#
255
256 primop   WordAddOp   "plusWord#"   Dyadic   Word# -> Word# -> Word#
257    with commutable = True
258
259 primop   WordSubOp   "minusWord#"   Dyadic   Word# -> Word# -> Word#
260
261 primop   WordMulOp   "timesWord#"   Dyadic   Word# -> Word# -> Word#
262    with commutable = True
263
264 primop   WordQuotOp   "quotWord#"   Dyadic   Word# -> Word# -> Word#
265    with can_fail = True
266
267 primop   WordRemOp   "remWord#"   Dyadic   Word# -> Word# -> Word#
268    with can_fail = True
269
270 primop   AndOp   "and#"   Dyadic   Word# -> Word# -> Word#
271    with commutable = True
272
273 primop   OrOp   "or#"   Dyadic   Word# -> Word# -> Word#
274    with commutable = True
275
276 primop   XorOp   "xor#"   Dyadic   Word# -> Word# -> Word#
277    with commutable = True
278
279 primop   NotOp   "not#"   Monadic   Word# -> Word#
280
281 primop   SllOp   "uncheckedShiftL#"   GenPrimOp   Word# -> Int# -> Word#
282          {Shift left logical.   Result undefined if shift amount is not
283           in the range 0 to word size - 1 inclusive.}
284 primop   SrlOp   "uncheckedShiftRL#"   GenPrimOp   Word# -> Int# -> Word#
285          {Shift right logical.   Result undefined if shift  amount is not
286           in the range 0 to word size - 1 inclusive.}
287
288 primop   Word2IntOp   "word2Int#"   GenPrimOp   Word# -> Int#
289
290 primop   WordGtOp   "gtWord#"   Compare   Word# -> Word# -> Bool
291 primop   WordGeOp   "geWord#"   Compare   Word# -> Word# -> Bool
292 primop   WordEqOp   "eqWord#"   Compare   Word# -> Word# -> Bool
293 primop   WordNeOp   "neWord#"   Compare   Word# -> Word# -> Bool
294 primop   WordLtOp   "ltWord#"   Compare   Word# -> Word# -> Bool
295 primop   WordLeOp   "leWord#"   Compare   Word# -> Word# -> Bool
296
297 ------------------------------------------------------------------------
298 section "Narrowings" 
299         {Explicit narrowing of native-sized ints or words.}
300 ------------------------------------------------------------------------
301
302 primop   Narrow8IntOp      "narrow8Int#"      Monadic   Int# -> Int#
303 primop   Narrow16IntOp     "narrow16Int#"     Monadic   Int# -> Int#
304 primop   Narrow32IntOp     "narrow32Int#"     Monadic   Int# -> Int#
305 primop   Narrow8WordOp     "narrow8Word#"     Monadic   Word# -> Word#
306 primop   Narrow16WordOp    "narrow16Word#"    Monadic   Word# -> Word#
307 primop   Narrow32WordOp    "narrow32Word#"    Monadic   Word# -> Word#
308
309
310 #if WORD_SIZE_IN_BITS < 32
311 ------------------------------------------------------------------------
312 section "Int32#"
313         {Operations on 32-bit integers ({\tt Int32\#}).  This type is only used
314          if plain {\tt Int\#} has less than 32 bits.  In any case, the operations
315          are not primops; they are implemented (if needed) as ccalls instead.}
316 ------------------------------------------------------------------------
317
318 primtype Int32#
319
320 ------------------------------------------------------------------------
321 section "Word32#"
322         {Operations on 32-bit unsigned words. This type is only used 
323          if plain {\tt Word\#} has less than 32 bits. In any case, the operations
324          are not primops; they are implemented (if needed) as ccalls instead.}
325 ------------------------------------------------------------------------
326
327 primtype Word32#
328
329 #endif 
330
331
332 #if WORD_SIZE_IN_BITS < 64
333 ------------------------------------------------------------------------
334 section "Int64#"
335         {Operations on 64-bit unsigned words. This type is only used 
336          if plain {\tt Int\#} has less than 64 bits. In any case, the operations
337          are not primops; they are implemented (if needed) as ccalls instead.}
338 ------------------------------------------------------------------------
339
340 primtype Int64#
341
342 ------------------------------------------------------------------------
343 section "Word64#"
344         {Operations on 64-bit unsigned words. This type is only used 
345          if plain {\tt Word\#} has less than 64 bits. In any case, the operations
346          are not primops; they are implemented (if needed) as ccalls instead.}
347 ------------------------------------------------------------------------
348
349 primtype Word64#
350
351 #endif
352
353 ------------------------------------------------------------------------
354 section "Double#"
355         {Operations on double-precision (64 bit) floating-point numbers.}
356 ------------------------------------------------------------------------
357
358 primtype Double#
359
360 primop   DoubleGtOp ">##"   Compare   Double# -> Double# -> Bool
361 primop   DoubleGeOp ">=##"   Compare   Double# -> Double# -> Bool
362
363 primop DoubleEqOp "==##"   Compare
364    Double# -> Double# -> Bool
365    with commutable = True
366
367 primop DoubleNeOp "/=##"   Compare
368    Double# -> Double# -> Bool
369    with commutable = True
370
371 primop   DoubleLtOp "<##"   Compare   Double# -> Double# -> Bool
372 primop   DoubleLeOp "<=##"   Compare   Double# -> Double# -> Bool
373
374 primop   DoubleAddOp   "+##"   Dyadic
375    Double# -> Double# -> Double#
376    with commutable = True
377
378 primop   DoubleSubOp   "-##"   Dyadic   Double# -> Double# -> Double#
379
380 primop   DoubleMulOp   "*##"   Dyadic
381    Double# -> Double# -> Double#
382    with commutable = True
383
384 primop   DoubleDivOp   "/##"   Dyadic
385    Double# -> Double# -> Double#
386    with can_fail = True
387
388 primop   DoubleNegOp   "negateDouble#"  Monadic   Double# -> Double#
389
390 primop   Double2IntOp   "double2Int#"          GenPrimOp  Double# -> Int#
391    {Truncates a {\tt Double#} value to the nearest {\tt Int#}.
392     Results are undefined if the truncation if truncation yields
393     a value outside the range of {\tt Int#}.}
394
395 primop   Double2FloatOp   "double2Float#" GenPrimOp Double# -> Float#
396
397 primop   DoubleExpOp   "expDouble#"      Monadic
398    Double# -> Double#
399    with needs_wrapper = True
400
401 primop   DoubleLogOp   "logDouble#"      Monadic         
402    Double# -> Double#
403    with
404    needs_wrapper = True
405    can_fail = True
406
407 primop   DoubleSqrtOp   "sqrtDouble#"      Monadic  
408    Double# -> Double#
409    with needs_wrapper = True
410
411 primop   DoubleSinOp   "sinDouble#"      Monadic          
412    Double# -> Double#
413    with needs_wrapper = True
414
415 primop   DoubleCosOp   "cosDouble#"      Monadic          
416    Double# -> Double#
417    with needs_wrapper = True
418
419 primop   DoubleTanOp   "tanDouble#"      Monadic          
420    Double# -> Double#
421    with needs_wrapper = True
422
423 primop   DoubleAsinOp   "asinDouble#"      Monadic 
424    Double# -> Double#
425    with
426    needs_wrapper = True
427    can_fail = True
428
429 primop   DoubleAcosOp   "acosDouble#"      Monadic  
430    Double# -> Double#
431    with
432    needs_wrapper = True
433    can_fail = True
434
435 primop   DoubleAtanOp   "atanDouble#"      Monadic  
436    Double# -> Double#
437    with
438    needs_wrapper = True
439
440 primop   DoubleSinhOp   "sinhDouble#"      Monadic  
441    Double# -> Double#
442    with needs_wrapper = True
443
444 primop   DoubleCoshOp   "coshDouble#"      Monadic  
445    Double# -> Double#
446    with needs_wrapper = True
447
448 primop   DoubleTanhOp   "tanhDouble#"      Monadic  
449    Double# -> Double#
450    with needs_wrapper = True
451
452 primop   DoublePowerOp   "**##" Dyadic  
453    Double# -> Double# -> Double#
454    {Exponentiation.}
455    with needs_wrapper = True
456
457 primop   DoubleDecode_2IntOp   "decodeDouble_2Int#" GenPrimOp    
458    Double# -> (# Int#, Word#, Word#, Int# #)
459    {Convert to integer.
460     First component of the result is -1 or 1, indicating the sign of the
461     mantissa. The next two are the high and low 32 bits of the mantissa
462     respectively, and the last is the exponent.}
463    with out_of_line = True
464
465 ------------------------------------------------------------------------
466 section "Float#" 
467         {Operations on single-precision (32-bit) floating-point numbers.}
468 ------------------------------------------------------------------------
469
470 primtype Float#
471
472 primop   FloatGtOp  "gtFloat#"   Compare   Float# -> Float# -> Bool
473 primop   FloatGeOp  "geFloat#"   Compare   Float# -> Float# -> Bool
474
475 primop   FloatEqOp  "eqFloat#"   Compare
476    Float# -> Float# -> Bool
477    with commutable = True
478
479 primop   FloatNeOp  "neFloat#"   Compare
480    Float# -> Float# -> Bool
481    with commutable = True
482
483 primop   FloatLtOp  "ltFloat#"   Compare   Float# -> Float# -> Bool
484 primop   FloatLeOp  "leFloat#"   Compare   Float# -> Float# -> Bool
485
486 primop   FloatAddOp   "plusFloat#"      Dyadic            
487    Float# -> Float# -> Float#
488    with commutable = True
489
490 primop   FloatSubOp   "minusFloat#"      Dyadic      Float# -> Float# -> Float#
491
492 primop   FloatMulOp   "timesFloat#"      Dyadic    
493    Float# -> Float# -> Float#
494    with commutable = True
495
496 primop   FloatDivOp   "divideFloat#"      Dyadic  
497    Float# -> Float# -> Float#
498    with can_fail = True
499
500 primop   FloatNegOp   "negateFloat#"      Monadic    Float# -> Float#
501
502 primop   Float2IntOp   "float2Int#"      GenPrimOp  Float# -> Int#
503    {Truncates a {\tt Float#} value to the nearest {\tt Int#}.
504     Results are undefined if the truncation if truncation yields
505     a value outside the range of {\tt Int#}.}
506
507 primop   FloatExpOp   "expFloat#"      Monadic          
508    Float# -> Float#
509    with needs_wrapper = True
510
511 primop   FloatLogOp   "logFloat#"      Monadic          
512    Float# -> Float#
513    with needs_wrapper = True
514         can_fail = True
515
516 primop   FloatSqrtOp   "sqrtFloat#"      Monadic          
517    Float# -> Float#
518    with needs_wrapper = True
519
520 primop   FloatSinOp   "sinFloat#"      Monadic          
521    Float# -> Float#
522    with needs_wrapper = True
523
524 primop   FloatCosOp   "cosFloat#"      Monadic          
525    Float# -> Float#
526    with needs_wrapper = True
527
528 primop   FloatTanOp   "tanFloat#"      Monadic          
529    Float# -> Float#
530    with needs_wrapper = True
531
532 primop   FloatAsinOp   "asinFloat#"      Monadic          
533    Float# -> Float#
534    with needs_wrapper = True
535         can_fail = True
536
537 primop   FloatAcosOp   "acosFloat#"      Monadic          
538    Float# -> Float#
539    with needs_wrapper = True
540         can_fail = True
541
542 primop   FloatAtanOp   "atanFloat#"      Monadic          
543    Float# -> Float#
544    with needs_wrapper = True
545
546 primop   FloatSinhOp   "sinhFloat#"      Monadic          
547    Float# -> Float#
548    with needs_wrapper = True
549
550 primop   FloatCoshOp   "coshFloat#"      Monadic          
551    Float# -> Float#
552    with needs_wrapper = True
553
554 primop   FloatTanhOp   "tanhFloat#"      Monadic          
555    Float# -> Float#
556    with needs_wrapper = True
557
558 primop   FloatPowerOp   "powerFloat#"      Dyadic   
559    Float# -> Float# -> Float#
560    with needs_wrapper = True
561
562 primop   Float2DoubleOp   "float2Double#" GenPrimOp  Float# -> Double#
563
564 primop   FloatDecode_IntOp   "decodeFloat_Int#" GenPrimOp
565    Float# -> (# Int#, Int# #)
566    {Convert to integers.
567     First {\tt Int\#} in result is the mantissa; second is the exponent.}
568    with out_of_line = True
569
570 ------------------------------------------------------------------------
571 section "Arrays"
572         {Operations on {\tt Array\#}.}
573 ------------------------------------------------------------------------
574
575 primtype Array# a
576
577 primtype MutableArray# s a
578
579 primop  NewArrayOp "newArray#" GenPrimOp
580    Int# -> a -> State# s -> (# State# s, MutableArray# s a #)
581    {Create a new mutable array of specified size (in bytes),
582     in the specified state thread,
583     with each element containing the specified initial value.}
584    with
585    out_of_line = True
586    has_side_effects = True
587
588 primop  SameMutableArrayOp "sameMutableArray#" GenPrimOp
589    MutableArray# s a -> MutableArray# s a -> Bool
590
591 primop  ReadArrayOp "readArray#" GenPrimOp
592    MutableArray# s a -> Int# -> State# s -> (# State# s, a #)
593    {Read from specified index of mutable array. Result is not yet evaluated.}
594    with
595    has_side_effects = True
596
597 primop  WriteArrayOp "writeArray#" GenPrimOp
598    MutableArray# s a -> Int# -> a -> State# s -> State# s
599    {Write to specified index of mutable array.}
600    with
601    has_side_effects = True
602
603 primop  IndexArrayOp "indexArray#" GenPrimOp
604    Array# a -> Int# -> (# a #)
605    {Read from specified index of immutable array. Result is packaged into
606     an unboxed singleton; the result itself is not yet evaluated.}
607
608 primop  UnsafeFreezeArrayOp "unsafeFreezeArray#" GenPrimOp
609    MutableArray# s a -> State# s -> (# State# s, Array# a #)
610    {Make a mutable array immutable, without copying.}
611    with
612    has_side_effects = True
613
614 primop  UnsafeThawArrayOp  "unsafeThawArray#" GenPrimOp
615    Array# a -> State# s -> (# State# s, MutableArray# s a #)
616    {Make an immutable array mutable, without copying.}
617    with
618    out_of_line = True
619    has_side_effects = True
620
621 ------------------------------------------------------------------------
622 section "Byte Arrays"
623         {Operations on {\tt ByteArray\#}. A {\tt ByteArray\#} is a just a region of
624          raw memory in the garbage-collected heap, which is not
625          scanned for pointers. It carries its own size (in bytes).
626          There are
627          three sets of operations for accessing byte array contents:
628          index for reading from immutable byte arrays, and read/write
629          for mutable byte arrays.  Each set contains operations for a
630          range of useful primitive data types.  Each operation takes
631          an offset measured in terms of the size fo the primitive type
632          being read or written.}
633
634 ------------------------------------------------------------------------
635
636 primtype ByteArray#
637
638 primtype MutableByteArray# s
639
640 primop  NewByteArrayOp_Char "newByteArray#" GenPrimOp
641    Int# -> State# s -> (# State# s, MutableByteArray# s #)
642    {Create a new mutable byte array of specified size (in bytes), in
643     the specified state thread.}
644    with out_of_line = True
645         has_side_effects = True
646
647 primop  NewPinnedByteArrayOp_Char "newPinnedByteArray#" GenPrimOp
648    Int# -> State# s -> (# State# s, MutableByteArray# s #)
649    {Create a mutable byte array that the GC guarantees not to move.}
650    with out_of_line = True
651         has_side_effects = True
652
653 primop  NewAlignedPinnedByteArrayOp_Char "newAlignedPinnedByteArray#" GenPrimOp
654    Int# -> Int# -> State# s -> (# State# s, MutableByteArray# s #)
655    {Create a mutable byte array, aligned by the specified amount, that the GC guarantees not to move.}
656    with out_of_line = True
657         has_side_effects = True
658
659 primop  ByteArrayContents_Char "byteArrayContents#" GenPrimOp
660    ByteArray# -> Addr#
661    {Intended for use with pinned arrays; otherwise very unsafe!}
662
663 primop  SameMutableByteArrayOp "sameMutableByteArray#" GenPrimOp
664    MutableByteArray# s -> MutableByteArray# s -> Bool
665
666 primop  UnsafeFreezeByteArrayOp "unsafeFreezeByteArray#" GenPrimOp
667    MutableByteArray# s -> State# s -> (# State# s, ByteArray# #)
668    {Make a mutable byte array immutable, without copying.}
669    with
670    has_side_effects = True
671
672 primop  SizeofByteArrayOp "sizeofByteArray#" GenPrimOp  
673    ByteArray# -> Int#
674    {Return the size of the array in bytes.}
675
676 primop  SizeofMutableByteArrayOp "sizeofMutableByteArray#" GenPrimOp
677    MutableByteArray# s -> Int#
678    {Return the size of the array in bytes.}
679
680 primop IndexByteArrayOp_Char "indexCharArray#" GenPrimOp
681    ByteArray# -> Int# -> Char#
682    {Read 8-bit character; offset in bytes.}
683
684 primop IndexByteArrayOp_WideChar "indexWideCharArray#" GenPrimOp
685    ByteArray# -> Int# -> Char#
686    {Read 31-bit character; offset in 4-byte words.}
687
688 primop IndexByteArrayOp_Int "indexIntArray#" GenPrimOp
689    ByteArray# -> Int# -> Int#
690
691 primop IndexByteArrayOp_Word "indexWordArray#" GenPrimOp
692    ByteArray# -> Int# -> Word#
693
694 primop IndexByteArrayOp_Addr "indexAddrArray#" GenPrimOp
695    ByteArray# -> Int# -> Addr#
696
697 primop IndexByteArrayOp_Float "indexFloatArray#" GenPrimOp
698    ByteArray# -> Int# -> Float#
699
700 primop IndexByteArrayOp_Double "indexDoubleArray#" GenPrimOp
701    ByteArray# -> Int# -> Double#
702
703 primop IndexByteArrayOp_StablePtr "indexStablePtrArray#" GenPrimOp
704    ByteArray# -> Int# -> StablePtr# a
705
706 primop IndexByteArrayOp_Int8 "indexInt8Array#" GenPrimOp
707    ByteArray# -> Int# -> Int#
708
709 primop IndexByteArrayOp_Int16 "indexInt16Array#" GenPrimOp
710    ByteArray# -> Int# -> Int#
711
712 primop IndexByteArrayOp_Int32 "indexInt32Array#" GenPrimOp
713    ByteArray# -> Int# -> INT32
714
715 primop IndexByteArrayOp_Int64 "indexInt64Array#" GenPrimOp
716    ByteArray# -> Int# -> INT64
717
718 primop IndexByteArrayOp_Word8 "indexWord8Array#" GenPrimOp
719    ByteArray# -> Int# -> Word#
720
721 primop IndexByteArrayOp_Word16 "indexWord16Array#" GenPrimOp
722    ByteArray# -> Int# -> Word#
723
724 primop IndexByteArrayOp_Word32 "indexWord32Array#" GenPrimOp
725    ByteArray# -> Int# -> WORD32
726
727 primop IndexByteArrayOp_Word64 "indexWord64Array#" GenPrimOp
728    ByteArray# -> Int# -> WORD64
729
730 primop  ReadByteArrayOp_Char "readCharArray#" GenPrimOp
731    MutableByteArray# s -> Int# -> State# s -> (# State# s, Char# #)
732    {Read 8-bit character; offset in bytes.}
733    with has_side_effects = True
734
735 primop  ReadByteArrayOp_WideChar "readWideCharArray#" GenPrimOp
736    MutableByteArray# s -> Int# -> State# s -> (# State# s, Char# #)
737    {Read 31-bit character; offset in 4-byte words.}
738    with has_side_effects = True
739
740 primop  ReadByteArrayOp_Int "readIntArray#" GenPrimOp
741    MutableByteArray# s -> Int# -> State# s -> (# State# s, Int# #)
742    with has_side_effects = True
743
744 primop  ReadByteArrayOp_Word "readWordArray#" GenPrimOp
745    MutableByteArray# s -> Int# -> State# s -> (# State# s, Word# #)
746    with has_side_effects = True
747
748 primop  ReadByteArrayOp_Addr "readAddrArray#" GenPrimOp
749    MutableByteArray# s -> Int# -> State# s -> (# State# s, Addr# #)
750    with has_side_effects = True
751
752 primop  ReadByteArrayOp_Float "readFloatArray#" GenPrimOp
753    MutableByteArray# s -> Int# -> State# s -> (# State# s, Float# #)
754    with has_side_effects = True
755
756 primop  ReadByteArrayOp_Double "readDoubleArray#" GenPrimOp
757    MutableByteArray# s -> Int# -> State# s -> (# State# s, Double# #)
758    with has_side_effects = True
759
760 primop  ReadByteArrayOp_StablePtr "readStablePtrArray#" GenPrimOp
761    MutableByteArray# s -> Int# -> State# s -> (# State# s, StablePtr# a #)
762    with has_side_effects = True
763
764 primop  ReadByteArrayOp_Int8 "readInt8Array#" GenPrimOp
765    MutableByteArray# s -> Int# -> State# s -> (# State# s, Int# #)
766    with has_side_effects = True
767
768 primop  ReadByteArrayOp_Int16 "readInt16Array#" GenPrimOp
769    MutableByteArray# s -> Int# -> State# s -> (# State# s, Int# #)
770    with has_side_effects = True
771
772 primop  ReadByteArrayOp_Int32 "readInt32Array#" GenPrimOp
773    MutableByteArray# s -> Int# -> State# s -> (# State# s, INT32 #)
774    with has_side_effects = True
775
776 primop  ReadByteArrayOp_Int64 "readInt64Array#" GenPrimOp
777    MutableByteArray# s -> Int# -> State# s -> (# State# s, INT64 #)
778    with has_side_effects = True
779
780 primop  ReadByteArrayOp_Word8 "readWord8Array#" GenPrimOp
781    MutableByteArray# s -> Int# -> State# s -> (# State# s, Word# #)
782    with has_side_effects = True
783
784 primop  ReadByteArrayOp_Word16 "readWord16Array#" GenPrimOp
785    MutableByteArray# s -> Int# -> State# s -> (# State# s, Word# #)
786    with has_side_effects = True
787
788 primop  ReadByteArrayOp_Word32 "readWord32Array#" GenPrimOp
789    MutableByteArray# s -> Int# -> State# s -> (# State# s, WORD32 #)
790    with has_side_effects = True
791
792 primop  ReadByteArrayOp_Word64 "readWord64Array#" GenPrimOp
793    MutableByteArray# s -> Int# -> State# s -> (# State# s, WORD64 #)
794    with has_side_effects = True
795
796 primop  WriteByteArrayOp_Char "writeCharArray#" GenPrimOp
797    MutableByteArray# s -> Int# -> Char# -> State# s -> State# s
798    {Write 8-bit character; offset in bytes.}
799    with has_side_effects = True
800
801 primop  WriteByteArrayOp_WideChar "writeWideCharArray#" GenPrimOp
802    MutableByteArray# s -> Int# -> Char# -> State# s -> State# s
803    {Write 31-bit character; offset in 4-byte words.}
804    with has_side_effects = True
805
806 primop  WriteByteArrayOp_Int "writeIntArray#" GenPrimOp
807    MutableByteArray# s -> Int# -> Int# -> State# s -> State# s
808    with has_side_effects = True
809
810 primop  WriteByteArrayOp_Word "writeWordArray#" GenPrimOp
811    MutableByteArray# s -> Int# -> Word# -> State# s -> State# s
812    with has_side_effects = True
813
814 primop  WriteByteArrayOp_Addr "writeAddrArray#" GenPrimOp
815    MutableByteArray# s -> Int# -> Addr# -> State# s -> State# s
816    with has_side_effects = True
817
818 primop  WriteByteArrayOp_Float "writeFloatArray#" GenPrimOp
819    MutableByteArray# s -> Int# -> Float# -> State# s -> State# s
820    with has_side_effects = True
821
822 primop  WriteByteArrayOp_Double "writeDoubleArray#" GenPrimOp
823    MutableByteArray# s -> Int# -> Double# -> State# s -> State# s
824    with has_side_effects = True
825
826 primop  WriteByteArrayOp_StablePtr "writeStablePtrArray#" GenPrimOp
827    MutableByteArray# s -> Int# -> StablePtr# a -> State# s -> State# s
828    with has_side_effects = True
829
830 primop  WriteByteArrayOp_Int8 "writeInt8Array#" GenPrimOp
831    MutableByteArray# s -> Int# -> Int# -> State# s -> State# s
832    with has_side_effects = True
833
834 primop  WriteByteArrayOp_Int16 "writeInt16Array#" GenPrimOp
835    MutableByteArray# s -> Int# -> Int# -> State# s -> State# s
836    with has_side_effects = True
837
838 primop  WriteByteArrayOp_Int32 "writeInt32Array#" GenPrimOp
839    MutableByteArray# s -> Int# -> INT32 -> State# s -> State# s
840    with has_side_effects = True
841
842 primop  WriteByteArrayOp_Int64 "writeInt64Array#" GenPrimOp
843    MutableByteArray# s -> Int# -> INT64 -> State# s -> State# s
844    with has_side_effects = True
845
846 primop  WriteByteArrayOp_Word8 "writeWord8Array#" GenPrimOp
847    MutableByteArray# s -> Int# -> Word# -> State# s -> State# s
848    with has_side_effects = True
849
850 primop  WriteByteArrayOp_Word16 "writeWord16Array#" GenPrimOp
851    MutableByteArray# s -> Int# -> Word# -> State# s -> State# s
852    with has_side_effects = True
853
854 primop  WriteByteArrayOp_Word32 "writeWord32Array#" GenPrimOp
855    MutableByteArray# s -> Int# -> WORD32 -> State# s -> State# s
856    with has_side_effects = True
857
858 primop  WriteByteArrayOp_Word64 "writeWord64Array#" GenPrimOp
859    MutableByteArray# s -> Int# -> WORD64 -> State# s -> State# s
860    with has_side_effects = True
861
862 ------------------------------------------------------------------------
863 section "Addr#"
864 ------------------------------------------------------------------------
865
866 primtype Addr#
867         { An arbitrary machine address assumed to point outside
868          the garbage-collected heap. }
869
870 pseudoop "nullAddr#" Addr#
871         { The null address. }
872
873 primop   AddrAddOp "plusAddr#" GenPrimOp Addr# -> Int# -> Addr#
874 primop   AddrSubOp "minusAddr#" GenPrimOp Addr# -> Addr# -> Int#
875          {Result is meaningless if two {\tt Addr\#}s are so far apart that their
876          difference doesn't fit in an {\tt Int\#}.}
877 primop   AddrRemOp "remAddr#" GenPrimOp Addr# -> Int# -> Int#
878          {Return the remainder when the {\tt Addr\#} arg, treated like an {\tt Int\#},
879           is divided by the {\tt Int\#} arg.}
880 #if (WORD_SIZE_IN_BITS == 32 || WORD_SIZE_IN_BITS == 64)
881 primop   Addr2IntOp  "addr2Int#"     GenPrimOp   Addr# -> Int#
882         {Coerce directly from address to int. Strongly deprecated.}
883 primop   Int2AddrOp   "int2Addr#"    GenPrimOp  Int# -> Addr#
884         {Coerce directly from int to address. Strongly deprecated.}
885 #endif
886
887 primop   AddrGtOp  "gtAddr#"   Compare   Addr# -> Addr# -> Bool
888 primop   AddrGeOp  "geAddr#"   Compare   Addr# -> Addr# -> Bool
889 primop   AddrEqOp  "eqAddr#"   Compare   Addr# -> Addr# -> Bool
890 primop   AddrNeOp  "neAddr#"   Compare   Addr# -> Addr# -> Bool
891 primop   AddrLtOp  "ltAddr#"   Compare   Addr# -> Addr# -> Bool
892 primop   AddrLeOp  "leAddr#"   Compare   Addr# -> Addr# -> Bool
893
894 primop IndexOffAddrOp_Char "indexCharOffAddr#" GenPrimOp
895    Addr# -> Int# -> Char#
896    {Reads 8-bit character; offset in bytes.}
897
898 primop IndexOffAddrOp_WideChar "indexWideCharOffAddr#" GenPrimOp
899    Addr# -> Int# -> Char#
900    {Reads 31-bit character; offset in 4-byte words.}
901
902 primop IndexOffAddrOp_Int "indexIntOffAddr#" GenPrimOp
903    Addr# -> Int# -> Int#
904
905 primop IndexOffAddrOp_Word "indexWordOffAddr#" GenPrimOp
906    Addr# -> Int# -> Word#
907
908 primop IndexOffAddrOp_Addr "indexAddrOffAddr#" GenPrimOp
909    Addr# -> Int# -> Addr#
910
911 primop IndexOffAddrOp_Float "indexFloatOffAddr#" GenPrimOp
912    Addr# -> Int# -> Float#
913
914 primop IndexOffAddrOp_Double "indexDoubleOffAddr#" GenPrimOp
915    Addr# -> Int# -> Double#
916
917 primop IndexOffAddrOp_StablePtr "indexStablePtrOffAddr#" GenPrimOp
918    Addr# -> Int# -> StablePtr# a
919
920 primop IndexOffAddrOp_Int8 "indexInt8OffAddr#" GenPrimOp
921    Addr# -> Int# -> Int#
922
923 primop IndexOffAddrOp_Int16 "indexInt16OffAddr#" GenPrimOp
924    Addr# -> Int# -> Int#
925
926 primop IndexOffAddrOp_Int32 "indexInt32OffAddr#" GenPrimOp
927    Addr# -> Int# -> INT32
928
929 primop IndexOffAddrOp_Int64 "indexInt64OffAddr#" GenPrimOp
930    Addr# -> Int# -> INT64
931
932 primop IndexOffAddrOp_Word8 "indexWord8OffAddr#" GenPrimOp
933    Addr# -> Int# -> Word#
934
935 primop IndexOffAddrOp_Word16 "indexWord16OffAddr#" GenPrimOp
936    Addr# -> Int# -> Word#
937
938 primop IndexOffAddrOp_Word32 "indexWord32OffAddr#" GenPrimOp
939    Addr# -> Int# -> WORD32
940
941 primop IndexOffAddrOp_Word64 "indexWord64OffAddr#" GenPrimOp
942    Addr# -> Int# -> WORD64
943
944 primop ReadOffAddrOp_Char "readCharOffAddr#" GenPrimOp
945    Addr# -> Int# -> State# s -> (# State# s, Char# #)
946    {Reads 8-bit character; offset in bytes.}
947    with has_side_effects = True
948
949 primop ReadOffAddrOp_WideChar "readWideCharOffAddr#" GenPrimOp
950    Addr# -> Int# -> State# s -> (# State# s, Char# #)
951    {Reads 31-bit character; offset in 4-byte words.}
952    with has_side_effects = True
953
954 primop ReadOffAddrOp_Int "readIntOffAddr#" GenPrimOp
955    Addr# -> Int# -> State# s -> (# State# s, Int# #)
956    with has_side_effects = True
957
958 primop ReadOffAddrOp_Word "readWordOffAddr#" GenPrimOp
959    Addr# -> Int# -> State# s -> (# State# s, Word# #)
960    with has_side_effects = True
961
962 primop ReadOffAddrOp_Addr "readAddrOffAddr#" GenPrimOp
963    Addr# -> Int# -> State# s -> (# State# s, Addr# #)
964    with has_side_effects = True
965
966 primop ReadOffAddrOp_Float "readFloatOffAddr#" GenPrimOp
967    Addr# -> Int# -> State# s -> (# State# s, Float# #)
968    with has_side_effects = True
969
970 primop ReadOffAddrOp_Double "readDoubleOffAddr#" GenPrimOp
971    Addr# -> Int# -> State# s -> (# State# s, Double# #)
972    with has_side_effects = True
973
974 primop ReadOffAddrOp_StablePtr "readStablePtrOffAddr#" GenPrimOp
975    Addr# -> Int# -> State# s -> (# State# s, StablePtr# a #)
976    with has_side_effects = True
977
978 primop ReadOffAddrOp_Int8 "readInt8OffAddr#" GenPrimOp
979    Addr# -> Int# -> State# s -> (# State# s, Int# #)
980    with has_side_effects = True
981
982 primop ReadOffAddrOp_Int16 "readInt16OffAddr#" GenPrimOp
983    Addr# -> Int# -> State# s -> (# State# s, Int# #)
984    with has_side_effects = True
985
986 primop ReadOffAddrOp_Int32 "readInt32OffAddr#" GenPrimOp
987    Addr# -> Int# -> State# s -> (# State# s, INT32 #)
988    with has_side_effects = True
989
990 primop ReadOffAddrOp_Int64 "readInt64OffAddr#" GenPrimOp
991    Addr# -> Int# -> State# s -> (# State# s, INT64 #)
992    with has_side_effects = True
993
994 primop ReadOffAddrOp_Word8 "readWord8OffAddr#" GenPrimOp
995    Addr# -> Int# -> State# s -> (# State# s, Word# #)
996    with has_side_effects = True
997
998 primop ReadOffAddrOp_Word16 "readWord16OffAddr#" GenPrimOp
999    Addr# -> Int# -> State# s -> (# State# s, Word# #)
1000    with has_side_effects = True
1001
1002 primop ReadOffAddrOp_Word32 "readWord32OffAddr#" GenPrimOp
1003    Addr# -> Int# -> State# s -> (# State# s, WORD32 #)
1004    with has_side_effects = True
1005
1006 primop ReadOffAddrOp_Word64 "readWord64OffAddr#" GenPrimOp
1007    Addr# -> Int# -> State# s -> (# State# s, WORD64 #)
1008    with has_side_effects = True
1009
1010
1011 primop  WriteOffAddrOp_Char "writeCharOffAddr#" GenPrimOp
1012    Addr# -> Int# -> Char# -> State# s -> State# s
1013    with has_side_effects = True
1014
1015 primop  WriteOffAddrOp_WideChar "writeWideCharOffAddr#" GenPrimOp
1016    Addr# -> Int# -> Char# -> State# s -> State# s
1017    with has_side_effects = True
1018
1019 primop  WriteOffAddrOp_Int "writeIntOffAddr#" GenPrimOp
1020    Addr# -> Int# -> Int# -> State# s -> State# s
1021    with has_side_effects = True
1022
1023 primop  WriteOffAddrOp_Word "writeWordOffAddr#" GenPrimOp
1024    Addr# -> Int# -> Word# -> State# s -> State# s
1025    with has_side_effects = True
1026
1027 primop  WriteOffAddrOp_Addr "writeAddrOffAddr#" GenPrimOp
1028    Addr# -> Int# -> Addr# -> State# s -> State# s
1029    with has_side_effects = True
1030
1031 primop  WriteOffAddrOp_Float "writeFloatOffAddr#" GenPrimOp
1032    Addr# -> Int# -> Float# -> State# s -> State# s
1033    with has_side_effects = True
1034
1035 primop  WriteOffAddrOp_Double "writeDoubleOffAddr#" GenPrimOp
1036    Addr# -> Int# -> Double# -> State# s -> State# s
1037    with has_side_effects = True
1038
1039 primop  WriteOffAddrOp_StablePtr "writeStablePtrOffAddr#" GenPrimOp
1040    Addr# -> Int# -> StablePtr# a -> State# s -> State# s
1041    with has_side_effects = True
1042
1043 primop  WriteOffAddrOp_Int8 "writeInt8OffAddr#" GenPrimOp
1044    Addr# -> Int# -> Int# -> State# s -> State# s
1045    with has_side_effects = True
1046
1047 primop  WriteOffAddrOp_Int16 "writeInt16OffAddr#" GenPrimOp
1048    Addr# -> Int# -> Int# -> State# s -> State# s
1049    with has_side_effects = True
1050
1051 primop  WriteOffAddrOp_Int32 "writeInt32OffAddr#" GenPrimOp
1052    Addr# -> Int# -> INT32 -> State# s -> State# s
1053    with has_side_effects = True
1054
1055 primop  WriteOffAddrOp_Int64 "writeInt64OffAddr#" GenPrimOp
1056    Addr# -> Int# -> INT64 -> State# s -> State# s
1057    with has_side_effects = True
1058
1059 primop  WriteOffAddrOp_Word8 "writeWord8OffAddr#" GenPrimOp
1060    Addr# -> Int# -> Word# -> State# s -> State# s
1061    with has_side_effects = True
1062
1063 primop  WriteOffAddrOp_Word16 "writeWord16OffAddr#" GenPrimOp
1064    Addr# -> Int# -> Word# -> State# s -> State# s
1065    with has_side_effects = True
1066
1067 primop  WriteOffAddrOp_Word32 "writeWord32OffAddr#" GenPrimOp
1068    Addr# -> Int# -> WORD32 -> State# s -> State# s
1069    with has_side_effects = True
1070
1071 primop  WriteOffAddrOp_Word64 "writeWord64OffAddr#" GenPrimOp
1072    Addr# -> Int# -> WORD64 -> State# s -> State# s
1073    with has_side_effects = True
1074
1075 ------------------------------------------------------------------------
1076 section "Mutable variables"
1077         {Operations on MutVar\#s.}
1078 ------------------------------------------------------------------------
1079
1080 primtype MutVar# s a
1081         {A {\tt MutVar\#} behaves like a single-element mutable array.}
1082
1083 primop  NewMutVarOp "newMutVar#" GenPrimOp
1084    a -> State# s -> (# State# s, MutVar# s a #)
1085    {Create {\tt MutVar\#} with specified initial value in specified state thread.}
1086    with
1087    out_of_line = True
1088    has_side_effects = True
1089
1090 primop  ReadMutVarOp "readMutVar#" GenPrimOp
1091    MutVar# s a -> State# s -> (# State# s, a #)
1092    {Read contents of {\tt MutVar\#}. Result is not yet evaluated.}
1093    with
1094    has_side_effects = True
1095
1096 primop  WriteMutVarOp "writeMutVar#"  GenPrimOp
1097    MutVar# s a -> a -> State# s -> State# s
1098    {Write contents of {\tt MutVar\#}.}
1099    with
1100    has_side_effects = True
1101
1102 primop  SameMutVarOp "sameMutVar#" GenPrimOp
1103    MutVar# s a -> MutVar# s a -> Bool
1104
1105 -- not really the right type, but we don't know about pairs here.  The
1106 -- correct type is
1107 --
1108 --   MutVar# s a -> (a -> (a,b)) -> State# s -> (# State# s, b #)
1109 --
1110 primop  AtomicModifyMutVarOp "atomicModifyMutVar#" GenPrimOp
1111    MutVar# s a -> (a -> b) -> State# s -> (# State# s, c #)
1112    with
1113    out_of_line = True
1114    has_side_effects = True
1115
1116 ------------------------------------------------------------------------
1117 section "Exceptions"
1118 ------------------------------------------------------------------------
1119
1120 primop  CatchOp "catch#" GenPrimOp
1121           (State# RealWorld -> (# State# RealWorld, a #) )
1122        -> (b -> State# RealWorld -> (# State# RealWorld, a #) ) 
1123        -> State# RealWorld
1124        -> (# State# RealWorld, a #)
1125    with
1126         -- Catch is actually strict in its first argument
1127         -- but we don't want to tell the strictness
1128         -- analyser about that!
1129         -- might use caught action multiply
1130    out_of_line = True
1131    has_side_effects = True
1132
1133 primop  RaiseOp "raise#" GenPrimOp
1134    a -> b
1135    with
1136    strictness  = { \ _arity -> mkStrictSig (mkTopDmdType [lazyDmd] BotRes) }
1137       -- NB: result is bottom
1138    out_of_line = True
1139
1140 -- raiseIO# needs to be a primop, because exceptions in the IO monad
1141 -- must be *precise* - we don't want the strictness analyser turning
1142 -- one kind of bottom into another, as it is allowed to do in pure code.
1143
1144 primop  RaiseIOOp "raiseIO#" GenPrimOp
1145    a -> State# RealWorld -> (# State# RealWorld, b #)
1146    with
1147    out_of_line = True
1148    has_side_effects = True
1149
1150 primop  MaskAsyncExceptionsOp "maskAsyncExceptions#" GenPrimOp
1151         (State# RealWorld -> (# State# RealWorld, a #))
1152      -> (State# RealWorld -> (# State# RealWorld, a #))
1153    with
1154    out_of_line = True
1155    has_side_effects = True
1156
1157 primop  MaskUninterruptibleOp "maskUninterruptible#" GenPrimOp
1158         (State# RealWorld -> (# State# RealWorld, a #))
1159      -> (State# RealWorld -> (# State# RealWorld, a #))
1160    with
1161    out_of_line = True
1162    has_side_effects = True
1163
1164 primop  UnmaskAsyncExceptionsOp "unmaskAsyncExceptions#" GenPrimOp
1165         (State# RealWorld -> (# State# RealWorld, a #))
1166      -> (State# RealWorld -> (# State# RealWorld, a #))
1167    with
1168    out_of_line = True
1169    has_side_effects = True
1170
1171 primop  MaskStatus "getMaskingState#" GenPrimOp
1172         State# RealWorld -> (# State# RealWorld, Int# #)
1173    with
1174    out_of_line = True
1175    has_side_effects = True
1176
1177 ------------------------------------------------------------------------
1178 section "STM-accessible Mutable Variables"
1179 ------------------------------------------------------------------------
1180
1181 primtype TVar# s a
1182
1183 primop  AtomicallyOp "atomically#" GenPrimOp
1184       (State# RealWorld -> (# State# RealWorld, a #) )
1185    -> State# RealWorld -> (# State# RealWorld, a #)
1186    with
1187    out_of_line = True
1188    has_side_effects = True
1189
1190 primop  RetryOp "retry#" GenPrimOp
1191    State# RealWorld -> (# State# RealWorld, a #)
1192    with 
1193    out_of_line = True
1194    has_side_effects = True
1195
1196 primop  CatchRetryOp "catchRetry#" GenPrimOp
1197       (State# RealWorld -> (# State# RealWorld, a #) )
1198    -> (State# RealWorld -> (# State# RealWorld, a #) )
1199    -> (State# RealWorld -> (# State# RealWorld, a #) )
1200    with 
1201    out_of_line = True
1202    has_side_effects = True
1203
1204 primop  CatchSTMOp "catchSTM#" GenPrimOp
1205       (State# RealWorld -> (# State# RealWorld, a #) )
1206    -> (b -> State# RealWorld -> (# State# RealWorld, a #) )
1207    -> (State# RealWorld -> (# State# RealWorld, a #) )
1208    with 
1209    out_of_line = True
1210    has_side_effects = True
1211
1212 primop  Check "check#" GenPrimOp
1213       (State# RealWorld -> (# State# RealWorld, a #) )
1214    -> (State# RealWorld -> (# State# RealWorld, () #) )
1215    with 
1216    out_of_line = True
1217    has_side_effects = True
1218
1219 primop  NewTVarOp "newTVar#" GenPrimOp
1220        a
1221     -> State# s -> (# State# s, TVar# s a #)
1222    {Create a new {\tt TVar\#} holding a specified initial value.}
1223    with
1224    out_of_line  = True
1225    has_side_effects = True
1226
1227 primop  ReadTVarOp "readTVar#" GenPrimOp
1228        TVar# s a
1229     -> State# s -> (# State# s, a #)
1230    {Read contents of {\tt TVar\#}.  Result is not yet evaluated.}
1231    with
1232    out_of_line  = True
1233    has_side_effects = True
1234
1235 primop ReadTVarIOOp "readTVarIO#" GenPrimOp
1236        TVar# s a
1237     -> State# s -> (# State# s, a #)
1238    {Read contents of {\tt TVar\#} outside an STM transaction}
1239    with
1240    out_of_line  = True
1241    has_side_effects = True
1242
1243 primop  WriteTVarOp "writeTVar#" GenPrimOp
1244        TVar# s a
1245     -> a
1246     -> State# s -> State# s
1247    {Write contents of {\tt TVar\#}.}
1248    with
1249    out_of_line      = True
1250    has_side_effects = True
1251
1252 primop  SameTVarOp "sameTVar#" GenPrimOp
1253    TVar# s a -> TVar# s a -> Bool
1254
1255
1256 ------------------------------------------------------------------------
1257 section "Synchronized Mutable Variables"
1258         {Operations on {\tt MVar\#}s. }
1259 ------------------------------------------------------------------------
1260
1261 primtype MVar# s a
1262         { A shared mutable variable ({\it not} the same as a {\tt MutVar\#}!).
1263         (Note: in a non-concurrent implementation, {\tt (MVar\# a)} can be
1264         represented by {\tt (MutVar\# (Maybe a))}.) }
1265
1266 primop  NewMVarOp "newMVar#"  GenPrimOp
1267    State# s -> (# State# s, MVar# s a #)
1268    {Create new {\tt MVar\#}; initially empty.}
1269    with
1270    out_of_line = True
1271    has_side_effects = True
1272
1273 primop  TakeMVarOp "takeMVar#" GenPrimOp
1274    MVar# s a -> State# s -> (# State# s, a #)
1275    {If {\tt MVar\#} is empty, block until it becomes full.
1276    Then remove and return its contents, and set it empty.}
1277    with
1278    out_of_line      = True
1279    has_side_effects = True
1280
1281 primop  TryTakeMVarOp "tryTakeMVar#" GenPrimOp
1282    MVar# s a -> State# s -> (# State# s, Int#, a #)
1283    {If {\tt MVar\#} is empty, immediately return with integer 0 and value undefined.
1284    Otherwise, return with integer 1 and contents of {\tt MVar\#}, and set {\tt MVar\#} empty.}
1285    with
1286    out_of_line      = True
1287    has_side_effects = True
1288
1289 primop  PutMVarOp "putMVar#" GenPrimOp
1290    MVar# s a -> a -> State# s -> State# s
1291    {If {\tt MVar\#} is full, block until it becomes empty.
1292    Then store value arg as its new contents.}
1293    with
1294    out_of_line      = True
1295    has_side_effects = True
1296
1297 primop  TryPutMVarOp "tryPutMVar#" GenPrimOp
1298    MVar# s a -> a -> State# s -> (# State# s, Int# #)
1299    {If {\tt MVar\#} is full, immediately return with integer 0.
1300     Otherwise, store value arg as {\tt MVar\#}'s new contents, and return with integer 1.}
1301    with
1302    out_of_line      = True
1303    has_side_effects = True
1304
1305 primop  SameMVarOp "sameMVar#" GenPrimOp
1306    MVar# s a -> MVar# s a -> Bool
1307
1308 primop  IsEmptyMVarOp "isEmptyMVar#" GenPrimOp
1309    MVar# s a -> State# s -> (# State# s, Int# #)
1310    {Return 1 if {\tt MVar\#} is empty; 0 otherwise.}
1311    with
1312    out_of_line = True
1313    has_side_effects = True
1314
1315 ------------------------------------------------------------------------
1316 section "Delay/wait operations"
1317 ------------------------------------------------------------------------
1318
1319 primop  DelayOp "delay#" GenPrimOp
1320    Int# -> State# s -> State# s
1321    {Sleep specified number of microseconds.}
1322    with
1323    needs_wrapper    = True
1324    has_side_effects = True
1325    out_of_line      = True
1326
1327 primop  WaitReadOp "waitRead#" GenPrimOp
1328    Int# -> State# s -> State# s
1329    {Block until input is available on specified file descriptor.}
1330    with
1331    needs_wrapper    = True
1332    has_side_effects = True
1333    out_of_line      = True
1334
1335 primop  WaitWriteOp "waitWrite#" GenPrimOp
1336    Int# -> State# s -> State# s
1337    {Block until output is possible on specified file descriptor.}
1338    with
1339    needs_wrapper    = True
1340    has_side_effects = True
1341    out_of_line      = True
1342
1343 #ifdef mingw32_TARGET_OS
1344 primop  AsyncReadOp "asyncRead#" GenPrimOp
1345    Int# -> Int# -> Int# -> Addr# -> State# RealWorld-> (# State# RealWorld, Int#, Int# #)
1346    {Asynchronously read bytes from specified file descriptor.}
1347    with
1348    needs_wrapper    = True
1349    has_side_effects = True
1350    out_of_line      = True
1351
1352 primop  AsyncWriteOp "asyncWrite#" GenPrimOp
1353    Int# -> Int# -> Int# -> Addr# -> State# RealWorld-> (# State# RealWorld, Int#, Int# #)
1354    {Asynchronously write bytes from specified file descriptor.}
1355    with
1356    needs_wrapper    = True
1357    has_side_effects = True
1358    out_of_line      = True
1359
1360 primop  AsyncDoProcOp "asyncDoProc#" GenPrimOp
1361    Addr# -> Addr# -> State# RealWorld-> (# State# RealWorld, Int#, Int# #)
1362    {Asynchronously perform procedure (first arg), passing it 2nd arg.}
1363    with
1364    needs_wrapper    = True
1365    has_side_effects = True
1366    out_of_line      = True
1367
1368 #endif
1369
1370 ------------------------------------------------------------------------
1371 section "Concurrency primitives"
1372 ------------------------------------------------------------------------
1373
1374 primtype State# s
1375         { {\tt State\#} is the primitive, unlifted type of states.  It has
1376         one type parameter, thus {\tt State\# RealWorld}, or {\tt State\# s},
1377         where s is a type variable. The only purpose of the type parameter
1378         is to keep different state threads separate.  It is represented by
1379         nothing at all. }
1380
1381 primtype RealWorld
1382         { {\tt RealWorld} is deeply magical.  It is {\it primitive}, but it is not
1383         {\it unlifted} (hence {\tt ptrArg}).  We never manipulate values of type
1384         {\tt RealWorld}; it's only used in the type system, to parameterise {\tt State\#}. }
1385
1386 primtype ThreadId#
1387         {(In a non-concurrent implementation, this can be a singleton
1388         type, whose (unique) value is returned by {\tt myThreadId\#}.  The 
1389         other operations can be omitted.)}
1390
1391 primop  ForkOp "fork#" GenPrimOp
1392    a -> State# RealWorld -> (# State# RealWorld, ThreadId# #)
1393    with
1394    has_side_effects = True
1395    out_of_line      = True
1396
1397 primop  ForkOnOp "forkOn#" GenPrimOp
1398    Int# -> a -> State# RealWorld -> (# State# RealWorld, ThreadId# #)
1399    with
1400    has_side_effects = True
1401    out_of_line      = True
1402
1403 primop  KillThreadOp "killThread#"  GenPrimOp
1404    ThreadId# -> a -> State# RealWorld -> State# RealWorld
1405    with
1406    has_side_effects = True
1407    out_of_line      = True
1408
1409 primop  YieldOp "yield#" GenPrimOp
1410    State# RealWorld -> State# RealWorld
1411    with
1412    has_side_effects = True
1413    out_of_line      = True
1414
1415 primop  MyThreadIdOp "myThreadId#" GenPrimOp
1416    State# RealWorld -> (# State# RealWorld, ThreadId# #)
1417    with
1418    out_of_line = True
1419    has_side_effects = True
1420
1421 primop LabelThreadOp "labelThread#" GenPrimOp
1422    ThreadId# -> Addr# -> State# RealWorld -> State# RealWorld
1423    with
1424    has_side_effects = True
1425    out_of_line      = True
1426    
1427 primop  IsCurrentThreadBoundOp "isCurrentThreadBound#" GenPrimOp
1428    State# RealWorld -> (# State# RealWorld, Int# #)
1429    with
1430    out_of_line = True
1431    has_side_effects = True
1432
1433 primop  NoDuplicateOp "noDuplicate#" GenPrimOp
1434    State# RealWorld -> State# RealWorld
1435    with
1436    out_of_line = True
1437    has_side_effects = True
1438
1439 primop  ThreadStatusOp "threadStatus#" GenPrimOp
1440    ThreadId# -> State# RealWorld -> (# State# RealWorld, Int# #)
1441    with
1442    out_of_line = True
1443    has_side_effects = True
1444
1445 ------------------------------------------------------------------------
1446 section "Weak pointers"
1447 ------------------------------------------------------------------------
1448
1449 primtype Weak# b
1450
1451 -- note that tyvar "o" denotes openAlphaTyVar
1452
1453 primop  MkWeakOp "mkWeak#" GenPrimOp
1454    o -> b -> c -> State# RealWorld -> (# State# RealWorld, Weak# b #)
1455    with
1456    has_side_effects = True
1457    out_of_line      = True
1458
1459 primop  MkWeakForeignEnvOp "mkWeakForeignEnv#" GenPrimOp
1460    o -> b -> Addr# -> Addr# -> Int# -> Addr# -> State# RealWorld -> (# State# RealWorld, Weak# b #)
1461    with
1462    has_side_effects = True
1463    out_of_line      = True
1464
1465 primop  DeRefWeakOp "deRefWeak#" GenPrimOp
1466    Weak# a -> State# RealWorld -> (# State# RealWorld, Int#, a #)
1467    with
1468    has_side_effects = True
1469    out_of_line      = True
1470
1471 primop  FinalizeWeakOp "finalizeWeak#" GenPrimOp
1472    Weak# a -> State# RealWorld -> (# State# RealWorld, Int#, 
1473               (State# RealWorld -> (# State# RealWorld, () #)) #)
1474    with
1475    has_side_effects = True
1476    out_of_line      = True
1477
1478 primop TouchOp "touch#" GenPrimOp
1479    o -> State# RealWorld -> State# RealWorld
1480    with
1481    has_side_effects = True
1482
1483 ------------------------------------------------------------------------
1484 section "Stable pointers and names"
1485 ------------------------------------------------------------------------
1486
1487 primtype StablePtr# a
1488
1489 primtype StableName# a
1490
1491 primop  MakeStablePtrOp "makeStablePtr#" GenPrimOp
1492    a -> State# RealWorld -> (# State# RealWorld, StablePtr# a #)
1493    with
1494    has_side_effects = True
1495    out_of_line      = True
1496
1497 primop  DeRefStablePtrOp "deRefStablePtr#" GenPrimOp
1498    StablePtr# a -> State# RealWorld -> (# State# RealWorld, a #)
1499    with
1500    needs_wrapper    = True
1501    has_side_effects = True
1502    out_of_line      = True
1503
1504 primop  EqStablePtrOp "eqStablePtr#" GenPrimOp
1505    StablePtr# a -> StablePtr# a -> Int#
1506    with
1507    has_side_effects = True
1508
1509 primop  MakeStableNameOp "makeStableName#" GenPrimOp
1510    a -> State# RealWorld -> (# State# RealWorld, StableName# a #)
1511    with
1512    needs_wrapper    = True
1513    has_side_effects = True
1514    out_of_line      = True
1515
1516 primop  EqStableNameOp "eqStableName#" GenPrimOp
1517    StableName# a -> StableName# a -> Int#
1518
1519 primop  StableNameToIntOp "stableNameToInt#" GenPrimOp
1520    StableName# a -> Int#
1521
1522 ------------------------------------------------------------------------
1523 section "Unsafe pointer equality"
1524 --  (#1 Bad Guy: Alistair Reid :)   
1525 ------------------------------------------------------------------------
1526
1527 primop  ReallyUnsafePtrEqualityOp "reallyUnsafePtrEquality#" GenPrimOp
1528    a -> a -> Int#
1529
1530 ------------------------------------------------------------------------
1531 section "Parallelism"
1532 ------------------------------------------------------------------------
1533
1534 primop  ParOp "par#" GenPrimOp
1535    a -> Int#
1536    with
1537       -- Note that Par is lazy to avoid that the sparked thing
1538       -- gets evaluted strictly, which it should *not* be
1539    has_side_effects = True
1540
1541 primop GetSparkOp "getSpark#" GenPrimOp
1542    State# s -> (# State# s, Int#, a #)
1543    with
1544    has_side_effects = True
1545    out_of_line = True
1546
1547 -- HWL: The first 4 Int# in all par... annotations denote:
1548 --   name, granularity info, size of result, degree of parallelism
1549 --      Same  structure as _seq_ i.e. returns Int#
1550 -- KSW: v, the second arg in parAt# and parAtForNow#, is used only to determine
1551 --   `the processor containing the expression v'; it is not evaluated
1552
1553 primop  ParGlobalOp  "parGlobal#"  GenPrimOp
1554    a -> Int# -> Int# -> Int# -> Int# -> b -> Int#
1555    with
1556    has_side_effects = True
1557
1558 primop  ParLocalOp  "parLocal#"  GenPrimOp
1559    a -> Int# -> Int# -> Int# -> Int# -> b -> Int#
1560    with
1561    has_side_effects = True
1562
1563 primop  ParAtOp  "parAt#"  GenPrimOp
1564    b -> a -> Int# -> Int# -> Int# -> Int# -> c -> Int#
1565    with
1566    has_side_effects = True
1567
1568 primop  ParAtAbsOp  "parAtAbs#"  GenPrimOp
1569    a -> Int# -> Int# -> Int# -> Int# -> Int# -> b -> Int#
1570    with
1571    has_side_effects = True
1572
1573 primop  ParAtRelOp  "parAtRel#" GenPrimOp
1574    a -> Int# -> Int# -> Int# -> Int# -> Int# -> b -> Int#
1575    with
1576    has_side_effects = True
1577
1578 primop  ParAtForNowOp  "parAtForNow#" GenPrimOp
1579    b -> a -> Int# -> Int# -> Int# -> Int# -> c -> Int#
1580    with
1581    has_side_effects = True
1582
1583 -- copyable# and noFollow# are yet to be implemented (for GpH)
1584 --
1585 --primop  CopyableOp  "copyable#" GenPrimOp
1586 --   a -> Int#
1587 --   with
1588 --   has_side_effects = True
1589 --
1590 --primop  NoFollowOp "noFollow#" GenPrimOp
1591 --   a -> Int#
1592 --   with
1593 --   has_side_effects = True
1594
1595
1596 ------------------------------------------------------------------------
1597 section "Tag to enum stuff"
1598         {Convert back and forth between values of enumerated types
1599         and small integers.}
1600 ------------------------------------------------------------------------
1601
1602 primop  DataToTagOp "dataToTag#" GenPrimOp
1603    a -> Int#
1604    with
1605    strictness  = { \ _arity -> mkStrictSig (mkTopDmdType [seqDmd] TopRes) }
1606         -- dataToTag# must have an evaluated argument
1607
1608 primop  TagToEnumOp "tagToEnum#" GenPrimOp     
1609    Int# -> a
1610
1611 ------------------------------------------------------------------------
1612 section "Bytecode operations" 
1613         {Support for the bytecode interpreter and linker.}
1614 ------------------------------------------------------------------------
1615
1616 primtype BCO#
1617    {Primitive bytecode type.}
1618
1619 primop   AddrToHValueOp "addrToHValue#" GenPrimOp
1620    Addr# -> (# a #)
1621    {Convert an {\tt Addr\#} to a followable type.}
1622
1623 primop   MkApUpd0_Op "mkApUpd0#" GenPrimOp
1624    BCO# -> (# a #)
1625    with
1626    out_of_line = True
1627
1628 primop  NewBCOOp "newBCO#" GenPrimOp
1629    ByteArray# -> ByteArray# -> Array# a -> Int# -> ByteArray# -> State# s -> (# State# s, BCO# #)
1630    with
1631    has_side_effects = True
1632    out_of_line      = True
1633
1634 primop  UnpackClosureOp "unpackClosure#" GenPrimOp
1635    a -> (# Addr#, Array# b, ByteArray# #)
1636    with
1637    out_of_line = True
1638
1639 primop  GetApStackValOp "getApStackVal#" GenPrimOp
1640    a -> Int# -> (# Int#, b #)
1641    with
1642    out_of_line = True
1643
1644 ------------------------------------------------------------------------
1645 section "Misc"
1646         {These aren't nearly as wired in as Etc...}
1647 ------------------------------------------------------------------------
1648
1649 primop  TraceCcsOp "traceCcs#" GenPrimOp
1650    a -> b -> b
1651    with
1652    has_side_effects = True
1653    out_of_line = True
1654
1655 ------------------------------------------------------------------------
1656 section "Etc" 
1657         {Miscellaneous built-ins}
1658 ------------------------------------------------------------------------
1659
1660 pseudoop   "seq"
1661    a -> b -> b
1662    { Evaluates its first argument to head normal form, and then returns its second
1663         argument as the result. }
1664
1665 pseudoop   "inline"
1666    a -> a
1667    { The call {\tt (inline f)} arranges that f is inlined, regardless of its size.
1668         More precisely, the call {\tt (inline f)} rewrites to the right-hand side of
1669         {\tt f}'s definition. This allows the programmer to control inlining from a
1670         particular call site rather than the definition site of the function (c.f.
1671         {\tt INLINE} pragmas in User's Guide, Section 7.10.3, "INLINE and NOINLINE
1672         pragmas").
1673
1674         This inlining occurs regardless of the argument to the call or the size of
1675         {\tt f}'s definition; it is unconditional. The main caveat is that {\tt f}'s
1676         definition must be visible to the compiler. That is, {\tt f} must be
1677         {\tt let}-bound in the current scope. If no inlining takes place, the
1678         {\tt inline} function expands to the identity function in Phase zero; so its
1679         use imposes no overhead.
1680
1681         If the function is defined in another module, GHC only exposes its inlining
1682         in the interface file if the function is sufficiently small that it might be
1683         inlined by the automatic mechanism. There is currently no way to tell GHC to
1684         expose arbitrarily-large functions in the interface file. (This shortcoming
1685         is something that could be fixed, with some kind of pragma.) }
1686
1687 pseudoop   "lazy"
1688    a -> a
1689    { The {\tt lazy} function restrains strictness analysis a little. The call
1690         {\tt (lazy e)} means the same as {\tt e}, but {\tt lazy} has a magical
1691         property so far as strictness analysis is concerned: it is lazy in its first
1692         argument, even though its semantics is strict. After strictness analysis has
1693         run, calls to {\tt lazy} are inlined to be the identity function.
1694
1695         This behaviour is occasionally useful when controlling evaluation order.
1696         Notably, {\tt lazy} is used in the library definition of {\tt Control.Parallel.par}:
1697
1698         {\tt par :: a -> b -> b}
1699
1700         {\tt par x y = case (par\# x) of \_ -> lazy y}
1701
1702         If {\tt lazy} were not lazy, {\tt par} would look strict in {\tt y} which
1703         would defeat the whole purpose of {\tt par}.
1704
1705         Like {\tt seq}, the argument of {\tt lazy} can have an unboxed type. }
1706
1707 primtype Any a
1708         { The type constructor {\tt Any} is type to which you can unsafely coerce any
1709         lifted type, and back. 
1710
1711           * It is lifted, and hence represented by a pointer
1712
1713           * It does not claim to be a {\it data} type, and that's important for
1714             the code generator, because the code gen may {\it enter} a data value
1715             but never enters a function value.  
1716
1717         It's also used to instantiate un-constrained type variables after type
1718         checking.  For example
1719
1720         {\tt length Any []}
1721
1722         Annoyingly, we sometimes need {\tt Any}s of other kinds, such as {\tt (* -> *)} etc.
1723         This is a bit like tuples.   We define a couple of useful ones here,
1724         and make others up on the fly.  If any of these others end up being exported
1725         into interface files, we'll get a crash; at least until we add interface-file
1726         syntax to support them. }
1727
1728 pseudoop   "unsafeCoerce#"
1729    a -> b
1730    { The function {\tt unsafeCoerce\#} allows you to side-step the typechecker entirely. That
1731         is, it allows you to coerce any type into any other type. If you use this function,
1732         you had better get it right, otherwise segmentation faults await. It is generally
1733         used when you want to write a program that you know is well-typed, but where Haskell's
1734         type system is not expressive enough to prove that it is well typed.
1735
1736         The following uses of {\tt unsafeCoerce\#} are supposed to work (i.e. not lead to
1737         spurious compile-time or run-time crashes):
1738
1739          * Casting any lifted type to {\tt Any}
1740
1741          * Casting {\tt Any} back to the real type
1742
1743          * Casting an unboxed type to another unboxed type of the same size
1744            (but not coercions between floating-point and integral types)
1745
1746          * Casting between two types that have the same runtime representation.  One case is when
1747            the two types differ only in "phantom" type parameters, for example
1748            {\tt Ptr Int} to {\tt Ptr Float}, or {\tt [Int]} to {\tt [Float]} when the list is 
1749            known to be empty.  Also, a {\tt newtype} of a type {\tt T} has the same representation
1750            at runtime as {\tt T}.
1751
1752         Other uses of {\tt unsafeCoerce\#} are undefined.  In particular, you should not use
1753         {\tt unsafeCoerce\#} to cast a T to an algebraic data type D, unless T is also
1754         an algebraic data type.  For example, do not cast {\tt Int->Int} to {\tt Bool}, even if
1755         you later cast that {\tt Bool} back to {\tt Int->Int} before applying it.  The reasons
1756         have to do with GHC's internal representation details (for the congnoscenti, data values
1757         can be entered but function closures cannot).  If you want a safe type to cast things
1758         to, use {\tt Any}, which is not an algebraic data type.
1759         
1760         }
1761
1762 -- NB. It is tempting to think that casting a value to a type that it doesn't have is safe
1763 -- as long as you don't "do anything" with the value in its cast form, such as seq on it.  This
1764 -- isn't the case: the compiler can insert seqs itself, and if these happen at the wrong type,
1765 -- Bad Things Might Happen.  See bug #1616: in this case we cast a function of type (a,b) -> (a,b)
1766 -- to () -> () and back again.  The strictness analyser saw that the function was strict, but
1767 -- the wrapper had type () -> (), and hence the wrapper de-constructed the (), the worker re-constructed
1768 -- a new (), with the result that the code ended up with "case () of (a,b) -> ...".
1769
1770 primop  TraceEventOp "traceEvent#" GenPrimOp
1771    Addr# -> State# s -> State# s
1772    { Emits an event via the RTS tracing framework.  The contents
1773      of the event is the zero-terminated byte string passed as the first
1774      argument.  The event will be emitted either to the .eventlog file,
1775      or to stderr, depending on the runtime RTS flags. }
1776    with
1777    has_side_effects = True
1778    out_of_line      = True
1779
1780 ------------------------------------------------------------------------
1781 ---                                                                  ---
1782 ------------------------------------------------------------------------
1783
1784 thats_all_folks
1785
1786
1787