-- text between curly brackets. This is a kludge to enable
-- processors of this file to easily get hold of simple info
-- (eg, out_of_line), whilst avoiding parsing complex expressions
--- needed for strictness and usage info.
+-- needed for strictness info.
defaults
has_side_effects = False
needs_wrapper = False
can_fail = False
strictness = { \ arity -> mkStrictSig (mkTopDmdType (replicate arity lazyDmd) TopRes) }
- usage = { nomangle other }
-- Currently, documentation is produced using latex, so contents of
-- description fields should be legal latex. Descriptions can contain
primop DoubleNegOp "negateDouble#" Monadic Double# -> Double#
primop Double2IntOp "double2Int#" GenPrimOp Double# -> Int#
+ {Truncates a {\tt Double#} value to the nearest {\tt Int#}.
+ Results are undefined if the truncation if truncation yields
+ a value outside the range of {\tt Int#}.}
+
primop Double2FloatOp "double2Float#" GenPrimOp Double# -> Float#
primop DoubleExpOp "expDouble#" Monadic
primop FloatNegOp "negateFloat#" Monadic Float# -> Float#
primop Float2IntOp "float2Int#" GenPrimOp Float# -> Int#
+ {Truncates a {\tt Float#} value to the nearest {\tt Int#}.
+ Results are undefined if the truncation if truncation yields
+ a value outside the range of {\tt Int#}.}
primop FloatExpOp "expFloat#" Monadic
Float# -> Float#
in the specified state thread,
with each element containing the specified initial value.}
with
- usage = { mangle NewArrayOp [mkP, mkM, mkP] mkM }
out_of_line = True
primop SameMutableArrayOp "sameMutableArray#" GenPrimOp
MutArr# s a -> MutArr# s a -> Bool
- with
- usage = { mangle SameMutableArrayOp [mkP, mkP] mkM }
primop ReadArrayOp "readArray#" GenPrimOp
MutArr# s a -> Int# -> State# s -> (# State# s, a #)
{Read from specified index of mutable array. Result is not yet evaluated.}
- with
- usage = { mangle ReadArrayOp [mkM, mkP, mkP] mkM }
primop WriteArrayOp "writeArray#" GenPrimOp
MutArr# s a -> Int# -> a -> State# s -> State# s
{Write to specified index of mutable array.}
with
- usage = { mangle WriteArrayOp [mkM, mkP, mkM, mkP] mkR }
has_side_effects = True
primop IndexArrayOp "indexArray#" GenPrimOp
Array# a -> Int# -> (# a #)
{Read from specified index of immutable array. Result is packaged into
an unboxed singleton; the result itself is not yet evaluated.}
- with
- usage = { mangle IndexArrayOp [mkM, mkP] mkM }
primop UnsafeFreezeArrayOp "unsafeFreezeArray#" GenPrimOp
MutArr# s a -> State# s -> (# State# s, Array# a #)
{Make a mutable array immutable, without copying.}
with
- usage = { mangle UnsafeFreezeArrayOp [mkM, mkP] mkM }
has_side_effects = True
primop UnsafeThawArrayOp "unsafeThawArray#" GenPrimOp
Array# a -> State# s -> (# State# s, MutArr# s a #)
{Make an immutable array mutable, without copying.}
with
- usage = { mangle UnsafeThawArrayOp [mkM, mkP] mkM }
out_of_line = True
------------------------------------------------------------------------
a -> State# s -> (# State# s, MutVar# s a #)
{Create {\tt MutVar\#} with specified initial value in specified state thread.}
with
- usage = { mangle NewMutVarOp [mkM, mkP] mkM }
out_of_line = True
primop ReadMutVarOp "readMutVar#" GenPrimOp
MutVar# s a -> State# s -> (# State# s, a #)
{Read contents of {\tt MutVar\#}. Result is not yet evaluated.}
- with
- usage = { mangle ReadMutVarOp [mkM, mkP] mkM }
primop WriteMutVarOp "writeMutVar#" GenPrimOp
MutVar# s a -> a -> State# s -> State# s
{Write contents of {\tt MutVar\#}.}
with
- usage = { mangle WriteMutVarOp [mkM, mkM, mkP] mkR }
has_side_effects = True
primop SameMutVarOp "sameMutVar#" GenPrimOp
MutVar# s a -> MutVar# s a -> Bool
- with
- usage = { mangle SameMutVarOp [mkP, mkP] mkM }
-- not really the right type, but we don't know about pairs here. The
-- correct type is
primop AtomicModifyMutVarOp "atomicModifyMutVar#" GenPrimOp
MutVar# s a -> (a -> b) -> State# s -> (# State# s, c #)
with
- usage = { mangle AtomicModifyMutVarOp [mkP, mkM, mkP] mkM }
has_side_effects = True
out_of_line = True
-- Catch is actually strict in its first argument
-- but we don't want to tell the strictness
-- analyser about that!
- usage = { mangle CatchOp [mkM, mkM . (inFun CatchOp mkM mkM), mkP] mkM }
- -- [mkO, mkO . (inFun mkM mkO)] mkO
-- might use caught action multiply
out_of_line = True
with
strictness = { \ arity -> mkStrictSig (mkTopDmdType [lazyDmd] BotRes) }
-- NB: result is bottom
- usage = { mangle RaiseOp [mkM] mkM }
out_of_line = True
-- raiseIO# needs to be a primop, because exceptions in the IO monad
State# s -> (# State# s, MVar# s a #)
{Create new {\tt MVar\#}; initially empty.}
with
- usage = { mangle NewMVarOp [mkP] mkR }
out_of_line = True
primop TakeMVarOp "takeMVar#" GenPrimOp
{If {\tt MVar\#} is empty, block until it becomes full.
Then remove and return its contents, and set it empty.}
with
- usage = { mangle TakeMVarOp [mkM, mkP] mkM }
has_side_effects = True
out_of_line = True
{If {\tt MVar\#} is empty, immediately return with integer 0 and value undefined.
Otherwise, return with integer 1 and contents of {\tt MVar\#}, and set {\tt MVar\#} empty.}
with
- usage = { mangle TryTakeMVarOp [mkM, mkP] mkM }
has_side_effects = True
out_of_line = True
{If {\tt MVar\#} is full, block until it becomes empty.
Then store value arg as its new contents.}
with
- usage = { mangle PutMVarOp [mkM, mkM, mkP] mkR }
has_side_effects = True
out_of_line = True
{If {\tt MVar\#} is full, immediately return with integer 0.
Otherwise, store value arg as {\tt MVar\#}'s new contents, and return with integer 1.}
with
- usage = { mangle TryPutMVarOp [mkM, mkM, mkP] mkR }
has_side_effects = True
out_of_line = True
primop SameMVarOp "sameMVar#" GenPrimOp
MVar# s a -> MVar# s a -> Bool
- with
- usage = { mangle SameMVarOp [mkP, mkP] mkM }
primop IsEmptyMVarOp "isEmptyMVar#" GenPrimOp
MVar# s a -> State# s -> (# State# s, Int# #)
{Return 1 if {\tt MVar\#} is empty; 0 otherwise.}
with
- usage = { mangle IsEmptyMVarOp [mkP, mkP] mkM }
out_of_line = True
------------------------------------------------------------------------
------------------------------------------------------------------------
primtype State# s
- { {\tt State#} is the primitive, unlifted type of states. It has
+ { {\tt State\#} is the primitive, unlifted type of states. It has
one type parameter, thus {\tt State\# RealWorld}, or {\tt State\# s},
where s is a type variable. The only purpose of the type parameter
is to keep different state threads separate. It is represented by
primtype RealWorld
{ {\tt RealWorld} is deeply magical. It is {\it primitive}, but it is not
{\it unlifted} (hence {\tt ptrArg}). We never manipulate values of type
- {\tt RealWorld}; it's only used in the type system, to parameterise {\tt State#}. }
+ {\tt RealWorld}; it's only used in the type system, to parameterise {\tt State\#}. }
primtype ThreadId#
{(In a non-concurrent implementation, this can be a singleton
primop ForkOp "fork#" GenPrimOp
a -> State# RealWorld -> (# State# RealWorld, ThreadId# #)
with
- usage = { mangle ForkOp [mkO, mkP] mkR }
has_side_effects = True
out_of_line = True
primop ForkOnOp "forkOn#" GenPrimOp
Int# -> a -> State# RealWorld -> (# State# RealWorld, ThreadId# #)
with
- usage = { mangle ForkOnOp [mkO, mkP] mkR }
has_side_effects = True
out_of_line = True
primop KillThreadOp "killThread#" GenPrimOp
ThreadId# -> a -> State# RealWorld -> State# RealWorld
with
- usage = { mangle KillThreadOp [mkP, mkM, mkP] mkR }
has_side_effects = True
out_of_line = True
with
out_of_line = True
+primop NoDuplicateOp "noDuplicate#" GenPrimOp
+ State# RealWorld -> State# RealWorld
+ with
+ out_of_line = True
+
------------------------------------------------------------------------
section "Weak pointers"
------------------------------------------------------------------------
primop MkWeakOp "mkWeak#" GenPrimOp
o -> b -> c -> State# RealWorld -> (# State# RealWorld, Weak# b #)
with
- usage = { mangle MkWeakOp [mkZ, mkM, mkM, mkP] mkM }
has_side_effects = True
out_of_line = True
primop DeRefWeakOp "deRefWeak#" GenPrimOp
Weak# a -> State# RealWorld -> (# State# RealWorld, Int#, a #)
with
- usage = { mangle DeRefWeakOp [mkM, mkP] mkM }
has_side_effects = True
out_of_line = True
Weak# a -> State# RealWorld -> (# State# RealWorld, Int#,
(State# RealWorld -> (# State# RealWorld, () #)) #)
with
- usage = { mangle FinalizeWeakOp [mkM, mkP]
- (mkR . (inUB FinalizeWeakOp
- [id,id,inFun FinalizeWeakOp mkR mkM])) }
has_side_effects = True
out_of_line = True
primop MakeStablePtrOp "makeStablePtr#" GenPrimOp
a -> State# RealWorld -> (# State# RealWorld, StablePtr# a #)
with
- usage = { mangle MakeStablePtrOp [mkM, mkP] mkM }
has_side_effects = True
out_of_line = True
primop DeRefStablePtrOp "deRefStablePtr#" GenPrimOp
StablePtr# a -> State# RealWorld -> (# State# RealWorld, a #)
with
- usage = { mangle DeRefStablePtrOp [mkM, mkP] mkM }
needs_wrapper = True
has_side_effects = True
out_of_line = True
primop EqStablePtrOp "eqStablePtr#" GenPrimOp
StablePtr# a -> StablePtr# a -> Int#
with
- usage = { mangle EqStablePtrOp [mkP, mkP] mkR }
has_side_effects = True
primop MakeStableNameOp "makeStableName#" GenPrimOp
a -> State# RealWorld -> (# State# RealWorld, StableName# a #)
with
- usage = { mangle MakeStableNameOp [mkZ, mkP] mkR }
needs_wrapper = True
has_side_effects = True
out_of_line = True
primop EqStableNameOp "eqStableName#" GenPrimOp
StableName# a -> StableName# a -> Int#
- with
- usage = { mangle EqStableNameOp [mkP, mkP] mkR }
primop StableNameToIntOp "stableNameToInt#" GenPrimOp
StableName# a -> Int#
- with
- usage = { mangle StableNameToIntOp [mkP] mkR }
------------------------------------------------------------------------
section "Unsafe pointer equality"
primop ReallyUnsafePtrEqualityOp "reallyUnsafePtrEquality#" GenPrimOp
a -> a -> Int#
- with
- usage = { mangle ReallyUnsafePtrEqualityOp [mkZ, mkZ] mkR }
------------------------------------------------------------------------
section "Parallelism"
primop ParOp "par#" GenPrimOp
a -> Int#
with
- usage = { mangle ParOp [mkO] mkR }
-- Note that Par is lazy to avoid that the sparked thing
-- gets evaluted strictly, which it should *not* be
has_side_effects = True
primop ParGlobalOp "parGlobal#" GenPrimOp
a -> Int# -> Int# -> Int# -> Int# -> b -> Int#
with
- usage = { mangle ParGlobalOp [mkO, mkP, mkP, mkP, mkP, mkM] mkM }
has_side_effects = True
primop ParLocalOp "parLocal#" GenPrimOp
a -> Int# -> Int# -> Int# -> Int# -> b -> Int#
with
- usage = { mangle ParLocalOp [mkO, mkP, mkP, mkP, mkP, mkM] mkM }
has_side_effects = True
primop ParAtOp "parAt#" GenPrimOp
b -> a -> Int# -> Int# -> Int# -> Int# -> c -> Int#
with
- usage = { mangle ParAtOp [mkO, mkZ, mkP, mkP, mkP, mkP, mkM] mkM }
has_side_effects = True
primop ParAtAbsOp "parAtAbs#" GenPrimOp
a -> Int# -> Int# -> Int# -> Int# -> Int# -> b -> Int#
with
- usage = { mangle ParAtAbsOp [mkO, mkP, mkP, mkP, mkP, mkM] mkM }
has_side_effects = True
primop ParAtRelOp "parAtRel#" GenPrimOp
a -> Int# -> Int# -> Int# -> Int# -> Int# -> b -> Int#
with
- usage = { mangle ParAtRelOp [mkO, mkP, mkP, mkP, mkP, mkM] mkM }
has_side_effects = True
primop ParAtForNowOp "parAtForNow#" GenPrimOp
b -> a -> Int# -> Int# -> Int# -> Int# -> c -> Int#
with
- usage = { mangle ParAtForNowOp [mkO, mkZ, mkP, mkP, mkP, mkP, mkM] mkM }
has_side_effects = True
-- copyable# and noFollow# are yet to be implemented (for GpH)
--primop CopyableOp "copyable#" GenPrimOp
-- a -> Int#
-- with
--- usage = { mangle CopyableOp [mkZ] mkR }
-- has_side_effects = True
--
--primop NoFollowOp "noFollow#" GenPrimOp
-- a -> Int#
-- with
--- usage = { mangle NoFollowOp [mkZ] mkR }
-- has_side_effects = True
has_side_effects = True
out_of_line = True
-primop InfoPtrOp "infoPtr#" GenPrimOp
- a -> Addr#
+primop UnpackClosureOp "unpackClosure#" GenPrimOp
+ a -> (# Addr#, Array# b, ByteArr# #)
with
out_of_line = True
-primop ClosurePayloadOp "closurePayload#" GenPrimOp
- a -> (# Array# b, ByteArr# #)
+primop GetApStackValOp "getApStackVal#" GenPrimOp
+ a -> Int# -> (# Int#, b #)
with
out_of_line = True
-
------------------------------------------------------------------------
section "Etc"
{Miscellaneous built-ins}
pseudoop "inline"
a -> a
- { The call {\tt(inline f)} arranges that f is inlined, regardless of its size.
- More precisely, the call {\tt(inline f)} rewrites to the right-hand side of
+ { The call {\tt (inline f)} arranges that f is inlined, regardless of its size.
+ More precisely, the call {\tt (inline f)} rewrites to the right-hand side of
{\tt f}'s definition. This allows the programmer to control inlining from a
particular call site rather than the definition site of the function (c.f.
- {\ttINLINE} pragmas in User's Guide, Section 7.10.3, "INLINE and NOINLINE
+ {\tt INLINE} pragmas in User's Guide, Section 7.10.3, "INLINE and NOINLINE
pragmas").
This inlining occurs regardless of the argument to the call or the size of
This behaviour is occasionally useful when controlling evaluation order.
Notably, {\tt lazy} is used in the library definition of {\tt Control.Parallel.par}:
- > par :: a -> b -> b
- > par x y = case (par# x) of { _ -> lazy y }
+ {\tt par :: a -> b -> b}
+
+ {\tt par x y = case (par\# x) of \_ -> lazy y}
If {\tt lazy} were not lazy, {\tt par} would look strict in {\tt y} which
would defeat the whole purpose of {\tt par}.
It's also used to instantiate un-constrained type variables after type
checking. For example
- > length Any []
+ {\tt length 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,
used when you want to write a program that you know is well-typed, but where Haskell's
type system is not expressive enough to prove that it is well typed.
- The argument to {\tt unsafeCoerce\#} can have unboxed types, although extremely bad
- things will happen if you coerce a boxed type to an unboxed type. }
+ The following uses of {\tt unsafeCoerce\#} are supposed to work (i.e. not lead to
+ spurious compile-time or run-time crashes):
+
+ * Casting any lifted type to {\tt Any}
+
+ * Casting {\tt Any} back to the real type
+
+ * Casting an unboxed type to another unboxed type of the same size
+
+ * Casting between two types that have the same runtime representation. One case is when
+ the two types differ only in "phantom" type parameters, for example
+ {\tt Ptr Int} to {\tt Ptr Float}, or {\tt [Int]} to {\tt [Float]} when the list is
+ known to be empty. Also, a {\tt newtype} of a type {\tt T} has the same representation
+ at runtime as {\tt T}.
+
+ Other uses of {\tt unsafeCoerce\#} are undefined.
+ }
+-- NB. It is tempting to think that casting a value to a type that it doesn't have is safe
+-- as long as you don't "do anything" with the value in its cast form, such as seq on it. This
+-- isn't the case: the compiler can insert seqs itself, and if these happen at the wrong type,
+-- Bad Things Might Happen. See bug #1616: in this case we cast a function of type (a,b) -> (a,b)
+-- to () -> () and back again. The strictness analyser saw that the function was strict, but
+-- 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) -> ...".
------------------------------------------------------------------------
--- ---