2 % (c) The GRASP/AQUA Project, Glasgow University, 1992-1998
4 \section[PrimOp]{Primitive operations (machine-level)}
8 PrimOp(..), allThePrimOps,
9 primOpType, primOpSig, primOpArity,
10 mkPrimOpIdName, primOpRdrName, primOpTag, primOpOcc,
14 primOpOutOfLine, primOpNeedsWrapper,
15 primOpOkForSpeculation, primOpIsCheap, primOpIsDupable,
18 getPrimOpResultInfo, PrimOpResultInfo(..)
21 #include "HsVersions.h"
23 import PrimRep -- most of it
29 import Name ( Name, mkWiredInName )
30 import RdrName ( RdrName, mkRdrOrig )
31 import OccName ( OccName, pprOccName, mkVarOcc )
32 import TyCon ( TyCon, isPrimTyCon, tyConPrimRep )
33 import Type ( Type, mkForAllTys, mkFunTy, mkFunTys, typePrimRep,
34 splitFunTy_maybe, tyConAppTyCon, splitTyConApp
36 import PprType () -- get at Outputable Type instance.
37 import Unique ( mkPrimOpIdUnique )
38 import BasicTypes ( Arity, Boxity(..) )
39 import PrelNames ( pREL_GHC, pREL_GHC_Name )
41 import Util ( zipWithEqual )
45 %************************************************************************
47 \subsection[PrimOp-datatype]{Datatype for @PrimOp@ (an enumeration)}
49 %************************************************************************
51 These are in \tr{state-interface.verb} order.
57 #include "primop-data-decl.hs-incl"
60 Used for the Ord instance
63 primOpTag :: PrimOp -> Int
64 primOpTag op = iBox (tagOf_PrimOp op)
67 -- tagOf_PrimOp :: PrimOp -> FastInt
68 #include "primop-tag.hs-incl"
69 tagOf_PrimOp op = pprPanic# "tagOf_PrimOp: pattern-match" (ppr op)
72 instance Eq PrimOp where
73 op1 == op2 = tagOf_PrimOp op1 ==# tagOf_PrimOp op2
75 instance Ord PrimOp where
76 op1 < op2 = tagOf_PrimOp op1 <# tagOf_PrimOp op2
77 op1 <= op2 = tagOf_PrimOp op1 <=# tagOf_PrimOp op2
78 op1 >= op2 = tagOf_PrimOp op1 >=# tagOf_PrimOp op2
79 op1 > op2 = tagOf_PrimOp op1 ># tagOf_PrimOp op2
80 op1 `compare` op2 | op1 < op2 = LT
84 instance Outputable PrimOp where
87 instance Show PrimOp where
88 showsPrec p op = showsPrecSDoc p (pprPrimOp op)
91 An @Enum@-derived list would be better; meanwhile... (ToDo)
93 allThePrimOps :: [PrimOp]
95 #include "primop-list.hs-incl"
98 %************************************************************************
100 \subsection[PrimOp-info]{The essential info about each @PrimOp@}
102 %************************************************************************
104 The @String@ in the @PrimOpInfos@ is the ``base name'' by which the user may
105 refer to the primitive operation. The conventional \tr{#}-for-
106 unboxed ops is added on later.
108 The reason for the funny characters in the names is so we do not
109 interfere with the programmer's Haskell name spaces.
111 We use @PrimKinds@ for the ``type'' information, because they're
112 (slightly) more convenient to use than @TyCons@.
115 = Dyadic OccName -- string :: T -> T -> T
117 | Monadic OccName -- string :: T -> T
119 | Compare OccName -- string :: T -> T -> Bool
122 | GenPrimOp OccName -- string :: \/a1..an . T1 -> .. -> Tk -> T
127 mkDyadic str ty = Dyadic (mkVarOcc str) ty
128 mkMonadic str ty = Monadic (mkVarOcc str) ty
129 mkCompare str ty = Compare (mkVarOcc str) ty
130 mkGenPrimOp str tvs tys ty = GenPrimOp (mkVarOcc str) tvs tys ty
133 %************************************************************************
135 \subsubsection{Strictness}
137 %************************************************************************
139 Not all primops are strict!
142 primOpStrictness :: PrimOp -> Arity -> StrictSig
143 -- See Demand.StrictnessInfo for discussion of what the results
144 -- The arity should be the arity of the primop; that's why
145 -- this function isn't exported.
146 #include "primop-strictness.hs-incl"
149 %************************************************************************
151 \subsubsection[PrimOp-comparison]{PrimOpInfo basic comparison ops}
153 %************************************************************************
155 @primOpInfo@ gives all essential information (from which everything
156 else, notably a type, can be constructed) for each @PrimOp@.
159 primOpInfo :: PrimOp -> PrimOpInfo
160 #include "primop-primop-info.hs-incl"
163 Here are a load of comments from the old primOp info:
165 A @Word#@ is an unsigned @Int#@.
167 @decodeFloat#@ is given w/ Integer-stuff (it's similar).
169 @decodeDouble#@ is given w/ Integer-stuff (it's similar).
171 Decoding of floating-point numbers is sorta Integer-related. Encoding
172 is done with plain ccalls now (see PrelNumExtra.lhs).
174 A @Weak@ Pointer is created by the @mkWeak#@ primitive:
176 mkWeak# :: k -> v -> f -> State# RealWorld
177 -> (# State# RealWorld, Weak# v #)
179 In practice, you'll use the higher-level
181 data Weak v = Weak# v
182 mkWeak :: k -> v -> IO () -> IO (Weak v)
184 The following operation dereferences a weak pointer. The weak pointer
185 may have been finalized, so the operation returns a result code which
186 must be inspected before looking at the dereferenced value.
188 deRefWeak# :: Weak# v -> State# RealWorld ->
189 (# State# RealWorld, v, Int# #)
191 Only look at v if the Int# returned is /= 0 !!
193 The higher-level op is
195 deRefWeak :: Weak v -> IO (Maybe v)
197 Weak pointers can be finalized early by using the finalize# operation:
199 finalizeWeak# :: Weak# v -> State# RealWorld ->
200 (# State# RealWorld, Int#, IO () #)
202 The Int# returned is either
204 0 if the weak pointer has already been finalized, or it has no
205 finalizer (the third component is then invalid).
207 1 if the weak pointer is still alive, with the finalizer returned
208 as the third component.
210 A {\em stable name/pointer} is an index into a table of stable name
211 entries. Since the garbage collector is told about stable pointers,
212 it is safe to pass a stable pointer to external systems such as C
216 makeStablePtr# :: a -> State# RealWorld -> (# State# RealWorld, StablePtr# a #)
217 freeStablePtr :: StablePtr# a -> State# RealWorld -> State# RealWorld
218 deRefStablePtr# :: StablePtr# a -> State# RealWorld -> (# State# RealWorld, a #)
219 eqStablePtr# :: StablePtr# a -> StablePtr# a -> Int#
222 It may seem a bit surprising that @makeStablePtr#@ is a @IO@
223 operation since it doesn't (directly) involve IO operations. The
224 reason is that if some optimisation pass decided to duplicate calls to
225 @makeStablePtr#@ and we only pass one of the stable pointers over, a
226 massive space leak can result. Putting it into the IO monad
227 prevents this. (Another reason for putting them in a monad is to
228 ensure correct sequencing wrt the side-effecting @freeStablePtr@
231 An important property of stable pointers is that if you call
232 makeStablePtr# twice on the same object you get the same stable
235 Note that we can implement @freeStablePtr#@ using @_ccall_@ (and,
236 besides, it's not likely to be used from Haskell) so it's not a
239 Question: Why @RealWorld@ - won't any instance of @_ST@ do the job? [ADR]
244 A stable name is like a stable pointer, but with three important differences:
246 (a) You can't deRef one to get back to the original object.
247 (b) You can convert one to an Int.
248 (c) You don't need to 'freeStableName'
250 The existence of a stable name doesn't guarantee to keep the object it
251 points to alive (unlike a stable pointer), hence (a).
255 (a) makeStableName always returns the same value for a given
256 object (same as stable pointers).
258 (b) if two stable names are equal, it implies that the objects
259 from which they were created were the same.
261 (c) stableNameToInt always returns the same Int for a given
265 -- HWL: The first 4 Int# in all par... annotations denote:
266 -- name, granularity info, size of result, degree of parallelism
267 -- Same structure as _seq_ i.e. returns Int#
268 -- KSW: v, the second arg in parAt# and parAtForNow#, is used only to determine
269 -- `the processor containing the expression v'; it is not evaluated
271 These primops are pretty wierd.
273 dataToTag# :: a -> Int (arg must be an evaluated data type)
274 tagToEnum# :: Int -> a (result type must be an enumerated type)
276 The constraints aren't currently checked by the front end, but the
277 code generator will fall over if they aren't satisfied.
281 primOpInfo op = pprPanic "primOpInfo:" (ppr op)
285 %************************************************************************
287 \subsubsection[PrimOp-ool]{Which PrimOps are out-of-line}
289 %************************************************************************
291 Some PrimOps need to be called out-of-line because they either need to
292 perform a heap check or they block.
296 primOpOutOfLine :: PrimOp -> Bool
297 #include "primop-out-of-line.hs-incl"
301 primOpOkForSpeculation
302 ~~~~~~~~~~~~~~~~~~~~~~
303 Sometimes we may choose to execute a PrimOp even though it isn't
304 certain that its result will be required; ie execute them
305 ``speculatively''. The same thing as ``cheap eagerness.'' Usually
306 this is OK, because PrimOps are usually cheap, but it isn't OK for
307 (a)~expensive PrimOps and (b)~PrimOps which can fail.
309 PrimOps that have side effects also should not be executed speculatively.
311 Ok-for-speculation also means that it's ok *not* to execute the
315 Here the result is not used, so we can discard the primop. Anything
316 that has side effects mustn't be dicarded in this way, of course!
318 See also @primOpIsCheap@ (below).
322 primOpOkForSpeculation :: PrimOp -> Bool
323 -- See comments with CoreUtils.exprOkForSpeculation
324 primOpOkForSpeculation op
325 = not (primOpHasSideEffects op || primOpOutOfLine op || primOpCanFail op)
331 @primOpIsCheap@, as used in \tr{SimplUtils.lhs}. For now (HACK
332 WARNING), we just borrow some other predicates for a
333 what-should-be-good-enough test. "Cheap" means willing to call it more
334 than once. Evaluation order is unaffected.
337 primOpIsCheap :: PrimOp -> Bool
338 primOpIsCheap op = False
339 -- March 2001: be less eager to inline PrimOps
340 -- Was: not (primOpHasSideEffects op || primOpOutOfLine op)
345 primOpIsDupable means that the use of the primop is small enough to
346 duplicate into different case branches. See CoreUtils.exprIsDupable.
349 primOpIsDupable :: PrimOp -> Bool
350 -- See comments with CoreUtils.exprIsDupable
351 -- We say it's dupable it isn't implemented by a C call with a wrapper
352 primOpIsDupable op = not (primOpNeedsWrapper op)
357 primOpCanFail :: PrimOp -> Bool
358 #include "primop-can-fail.hs-incl"
361 And some primops have side-effects and so, for example, must not be
365 primOpHasSideEffects :: PrimOp -> Bool
366 #include "primop-has-side-effects.hs-incl"
369 Inline primitive operations that perform calls need wrappers to save
370 any live variables that are stored in caller-saves registers.
373 primOpNeedsWrapper :: PrimOp -> Bool
374 #include "primop-needs-wrapper.hs-incl"
378 primOpArity :: PrimOp -> Arity
380 = case (primOpInfo op) of
384 GenPrimOp occ tyvars arg_tys res_ty -> length arg_tys
386 primOpType :: PrimOp -> Type -- you may want to use primOpSig instead
388 = case (primOpInfo op) of
389 Dyadic occ ty -> dyadic_fun_ty ty
390 Monadic occ ty -> monadic_fun_ty ty
391 Compare occ ty -> compare_fun_ty ty
393 GenPrimOp occ tyvars arg_tys res_ty ->
394 mkForAllTys tyvars (mkFunTys arg_tys res_ty)
396 mkPrimOpIdName :: PrimOp -> Name
397 -- Make the name for the PrimOp's Id
398 -- We have to pass in the Id itself because it's a WiredInId
399 -- and hence recursive
401 = mkWiredInName pREL_GHC (primOpOcc op) (mkPrimOpIdUnique (primOpTag op))
403 primOpRdrName :: PrimOp -> RdrName
404 primOpRdrName op = mkRdrOrig pREL_GHC_Name (primOpOcc op)
406 primOpOcc :: PrimOp -> OccName
407 primOpOcc op = case (primOpInfo op) of
411 GenPrimOp occ _ _ _ -> occ
413 -- primOpSig is like primOpType but gives the result split apart:
414 -- (type variables, argument types, result type)
415 -- It also gives arity, strictness info
417 primOpSig :: PrimOp -> ([TyVar], [Type], Type, Arity, StrictSig)
419 = (tyvars, arg_tys, res_ty, arity, primOpStrictness op arity)
421 arity = length arg_tys
422 (tyvars, arg_tys, res_ty)
423 = case (primOpInfo op) of
424 Monadic occ ty -> ([], [ty], ty )
425 Dyadic occ ty -> ([], [ty,ty], ty )
426 Compare occ ty -> ([], [ty,ty], boolTy)
427 GenPrimOp occ tyvars arg_tys res_ty
428 -> (tyvars, arg_tys, res_ty)
432 data PrimOpResultInfo
433 = ReturnsPrim PrimRep
436 -- Some PrimOps need not return a manifest primitive or algebraic value
437 -- (i.e. they might return a polymorphic value). These PrimOps *must*
438 -- be out of line, or the code generator won't work.
440 getPrimOpResultInfo :: PrimOp -> PrimOpResultInfo
441 getPrimOpResultInfo op
442 = case (primOpInfo op) of
443 Dyadic _ ty -> ReturnsPrim (typePrimRep ty)
444 Monadic _ ty -> ReturnsPrim (typePrimRep ty)
445 Compare _ ty -> ReturnsAlg boolTyCon
446 GenPrimOp _ _ _ ty | isPrimTyCon tc -> ReturnsPrim (tyConPrimRep tc)
447 | otherwise -> ReturnsAlg tc
449 tc = tyConAppTyCon ty
450 -- All primops return a tycon-app result
451 -- The tycon can be an unboxed tuple, though, which
452 -- gives rise to a ReturnAlg
455 The commutable ops are those for which we will try to move constants
456 to the right hand side for strength reduction.
459 commutableOp :: PrimOp -> Bool
460 #include "primop-commutable.hs-incl"
465 dyadic_fun_ty ty = mkFunTys [ty, ty] ty
466 monadic_fun_ty ty = mkFunTy ty ty
467 compare_fun_ty ty = mkFunTys [ty, ty] boolTy
472 pprPrimOp :: PrimOp -> SDoc
474 = getPprStyle $ \ sty ->
475 if ifaceStyle sty then -- For interfaces Print it qualified with PrelGHC.
476 ptext SLIT("PrelGHC.") <> pprOccName occ
480 occ = primOpOcc other_op