X-Git-Url: http://git.megacz.com/?p=ghc-hetmet.git;a=blobdiff_plain;f=compiler%2Fprelude%2Fprimops.txt.pp;h=49f7a97a61d699b34fb19e2e162d3eda049d831c;hp=0af4c881f60ee5691d8a3a22fc4bee5071b9d1bd;hb=e11c554e94c39223ea55991a552ccb244dfe4364;hpb=d874b8c93b737bf26c949ef7bf19fc43e335bd1f

diff --git a/compiler/prelude/primops.txt.pp b/compiler/prelude/primops.txt.pp
index 0af4c88..49f7a97 100644
--- a/compiler/prelude/primops.txt.pp
+++ b/compiler/prelude/primops.txt.pp
@@ -1,8 +1,12 @@
 -----------------------------------------------------------------------
--- $Id: primops.txt.pp,v 1.37 2005/11/25 09:46:19 simonmar Exp $
+-- 
+-- (c) 2010 The University of Glasgow
 --
 -- Primitive Operations and Types
 --
+-- For more information on PrimOps, see
+--   http://hackage.haskell.org/trac/ghc/wiki/Commentary/PrimOps
+--
 -----------------------------------------------------------------------
 
 -- This file is processed by the utility program genprimopcode to produce
@@ -11,25 +15,10 @@
 --
 -- It should first be preprocessed.
 --
--- To add a new primop, you currently need to update the following files:
---
---	- this file (ghc/compiler/prelude/primops.txt.pp), which includes
---	  the type of the primop, and various other properties (its
---	  strictness attributes, whether it is defined as a macro
---	  or as out-of-line code, etc.)
---
---	- if the primop is inline (i.e. a macro), then:
---	  	ghc/compiler/AbsCUtils.lhs (dscCOpStmt)
---		  defines the translation of the primop into simpler
---		  abstract C operations.
---		
---	- or, for an out-of-line primop:
---	        ghc/includes/StgMiscClosures.h (just add the declaration)
---		ghc/rts/PrimOps.cmm     (define it here)
---		ghc/rts/Linker.c       (declare the symbol for GHCi)
---
---	- the User's Guide 
+-- Information on how PrimOps are implemented and the steps necessary to
+-- add a new one can be found in the Commentary:
 --
+--  http://hackage.haskell.org/trac/ghc/wiki/Commentary/PrimOps
 
 -- This file is divided into named sections, each containing or more
 -- primop entries. Section headers have the format:
@@ -589,7 +578,7 @@ primtype MutableArray# s a
 
 primop  NewArrayOp "newArray#" GenPrimOp
    Int# -> a -> State# s -> (# State# s, MutableArray# s a #)
-   {Create a new mutable array of specified size (in bytes),
+   {Create a new mutable array with the specified number of elements,
     in the specified state thread,
     with each element containing the specified initial value.}
    with
@@ -611,6 +600,14 @@ primop  WriteArrayOp "writeArray#" GenPrimOp
    with
    has_side_effects = True
 
+primop  SizeofArrayOp "sizeofArray#" GenPrimOp
+   Array# a -> Int#
+   {Return the number of elements in the array.}
+
+primop  SizeofMutableArrayOp "sizeofMutableArray#" GenPrimOp
+   MutableArray# s a -> Int#
+   {Return the number of elements in the array.}
+
 primop  IndexArrayOp "indexArray#" GenPrimOp
    Array# a -> Int# -> (# a #)
    {Read from specified index of immutable array. Result is packaged into
@@ -632,14 +629,15 @@ primop  UnsafeThawArrayOp  "unsafeThawArray#" GenPrimOp
 ------------------------------------------------------------------------
 section "Byte Arrays"
 	{Operations on {\tt ByteArray\#}. A {\tt ByteArray\#} is a just a region of
-         raw memory in the garbage-collected heap, which is not scanned
-         for pointers. It carries its own size (in bytes). There are
-	 three sets of operations for accessing byte array contents:
-	 index for reading from immutable byte arrays, and read/write
-	 for mutable byte arrays.  Each set contains operations for 
-	 a range of useful primitive data types.  Each operation takes	
-	 an offset measured in terms of the size fo the primitive type
-	 being read or written.}
+         raw memory in the garbage-collected heap, which is not
+         scanned for pointers. It carries its own size (in bytes).
+         There are
+         three sets of operations for accessing byte array contents:
+         index for reading from immutable byte arrays, and read/write
+         for mutable byte arrays.  Each set contains operations for a
+         range of useful primitive data types.  Each operation takes
+         an offset measured in terms of the size fo the primitive type
+         being read or written.}
 
 ------------------------------------------------------------------------
 
@@ -681,10 +679,11 @@ primop  UnsafeFreezeByteArrayOp "unsafeFreezeByteArray#" GenPrimOp
 
 primop  SizeofByteArrayOp "sizeofByteArray#" GenPrimOp  
    ByteArray# -> Int#
+   {Return the size of the array in bytes.}
 
 primop  SizeofMutableByteArrayOp "sizeofMutableByteArray#" GenPrimOp
    MutableByteArray# s -> Int#
-
+   {Return the size of the array in bytes.}
 
 primop IndexByteArrayOp_Char "indexCharArray#" GenPrimOp
    ByteArray# -> Int# -> Char#
@@ -1122,6 +1121,12 @@ primop  AtomicModifyMutVarOp "atomicModifyMutVar#" GenPrimOp
    out_of_line = True
    has_side_effects = True
 
+primop  CasMutVarOp "casMutVar#" GenPrimOp
+  MutVar# s a -> a -> a -> State# s -> (# State# s, Int#, a #)
+   with
+   out_of_line = True
+   has_side_effects = True
+
 ------------------------------------------------------------------------
 section "Exceptions"
 ------------------------------------------------------------------------
@@ -1149,28 +1154,39 @@ primop  RaiseOp "raise#" GenPrimOp
 -- raiseIO# needs to be a primop, because exceptions in the IO monad
 -- must be *precise* - we don't want the strictness analyser turning
 -- one kind of bottom into another, as it is allowed to do in pure code.
+--
+-- But we *do* want to know that it returns bottom after 
+-- being applied to two arguments
 
 primop  RaiseIOOp "raiseIO#" GenPrimOp
    a -> State# RealWorld -> (# State# RealWorld, b #)
    with
+   strictness  = { \ _arity -> mkStrictSig (mkTopDmdType [lazyDmd,lazyDmd] BotRes) }
+   out_of_line = True
+   has_side_effects = True
+
+primop  MaskAsyncExceptionsOp "maskAsyncExceptions#" GenPrimOp
+        (State# RealWorld -> (# State# RealWorld, a #))
+     -> (State# RealWorld -> (# State# RealWorld, a #))
+   with
    out_of_line = True
    has_side_effects = True
 
-primop  BlockAsyncExceptionsOp "blockAsyncExceptions#" GenPrimOp
+primop  MaskUninterruptibleOp "maskUninterruptible#" GenPrimOp
         (State# RealWorld -> (# State# RealWorld, a #))
      -> (State# RealWorld -> (# State# RealWorld, a #))
    with
    out_of_line = True
    has_side_effects = True
 
-primop  UnblockAsyncExceptionsOp "unblockAsyncExceptions#" GenPrimOp
+primop  UnmaskAsyncExceptionsOp "unmaskAsyncExceptions#" GenPrimOp
         (State# RealWorld -> (# State# RealWorld, a #))
      -> (State# RealWorld -> (# State# RealWorld, a #))
    with
    out_of_line = True
    has_side_effects = True
 
-primop  AsyncExceptionsBlockedOp "asyncExceptionsBlocked#" GenPrimOp
+primop  MaskStatus "getMaskingState#" GenPrimOp
         State# RealWorld -> (# State# RealWorld, Int# #)
    with
    out_of_line = True
@@ -1439,7 +1455,7 @@ primop  NoDuplicateOp "noDuplicate#" GenPrimOp
    has_side_effects = True
 
 primop  ThreadStatusOp "threadStatus#" GenPrimOp
-   ThreadId# -> State# RealWorld -> (# State# RealWorld, Int# #)
+   ThreadId# -> State# RealWorld -> (# State# RealWorld, Int#, Int#, Int# #)
    with
    out_of_line = True
    has_side_effects = True
@@ -1546,6 +1562,13 @@ primop GetSparkOp "getSpark#" GenPrimOp
    has_side_effects = True
    out_of_line = True
 
+primop NumSparks "numSparks#" GenPrimOp
+   State# s -> (# State# s, Int# #)
+   { Returns the number of sparks in the local spark pool. }
+   with
+   has_side_effects = True
+   out_of_line = True
+
 -- HWL: The first 4 Int# in all par... annotations denote:
 --   name, granularity info, size of result, degree of parallelism
 --      Same  structure as _seq_ i.e. returns Int#
@@ -1680,11 +1703,9 @@ pseudoop   "inline"
 	{\tt inline} function expands to the identity function in Phase zero; so its
 	use imposes no overhead.
 
-	If the function is defined in another module, GHC only exposes its inlining
-	in the interface file if the function is sufficiently small that it might be
-	inlined by the automatic mechanism. There is currently no way to tell GHC to
-	expose arbitrarily-large functions in the interface file. (This shortcoming
-	is something that could be fixed, with some kind of pragma.) }
+	It is good practice to mark the function with an INLINABLE pragma at
+        its definition, (a) so that GHC guarantees to expose its unfolding regardless
+        of size, and (b) so that you have control over exactly what is inlined. }
 
 pseudoop   "lazy"
    a -> a
@@ -1717,9 +1738,19 @@ primtype Any a
 	    but never enters a function value.  
 
 	It's also used to instantiate un-constrained type variables after type
-	checking.  For example
+	checking.  For example, {\tt length} has type
+
+	{\tt length :: forall a. [a] -> Int}
 
-	{\tt length Any []}
+	and the list datacon for the empty list has type
+
+	{\tt [] :: forall a. [a]}
+
+	In order to compose these two terms as {\tt length []} a type
+	application is required, but there is no constraint on the
+	choice.  In this situation GHC uses {\tt Any}:
+
+	{\tt length Any ([] Any)}
 
 	Annoyingly, we sometimes need {\tt Any}s of other kinds, such as {\tt (* -> *)} etc.
 	This is a bit like tuples.   We define a couple of useful ones here,
@@ -1769,6 +1800,16 @@ pseudoop   "unsafeCoerce#"
 -- the wrapper had type () -> (), and hence the wrapper de-constructed the (), the worker re-constructed
 -- a new (), with the result that the code ended up with "case () of (a,b) -> ...".
 
+primop  TraceEventOp "traceEvent#" GenPrimOp
+   Addr# -> State# s -> State# s
+   { Emits an event via the RTS tracing framework.  The contents
+     of the event is the zero-terminated byte string passed as the first
+     argument.  The event will be emitted either to the .eventlog file,
+     or to stderr, depending on the runtime RTS flags. }
+   with
+   has_side_effects = True
+   out_of_line      = True
+
 ------------------------------------------------------------------------
 ---                                                                  ---
 ------------------------------------------------------------------------