2 % (c) The GRASP/AQUA Project, Glasgow University, 1992-1998
4 \section[PrimOp]{Primitive operations (machine-level)}
8 -- The above warning supression flag is a temporary kludge.
9 -- While working on this module you are encouraged to remove it and fix
10 -- any warnings in the module. See
11 -- http://hackage.haskell.org/trac/ghc/wiki/Commentary/CodingStyle#Warnings
15 PrimOp(..), allThePrimOps,
16 primOpType, primOpSig,
17 primOpTag, maxPrimOpTag, primOpOcc,
21 primOpOutOfLine, primOpNeedsWrapper,
22 primOpOkForSpeculation, primOpIsCheap, primOpIsDupable,
24 getPrimOpResultInfo, PrimOpResultInfo(..)
27 #include "HsVersions.h"
34 import OccName ( OccName, pprOccName, mkVarOccFS )
35 import TyCon ( TyCon, isPrimTyCon, tyConPrimRep, PrimRep(..) )
36 import Type ( Type, mkForAllTys, mkFunTy, mkFunTys, tyConAppTyCon,
38 import BasicTypes ( Arity, Boxity(..) )
39 import Unique ( Unique, mkPrimOpIdUnique )
44 %************************************************************************
46 \subsection[PrimOp-datatype]{Datatype for @PrimOp@ (an enumeration)}
48 %************************************************************************
50 These are in \tr{state-interface.verb} order.
56 #include "primop-data-decl.hs-incl"
59 Used for the Ord instance
62 primOpTag :: PrimOp -> Int
63 primOpTag op = iBox (tagOf_PrimOp op)
66 -- tagOf_PrimOp :: PrimOp -> FastInt
67 #include "primop-tag.hs-incl"
70 instance Eq PrimOp where
71 op1 == op2 = tagOf_PrimOp op1 ==# tagOf_PrimOp op2
73 instance Ord PrimOp where
74 op1 < op2 = tagOf_PrimOp op1 <# tagOf_PrimOp op2
75 op1 <= op2 = tagOf_PrimOp op1 <=# tagOf_PrimOp op2
76 op1 >= op2 = tagOf_PrimOp op1 >=# tagOf_PrimOp op2
77 op1 > op2 = tagOf_PrimOp op1 ># tagOf_PrimOp op2
78 op1 `compare` op2 | op1 < op2 = LT
82 instance Outputable PrimOp where
85 instance Show PrimOp where
86 showsPrec p op = showsPrecSDoc p (pprPrimOp op)
89 An @Enum@-derived list would be better; meanwhile... (ToDo)
92 allThePrimOps :: [PrimOp]
94 #include "primop-list.hs-incl"
98 tagToEnumKey :: Unique
99 tagToEnumKey = mkPrimOpIdUnique (primOpTag TagToEnumOp)
104 %************************************************************************
106 \subsection[PrimOp-info]{The essential info about each @PrimOp@}
108 %************************************************************************
110 The @String@ in the @PrimOpInfos@ is the ``base name'' by which the user may
111 refer to the primitive operation. The conventional \tr{#}-for-
112 unboxed ops is added on later.
114 The reason for the funny characters in the names is so we do not
115 interfere with the programmer's Haskell name spaces.
117 We use @PrimKinds@ for the ``type'' information, because they're
118 (slightly) more convenient to use than @TyCons@.
121 = Dyadic OccName -- string :: T -> T -> T
123 | Monadic OccName -- string :: T -> T
125 | Compare OccName -- string :: T -> T -> Bool
128 | GenPrimOp OccName -- string :: \/a1..an . T1 -> .. -> Tk -> T
133 mkDyadic str ty = Dyadic (mkVarOccFS str) ty
134 mkMonadic str ty = Monadic (mkVarOccFS str) ty
135 mkCompare str ty = Compare (mkVarOccFS str) ty
136 mkGenPrimOp str tvs tys ty = GenPrimOp (mkVarOccFS str) tvs tys ty
139 %************************************************************************
141 \subsubsection{Strictness}
143 %************************************************************************
145 Not all primops are strict!
148 primOpStrictness :: PrimOp -> Arity -> StrictSig
149 -- See Demand.StrictnessInfo for discussion of what the results
150 -- The arity should be the arity of the primop; that's why
151 -- this function isn't exported.
152 #include "primop-strictness.hs-incl"
155 %************************************************************************
157 \subsubsection[PrimOp-comparison]{PrimOpInfo basic comparison ops}
159 %************************************************************************
161 @primOpInfo@ gives all essential information (from which everything
162 else, notably a type, can be constructed) for each @PrimOp@.
165 primOpInfo :: PrimOp -> PrimOpInfo
166 #include "primop-primop-info.hs-incl"
169 Here are a load of comments from the old primOp info:
171 A @Word#@ is an unsigned @Int#@.
173 @decodeFloat#@ is given w/ Integer-stuff (it's similar).
175 @decodeDouble#@ is given w/ Integer-stuff (it's similar).
177 Decoding of floating-point numbers is sorta Integer-related. Encoding
178 is done with plain ccalls now (see PrelNumExtra.lhs).
180 A @Weak@ Pointer is created by the @mkWeak#@ primitive:
182 mkWeak# :: k -> v -> f -> State# RealWorld
183 -> (# State# RealWorld, Weak# v #)
185 In practice, you'll use the higher-level
187 data Weak v = Weak# v
188 mkWeak :: k -> v -> IO () -> IO (Weak v)
190 The following operation dereferences a weak pointer. The weak pointer
191 may have been finalized, so the operation returns a result code which
192 must be inspected before looking at the dereferenced value.
194 deRefWeak# :: Weak# v -> State# RealWorld ->
195 (# State# RealWorld, v, Int# #)
197 Only look at v if the Int# returned is /= 0 !!
199 The higher-level op is
201 deRefWeak :: Weak v -> IO (Maybe v)
203 Weak pointers can be finalized early by using the finalize# operation:
205 finalizeWeak# :: Weak# v -> State# RealWorld ->
206 (# State# RealWorld, Int#, IO () #)
208 The Int# returned is either
210 0 if the weak pointer has already been finalized, or it has no
211 finalizer (the third component is then invalid).
213 1 if the weak pointer is still alive, with the finalizer returned
214 as the third component.
216 A {\em stable name/pointer} is an index into a table of stable name
217 entries. Since the garbage collector is told about stable pointers,
218 it is safe to pass a stable pointer to external systems such as C
222 makeStablePtr# :: a -> State# RealWorld -> (# State# RealWorld, StablePtr# a #)
223 freeStablePtr :: StablePtr# a -> State# RealWorld -> State# RealWorld
224 deRefStablePtr# :: StablePtr# a -> State# RealWorld -> (# State# RealWorld, a #)
225 eqStablePtr# :: StablePtr# a -> StablePtr# a -> Int#
228 It may seem a bit surprising that @makeStablePtr#@ is a @IO@
229 operation since it doesn't (directly) involve IO operations. The
230 reason is that if some optimisation pass decided to duplicate calls to
231 @makeStablePtr#@ and we only pass one of the stable pointers over, a
232 massive space leak can result. Putting it into the IO monad
233 prevents this. (Another reason for putting them in a monad is to
234 ensure correct sequencing wrt the side-effecting @freeStablePtr@
237 An important property of stable pointers is that if you call
238 makeStablePtr# twice on the same object you get the same stable
241 Note that we can implement @freeStablePtr#@ using @_ccall_@ (and,
242 besides, it's not likely to be used from Haskell) so it's not a
245 Question: Why @RealWorld@ - won't any instance of @_ST@ do the job? [ADR]
250 A stable name is like a stable pointer, but with three important differences:
252 (a) You can't deRef one to get back to the original object.
253 (b) You can convert one to an Int.
254 (c) You don't need to 'freeStableName'
256 The existence of a stable name doesn't guarantee to keep the object it
257 points to alive (unlike a stable pointer), hence (a).
261 (a) makeStableName always returns the same value for a given
262 object (same as stable pointers).
264 (b) if two stable names are equal, it implies that the objects
265 from which they were created were the same.
267 (c) stableNameToInt always returns the same Int for a given
271 -- HWL: The first 4 Int# in all par... annotations denote:
272 -- name, granularity info, size of result, degree of parallelism
273 -- Same structure as _seq_ i.e. returns Int#
274 -- KSW: v, the second arg in parAt# and parAtForNow#, is used only to determine
275 -- `the processor containing the expression v'; it is not evaluated
277 These primops are pretty wierd.
279 dataToTag# :: a -> Int (arg must be an evaluated data type)
280 tagToEnum# :: Int -> a (result type must be an enumerated type)
282 The constraints aren't currently checked by the front end, but the
283 code generator will fall over if they aren't satisfied.
287 primOpInfo op = pprPanic "primOpInfo:" (ppr op)
291 %************************************************************************
293 \subsubsection[PrimOp-ool]{Which PrimOps are out-of-line}
295 %************************************************************************
297 Some PrimOps need to be called out-of-line because they either need to
298 perform a heap check or they block.
302 primOpOutOfLine :: PrimOp -> Bool
303 #include "primop-out-of-line.hs-incl"
307 primOpOkForSpeculation
308 ~~~~~~~~~~~~~~~~~~~~~~
309 Sometimes we may choose to execute a PrimOp even though it isn't
310 certain that its result will be required; ie execute them
311 ``speculatively''. The same thing as ``cheap eagerness.'' Usually
312 this is OK, because PrimOps are usually cheap, but it isn't OK for
313 (a)~expensive PrimOps and (b)~PrimOps which can fail.
315 PrimOps that have side effects also should not be executed speculatively.
317 Ok-for-speculation also means that it's ok *not* to execute the
321 Here the result is not used, so we can discard the primop. Anything
322 that has side effects mustn't be dicarded in this way, of course!
324 See also @primOpIsCheap@ (below).
328 primOpOkForSpeculation :: PrimOp -> Bool
329 -- See comments with CoreUtils.exprOkForSpeculation
330 primOpOkForSpeculation op
331 = not (primOpHasSideEffects op || primOpOutOfLine op || primOpCanFail op)
337 @primOpIsCheap@, as used in \tr{SimplUtils.lhs}. For now (HACK
338 WARNING), we just borrow some other predicates for a
339 what-should-be-good-enough test. "Cheap" means willing to call it more
340 than once, and/or push it inside a lambda. The latter could change the
341 behaviour of 'seq' for primops that can fail, so we don't treat them as cheap.
344 primOpIsCheap :: PrimOp -> Bool
345 primOpIsCheap op = primOpOkForSpeculation op
346 -- In March 2001, we changed this to
347 -- primOpIsCheap op = False
348 -- thereby making *no* primops seem cheap. But this killed eta
349 -- expansion on case (x ==# y) of True -> \s -> ...
350 -- which is bad. In particular a loop like
353 -- loop i | i == n = return ()
354 -- | otherwise = bar i >> loop (i+1)
355 -- allocated a closure every time round because it doesn't eta expand.
357 -- The problem that originally gave rise to the change was
358 -- let x = a +# b *# c in x +# x
359 -- were we don't want to inline x. But primopIsCheap doesn't control
360 -- that (it's exprIsDupable that does) so the problem doesn't occur
361 -- even if primOpIsCheap sometimes says 'True'.
366 primOpIsDupable means that the use of the primop is small enough to
367 duplicate into different case branches. See CoreUtils.exprIsDupable.
370 primOpIsDupable :: PrimOp -> Bool
371 -- See comments with CoreUtils.exprIsDupable
372 -- We say it's dupable it isn't implemented by a C call with a wrapper
373 primOpIsDupable op = not (primOpNeedsWrapper op)
378 primOpCanFail :: PrimOp -> Bool
379 #include "primop-can-fail.hs-incl"
382 And some primops have side-effects and so, for example, must not be
386 primOpHasSideEffects :: PrimOp -> Bool
387 #include "primop-has-side-effects.hs-incl"
390 Inline primitive operations that perform calls need wrappers to save
391 any live variables that are stored in caller-saves registers.
394 primOpNeedsWrapper :: PrimOp -> Bool
395 #include "primop-needs-wrapper.hs-incl"
399 primOpType :: PrimOp -> Type -- you may want to use primOpSig instead
401 = case (primOpInfo op) of
402 Dyadic occ ty -> dyadic_fun_ty ty
403 Monadic occ ty -> monadic_fun_ty ty
404 Compare occ ty -> compare_fun_ty ty
406 GenPrimOp occ tyvars arg_tys res_ty ->
407 mkForAllTys tyvars (mkFunTys arg_tys res_ty)
409 primOpOcc :: PrimOp -> OccName
410 primOpOcc op = case (primOpInfo op) of
414 GenPrimOp occ _ _ _ -> occ
416 -- primOpSig is like primOpType but gives the result split apart:
417 -- (type variables, argument types, result type)
418 -- It also gives arity, strictness info
420 primOpSig :: PrimOp -> ([TyVar], [Type], Type, Arity, StrictSig)
422 = (tyvars, arg_tys, res_ty, arity, primOpStrictness op arity)
424 arity = length arg_tys
425 (tyvars, arg_tys, res_ty)
426 = case (primOpInfo op) of
427 Monadic occ ty -> ([], [ty], ty )
428 Dyadic occ ty -> ([], [ty,ty], ty )
429 Compare occ ty -> ([], [ty,ty], boolTy)
430 GenPrimOp occ tyvars arg_tys res_ty
431 -> (tyvars, arg_tys, res_ty)
435 data PrimOpResultInfo
436 = ReturnsPrim PrimRep
439 -- Some PrimOps need not return a manifest primitive or algebraic value
440 -- (i.e. they might return a polymorphic value). These PrimOps *must*
441 -- be out of line, or the code generator won't work.
443 getPrimOpResultInfo :: PrimOp -> PrimOpResultInfo
444 getPrimOpResultInfo op
445 = case (primOpInfo op) of
446 Dyadic _ ty -> ReturnsPrim (typePrimRep ty)
447 Monadic _ ty -> ReturnsPrim (typePrimRep ty)
448 Compare _ ty -> ReturnsAlg boolTyCon
449 GenPrimOp _ _ _ ty | isPrimTyCon tc -> ReturnsPrim (tyConPrimRep tc)
450 | otherwise -> ReturnsAlg tc
452 tc = tyConAppTyCon ty
453 -- All primops return a tycon-app result
454 -- The tycon can be an unboxed tuple, though, which
455 -- gives rise to a ReturnAlg
458 The commutable ops are those for which we will try to move constants
459 to the right hand side for strength reduction.
462 commutableOp :: PrimOp -> Bool
463 #include "primop-commutable.hs-incl"
468 dyadic_fun_ty ty = mkFunTys [ty, ty] ty
469 monadic_fun_ty ty = mkFunTy ty ty
470 compare_fun_ty ty = mkFunTys [ty, ty] boolTy
475 pprPrimOp :: PrimOp -> SDoc
476 pprPrimOp other_op = pprOccName (primOpOcc other_op)