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(..),
20 eqCharName, eqIntName, eqFloatName, eqDoubleName, neqIntName,
23 #include "HsVersions.h"
25 import PrimRep -- most of it
31 import Name ( Name, mkWiredInName )
32 import RdrName ( RdrName, mkRdrOrig )
33 import OccName ( OccName, pprOccName, mkVarOcc )
34 import TyCon ( TyCon, isPrimTyCon, tyConPrimRep )
35 import Type ( Type, mkForAllTys, mkFunTy, mkFunTys, typePrimRep, tyConAppTyCon )
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 )
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"
68 tagOf_PrimOp op = pprPanic# "tagOf_PrimOp: pattern-match" (ppr op)
71 instance Eq PrimOp where
72 op1 == op2 = tagOf_PrimOp op1 ==# tagOf_PrimOp op2
74 instance Ord PrimOp where
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 > op2 = tagOf_PrimOp op1 ># tagOf_PrimOp op2
79 op1 `compare` op2 | op1 < op2 = LT
83 instance Outputable PrimOp where
86 instance Show PrimOp where
87 showsPrec p op = showsPrecSDoc p (pprPrimOp op)
90 An @Enum@-derived list would be better; meanwhile... (ToDo)
92 allThePrimOps :: [PrimOp]
94 #include "primop-list.hs-incl"
97 %************************************************************************
99 \subsection[PrimOp-info]{The essential info about each @PrimOp@}
101 %************************************************************************
103 The @String@ in the @PrimOpInfos@ is the ``base name'' by which the user may
104 refer to the primitive operation. The conventional \tr{#}-for-
105 unboxed ops is added on later.
107 The reason for the funny characters in the names is so we do not
108 interfere with the programmer's Haskell name spaces.
110 We use @PrimKinds@ for the ``type'' information, because they're
111 (slightly) more convenient to use than @TyCons@.
114 = Dyadic OccName -- string :: T -> T -> T
116 | Monadic OccName -- string :: T -> T
118 | Compare OccName -- string :: T -> T -> Bool
121 | GenPrimOp OccName -- string :: \/a1..an . T1 -> .. -> Tk -> T
126 mkDyadic str ty = Dyadic (mkVarOcc str) ty
127 mkMonadic str ty = Monadic (mkVarOcc str) ty
128 mkCompare str ty = Compare (mkVarOcc str) ty
129 mkGenPrimOp str tvs tys ty = GenPrimOp (mkVarOcc str) tvs tys ty
132 %************************************************************************
134 \subsubsection{Strictness}
136 %************************************************************************
138 Not all primops are strict!
141 primOpStrictness :: PrimOp -> Arity -> StrictSig
142 -- See Demand.StrictnessInfo for discussion of what the results
143 -- The arity should be the arity of the primop; that's why
144 -- this function isn't exported.
145 #include "primop-strictness.hs-incl"
148 %************************************************************************
150 \subsubsection[PrimOp-comparison]{PrimOpInfo basic comparison ops}
152 %************************************************************************
154 @primOpInfo@ gives all essential information (from which everything
155 else, notably a type, can be constructed) for each @PrimOp@.
158 primOpInfo :: PrimOp -> PrimOpInfo
159 #include "primop-primop-info.hs-incl"
162 Here are a load of comments from the old primOp info:
164 A @Word#@ is an unsigned @Int#@.
166 @decodeFloat#@ is given w/ Integer-stuff (it's similar).
168 @decodeDouble#@ is given w/ Integer-stuff (it's similar).
170 Decoding of floating-point numbers is sorta Integer-related. Encoding
171 is done with plain ccalls now (see PrelNumExtra.lhs).
173 A @Weak@ Pointer is created by the @mkWeak#@ primitive:
175 mkWeak# :: k -> v -> f -> State# RealWorld
176 -> (# State# RealWorld, Weak# v #)
178 In practice, you'll use the higher-level
180 data Weak v = Weak# v
181 mkWeak :: k -> v -> IO () -> IO (Weak v)
183 The following operation dereferences a weak pointer. The weak pointer
184 may have been finalized, so the operation returns a result code which
185 must be inspected before looking at the dereferenced value.
187 deRefWeak# :: Weak# v -> State# RealWorld ->
188 (# State# RealWorld, v, Int# #)
190 Only look at v if the Int# returned is /= 0 !!
192 The higher-level op is
194 deRefWeak :: Weak v -> IO (Maybe v)
196 Weak pointers can be finalized early by using the finalize# operation:
198 finalizeWeak# :: Weak# v -> State# RealWorld ->
199 (# State# RealWorld, Int#, IO () #)
201 The Int# returned is either
203 0 if the weak pointer has already been finalized, or it has no
204 finalizer (the third component is then invalid).
206 1 if the weak pointer is still alive, with the finalizer returned
207 as the third component.
209 A {\em stable name/pointer} is an index into a table of stable name
210 entries. Since the garbage collector is told about stable pointers,
211 it is safe to pass a stable pointer to external systems such as C
215 makeStablePtr# :: a -> State# RealWorld -> (# State# RealWorld, StablePtr# a #)
216 freeStablePtr :: StablePtr# a -> State# RealWorld -> State# RealWorld
217 deRefStablePtr# :: StablePtr# a -> State# RealWorld -> (# State# RealWorld, a #)
218 eqStablePtr# :: StablePtr# a -> StablePtr# a -> Int#
221 It may seem a bit surprising that @makeStablePtr#@ is a @IO@
222 operation since it doesn't (directly) involve IO operations. The
223 reason is that if some optimisation pass decided to duplicate calls to
224 @makeStablePtr#@ and we only pass one of the stable pointers over, a
225 massive space leak can result. Putting it into the IO monad
226 prevents this. (Another reason for putting them in a monad is to
227 ensure correct sequencing wrt the side-effecting @freeStablePtr@
230 An important property of stable pointers is that if you call
231 makeStablePtr# twice on the same object you get the same stable
234 Note that we can implement @freeStablePtr#@ using @_ccall_@ (and,
235 besides, it's not likely to be used from Haskell) so it's not a
238 Question: Why @RealWorld@ - won't any instance of @_ST@ do the job? [ADR]
243 A stable name is like a stable pointer, but with three important differences:
245 (a) You can't deRef one to get back to the original object.
246 (b) You can convert one to an Int.
247 (c) You don't need to 'freeStableName'
249 The existence of a stable name doesn't guarantee to keep the object it
250 points to alive (unlike a stable pointer), hence (a).
254 (a) makeStableName always returns the same value for a given
255 object (same as stable pointers).
257 (b) if two stable names are equal, it implies that the objects
258 from which they were created were the same.
260 (c) stableNameToInt always returns the same Int for a given
264 -- HWL: The first 4 Int# in all par... annotations denote:
265 -- name, granularity info, size of result, degree of parallelism
266 -- Same structure as _seq_ i.e. returns Int#
267 -- KSW: v, the second arg in parAt# and parAtForNow#, is used only to determine
268 -- `the processor containing the expression v'; it is not evaluated
270 These primops are pretty wierd.
272 dataToTag# :: a -> Int (arg must be an evaluated data type)
273 tagToEnum# :: Int -> a (result type must be an enumerated type)
275 The constraints aren't currently checked by the front end, but the
276 code generator will fall over if they aren't satisfied.
280 primOpInfo op = pprPanic "primOpInfo:" (ppr op)
284 %************************************************************************
286 \subsubsection[PrimOp-ool]{Which PrimOps are out-of-line}
288 %************************************************************************
290 Some PrimOps need to be called out-of-line because they either need to
291 perform a heap check or they block.
295 primOpOutOfLine :: PrimOp -> Bool
296 #include "primop-out-of-line.hs-incl"
300 primOpOkForSpeculation
301 ~~~~~~~~~~~~~~~~~~~~~~
302 Sometimes we may choose to execute a PrimOp even though it isn't
303 certain that its result will be required; ie execute them
304 ``speculatively''. The same thing as ``cheap eagerness.'' Usually
305 this is OK, because PrimOps are usually cheap, but it isn't OK for
306 (a)~expensive PrimOps and (b)~PrimOps which can fail.
308 PrimOps that have side effects also should not be executed speculatively.
310 Ok-for-speculation also means that it's ok *not* to execute the
314 Here the result is not used, so we can discard the primop. Anything
315 that has side effects mustn't be dicarded in this way, of course!
317 See also @primOpIsCheap@ (below).
321 primOpOkForSpeculation :: PrimOp -> Bool
322 -- See comments with CoreUtils.exprOkForSpeculation
323 primOpOkForSpeculation op
324 = not (primOpHasSideEffects op || primOpOutOfLine op || primOpCanFail op)
330 @primOpIsCheap@, as used in \tr{SimplUtils.lhs}. For now (HACK
331 WARNING), we just borrow some other predicates for a
332 what-should-be-good-enough test. "Cheap" means willing to call it more
333 than once. Evaluation order is unaffected.
336 primOpIsCheap :: PrimOp -> Bool
337 primOpIsCheap op = False
338 -- March 2001: be less eager to inline PrimOps
339 -- Was: not (primOpHasSideEffects op || primOpOutOfLine op)
344 primOpIsDupable means that the use of the primop is small enough to
345 duplicate into different case branches. See CoreUtils.exprIsDupable.
348 primOpIsDupable :: PrimOp -> Bool
349 -- See comments with CoreUtils.exprIsDupable
350 -- We say it's dupable it isn't implemented by a C call with a wrapper
351 primOpIsDupable op = not (primOpNeedsWrapper op)
356 primOpCanFail :: PrimOp -> Bool
357 #include "primop-can-fail.hs-incl"
360 And some primops have side-effects and so, for example, must not be
364 primOpHasSideEffects :: PrimOp -> Bool
365 #include "primop-has-side-effects.hs-incl"
368 Inline primitive operations that perform calls need wrappers to save
369 any live variables that are stored in caller-saves registers.
372 primOpNeedsWrapper :: PrimOp -> Bool
373 #include "primop-needs-wrapper.hs-incl"
377 primOpArity :: PrimOp -> Arity
379 = case (primOpInfo op) of
383 GenPrimOp occ tyvars arg_tys res_ty -> length arg_tys
385 primOpType :: PrimOp -> Type -- you may want to use primOpSig instead
387 = case (primOpInfo op) of
388 Dyadic occ ty -> dyadic_fun_ty ty
389 Monadic occ ty -> monadic_fun_ty ty
390 Compare occ ty -> compare_fun_ty ty
392 GenPrimOp occ tyvars arg_tys res_ty ->
393 mkForAllTys tyvars (mkFunTys arg_tys res_ty)
395 mkPrimOpIdName :: PrimOp -> Name
396 -- Make the name for the PrimOp's Id
397 -- We have to pass in the Id itself because it's a WiredInId
398 -- and hence recursive
400 = mkWiredInName pREL_GHC (primOpOcc op) (mkPrimOpIdUnique (primOpTag op))
402 primOpRdrName :: PrimOp -> RdrName
403 primOpRdrName op = mkRdrOrig pREL_GHC_Name (primOpOcc op)
405 primOpOcc :: PrimOp -> OccName
406 primOpOcc op = case (primOpInfo op) of
410 GenPrimOp occ _ _ _ -> occ
412 -- primOpSig is like primOpType but gives the result split apart:
413 -- (type variables, argument types, result type)
414 -- It also gives arity, strictness info
416 primOpSig :: PrimOp -> ([TyVar], [Type], Type, Arity, StrictSig)
418 = (tyvars, arg_tys, res_ty, arity, primOpStrictness op arity)
420 arity = length arg_tys
421 (tyvars, arg_tys, res_ty)
422 = case (primOpInfo op) of
423 Monadic occ ty -> ([], [ty], ty )
424 Dyadic occ ty -> ([], [ty,ty], ty )
425 Compare occ ty -> ([], [ty,ty], boolTy)
426 GenPrimOp occ tyvars arg_tys res_ty
427 -> (tyvars, arg_tys, res_ty)
431 data PrimOpResultInfo
432 = ReturnsPrim PrimRep
435 -- Some PrimOps need not return a manifest primitive or algebraic value
436 -- (i.e. they might return a polymorphic value). These PrimOps *must*
437 -- be out of line, or the code generator won't work.
439 getPrimOpResultInfo :: PrimOp -> PrimOpResultInfo
440 getPrimOpResultInfo op
441 = case (primOpInfo op) of
442 Dyadic _ ty -> ReturnsPrim (typePrimRep ty)
443 Monadic _ ty -> ReturnsPrim (typePrimRep ty)
444 Compare _ ty -> ReturnsAlg boolTyCon
445 GenPrimOp _ _ _ ty | isPrimTyCon tc -> ReturnsPrim (tyConPrimRep tc)
446 | otherwise -> ReturnsAlg tc
448 tc = tyConAppTyCon ty
449 -- All primops return a tycon-app result
450 -- The tycon can be an unboxed tuple, though, which
451 -- gives rise to a ReturnAlg
454 The commutable ops are those for which we will try to move constants
455 to the right hand side for strength reduction.
458 commutableOp :: PrimOp -> Bool
459 #include "primop-commutable.hs-incl"
464 dyadic_fun_ty ty = mkFunTys [ty, ty] ty
465 monadic_fun_ty ty = mkFunTy ty ty
466 compare_fun_ty ty = mkFunTys [ty, ty] boolTy
471 pprPrimOp :: PrimOp -> SDoc
473 = getPprStyle $ \ sty ->
474 if ifaceStyle sty then -- For interfaces Print it qualified with PrelGHC.
475 ptext SLIT("PrelGHC.") <> pprOccName occ
479 occ = primOpOcc other_op
482 Names for some primops (for ndpFlatten/FlattenMonad.lhs)
485 eqCharName = mkPrimOpIdName CharEqOp
486 eqIntName = mkPrimOpIdName IntEqOp
487 eqFloatName = mkPrimOpIdName FloatEqOp
488 eqDoubleName = mkPrimOpIdName DoubleEqOp
489 neqIntName = mkPrimOpIdName IntNeOp