2 % (c) The GRASP/AQUA Project, Glasgow University, 1992-1998
4 \section[PrimOp]{Primitive operations (machine-level)}
8 PrimOp(..), allThePrimOps,
10 primOpTag, maxPrimOpTag, primOpOcc,
12 primOpOutOfLine, primOpNeedsWrapper,
13 primOpOkForSpeculation, primOpIsCheap, primOpIsDupable,
15 getPrimOpResultInfo, PrimOpResultInfo(..)
18 #include "HsVersions.h"
20 import PrimRep -- most of it
26 import OccName ( OccName, pprOccName, mkVarOcc )
27 import TyCon ( TyCon, isPrimTyCon, tyConPrimRep )
28 import Type ( Type, mkForAllTys, mkFunTy, mkFunTys, typePrimRep, tyConAppTyCon )
29 import BasicTypes ( Arity, Boxity(..) )
34 %************************************************************************
36 \subsection[PrimOp-datatype]{Datatype for @PrimOp@ (an enumeration)}
38 %************************************************************************
40 These are in \tr{state-interface.verb} order.
46 #include "primop-data-decl.hs-incl"
49 Used for the Ord instance
52 primOpTag :: PrimOp -> Int
53 primOpTag op = iBox (tagOf_PrimOp op)
56 -- tagOf_PrimOp :: PrimOp -> FastInt
57 #include "primop-tag.hs-incl"
58 tagOf_PrimOp op = pprPanic# "tagOf_PrimOp: pattern-match" (ppr op)
61 instance Eq PrimOp where
62 op1 == op2 = tagOf_PrimOp op1 ==# tagOf_PrimOp op2
64 instance Ord PrimOp where
65 op1 < op2 = tagOf_PrimOp op1 <# tagOf_PrimOp op2
66 op1 <= op2 = tagOf_PrimOp op1 <=# tagOf_PrimOp op2
67 op1 >= op2 = tagOf_PrimOp op1 >=# tagOf_PrimOp op2
68 op1 > op2 = tagOf_PrimOp op1 ># tagOf_PrimOp op2
69 op1 `compare` op2 | op1 < op2 = LT
73 instance Outputable PrimOp where
76 instance Show PrimOp where
77 showsPrec p op = showsPrecSDoc p (pprPrimOp op)
80 An @Enum@-derived list would be better; meanwhile... (ToDo)
83 allThePrimOps :: [PrimOp]
85 #include "primop-list.hs-incl"
88 %************************************************************************
90 \subsection[PrimOp-info]{The essential info about each @PrimOp@}
92 %************************************************************************
94 The @String@ in the @PrimOpInfos@ is the ``base name'' by which the user may
95 refer to the primitive operation. The conventional \tr{#}-for-
96 unboxed ops is added on later.
98 The reason for the funny characters in the names is so we do not
99 interfere with the programmer's Haskell name spaces.
101 We use @PrimKinds@ for the ``type'' information, because they're
102 (slightly) more convenient to use than @TyCons@.
105 = Dyadic OccName -- string :: T -> T -> T
107 | Monadic OccName -- string :: T -> T
109 | Compare OccName -- string :: T -> T -> Bool
112 | GenPrimOp OccName -- string :: \/a1..an . T1 -> .. -> Tk -> T
117 mkDyadic str ty = Dyadic (mkVarOcc str) ty
118 mkMonadic str ty = Monadic (mkVarOcc str) ty
119 mkCompare str ty = Compare (mkVarOcc str) ty
120 mkGenPrimOp str tvs tys ty = GenPrimOp (mkVarOcc str) tvs tys ty
123 %************************************************************************
125 \subsubsection{Strictness}
127 %************************************************************************
129 Not all primops are strict!
132 primOpStrictness :: PrimOp -> Arity -> StrictSig
133 -- See Demand.StrictnessInfo for discussion of what the results
134 -- The arity should be the arity of the primop; that's why
135 -- this function isn't exported.
136 #include "primop-strictness.hs-incl"
139 %************************************************************************
141 \subsubsection[PrimOp-comparison]{PrimOpInfo basic comparison ops}
143 %************************************************************************
145 @primOpInfo@ gives all essential information (from which everything
146 else, notably a type, can be constructed) for each @PrimOp@.
149 primOpInfo :: PrimOp -> PrimOpInfo
150 #include "primop-primop-info.hs-incl"
153 Here are a load of comments from the old primOp info:
155 A @Word#@ is an unsigned @Int#@.
157 @decodeFloat#@ is given w/ Integer-stuff (it's similar).
159 @decodeDouble#@ is given w/ Integer-stuff (it's similar).
161 Decoding of floating-point numbers is sorta Integer-related. Encoding
162 is done with plain ccalls now (see PrelNumExtra.lhs).
164 A @Weak@ Pointer is created by the @mkWeak#@ primitive:
166 mkWeak# :: k -> v -> f -> State# RealWorld
167 -> (# State# RealWorld, Weak# v #)
169 In practice, you'll use the higher-level
171 data Weak v = Weak# v
172 mkWeak :: k -> v -> IO () -> IO (Weak v)
174 The following operation dereferences a weak pointer. The weak pointer
175 may have been finalized, so the operation returns a result code which
176 must be inspected before looking at the dereferenced value.
178 deRefWeak# :: Weak# v -> State# RealWorld ->
179 (# State# RealWorld, v, Int# #)
181 Only look at v if the Int# returned is /= 0 !!
183 The higher-level op is
185 deRefWeak :: Weak v -> IO (Maybe v)
187 Weak pointers can be finalized early by using the finalize# operation:
189 finalizeWeak# :: Weak# v -> State# RealWorld ->
190 (# State# RealWorld, Int#, IO () #)
192 The Int# returned is either
194 0 if the weak pointer has already been finalized, or it has no
195 finalizer (the third component is then invalid).
197 1 if the weak pointer is still alive, with the finalizer returned
198 as the third component.
200 A {\em stable name/pointer} is an index into a table of stable name
201 entries. Since the garbage collector is told about stable pointers,
202 it is safe to pass a stable pointer to external systems such as C
206 makeStablePtr# :: a -> State# RealWorld -> (# State# RealWorld, StablePtr# a #)
207 freeStablePtr :: StablePtr# a -> State# RealWorld -> State# RealWorld
208 deRefStablePtr# :: StablePtr# a -> State# RealWorld -> (# State# RealWorld, a #)
209 eqStablePtr# :: StablePtr# a -> StablePtr# a -> Int#
212 It may seem a bit surprising that @makeStablePtr#@ is a @IO@
213 operation since it doesn't (directly) involve IO operations. The
214 reason is that if some optimisation pass decided to duplicate calls to
215 @makeStablePtr#@ and we only pass one of the stable pointers over, a
216 massive space leak can result. Putting it into the IO monad
217 prevents this. (Another reason for putting them in a monad is to
218 ensure correct sequencing wrt the side-effecting @freeStablePtr@
221 An important property of stable pointers is that if you call
222 makeStablePtr# twice on the same object you get the same stable
225 Note that we can implement @freeStablePtr#@ using @_ccall_@ (and,
226 besides, it's not likely to be used from Haskell) so it's not a
229 Question: Why @RealWorld@ - won't any instance of @_ST@ do the job? [ADR]
234 A stable name is like a stable pointer, but with three important differences:
236 (a) You can't deRef one to get back to the original object.
237 (b) You can convert one to an Int.
238 (c) You don't need to 'freeStableName'
240 The existence of a stable name doesn't guarantee to keep the object it
241 points to alive (unlike a stable pointer), hence (a).
245 (a) makeStableName always returns the same value for a given
246 object (same as stable pointers).
248 (b) if two stable names are equal, it implies that the objects
249 from which they were created were the same.
251 (c) stableNameToInt always returns the same Int for a given
255 -- HWL: The first 4 Int# in all par... annotations denote:
256 -- name, granularity info, size of result, degree of parallelism
257 -- Same structure as _seq_ i.e. returns Int#
258 -- KSW: v, the second arg in parAt# and parAtForNow#, is used only to determine
259 -- `the processor containing the expression v'; it is not evaluated
261 These primops are pretty wierd.
263 dataToTag# :: a -> Int (arg must be an evaluated data type)
264 tagToEnum# :: Int -> a (result type must be an enumerated type)
266 The constraints aren't currently checked by the front end, but the
267 code generator will fall over if they aren't satisfied.
271 primOpInfo op = pprPanic "primOpInfo:" (ppr op)
275 %************************************************************************
277 \subsubsection[PrimOp-ool]{Which PrimOps are out-of-line}
279 %************************************************************************
281 Some PrimOps need to be called out-of-line because they either need to
282 perform a heap check or they block.
286 primOpOutOfLine :: PrimOp -> Bool
287 #include "primop-out-of-line.hs-incl"
291 primOpOkForSpeculation
292 ~~~~~~~~~~~~~~~~~~~~~~
293 Sometimes we may choose to execute a PrimOp even though it isn't
294 certain that its result will be required; ie execute them
295 ``speculatively''. The same thing as ``cheap eagerness.'' Usually
296 this is OK, because PrimOps are usually cheap, but it isn't OK for
297 (a)~expensive PrimOps and (b)~PrimOps which can fail.
299 PrimOps that have side effects also should not be executed speculatively.
301 Ok-for-speculation also means that it's ok *not* to execute the
305 Here the result is not used, so we can discard the primop. Anything
306 that has side effects mustn't be dicarded in this way, of course!
308 See also @primOpIsCheap@ (below).
312 primOpOkForSpeculation :: PrimOp -> Bool
313 -- See comments with CoreUtils.exprOkForSpeculation
314 primOpOkForSpeculation op
315 = not (primOpHasSideEffects op || primOpOutOfLine op || primOpCanFail op)
321 @primOpIsCheap@, as used in \tr{SimplUtils.lhs}. For now (HACK
322 WARNING), we just borrow some other predicates for a
323 what-should-be-good-enough test. "Cheap" means willing to call it more
324 than once. Evaluation order is unaffected.
327 primOpIsCheap :: PrimOp -> Bool
328 primOpIsCheap op = False
329 -- March 2001: be less eager to inline PrimOps
330 -- Was: not (primOpHasSideEffects op || primOpOutOfLine op)
335 primOpIsDupable means that the use of the primop is small enough to
336 duplicate into different case branches. See CoreUtils.exprIsDupable.
339 primOpIsDupable :: PrimOp -> Bool
340 -- See comments with CoreUtils.exprIsDupable
341 -- We say it's dupable it isn't implemented by a C call with a wrapper
342 primOpIsDupable op = not (primOpNeedsWrapper op)
347 primOpCanFail :: PrimOp -> Bool
348 #include "primop-can-fail.hs-incl"
351 And some primops have side-effects and so, for example, must not be
355 primOpHasSideEffects :: PrimOp -> Bool
356 #include "primop-has-side-effects.hs-incl"
359 Inline primitive operations that perform calls need wrappers to save
360 any live variables that are stored in caller-saves registers.
363 primOpNeedsWrapper :: PrimOp -> Bool
364 #include "primop-needs-wrapper.hs-incl"
368 primOpType :: PrimOp -> Type -- you may want to use primOpSig instead
370 = case (primOpInfo op) of
371 Dyadic occ ty -> dyadic_fun_ty ty
372 Monadic occ ty -> monadic_fun_ty ty
373 Compare occ ty -> compare_fun_ty ty
375 GenPrimOp occ tyvars arg_tys res_ty ->
376 mkForAllTys tyvars (mkFunTys arg_tys res_ty)
378 primOpOcc :: PrimOp -> OccName
379 primOpOcc op = case (primOpInfo op) of
383 GenPrimOp occ _ _ _ -> occ
385 -- primOpSig is like primOpType but gives the result split apart:
386 -- (type variables, argument types, result type)
387 -- It also gives arity, strictness info
389 primOpSig :: PrimOp -> ([TyVar], [Type], Type, Arity, StrictSig)
391 = (tyvars, arg_tys, res_ty, arity, primOpStrictness op arity)
393 arity = length arg_tys
394 (tyvars, arg_tys, res_ty)
395 = case (primOpInfo op) of
396 Monadic occ ty -> ([], [ty], ty )
397 Dyadic occ ty -> ([], [ty,ty], ty )
398 Compare occ ty -> ([], [ty,ty], boolTy)
399 GenPrimOp occ tyvars arg_tys res_ty
400 -> (tyvars, arg_tys, res_ty)
404 data PrimOpResultInfo
405 = ReturnsPrim PrimRep
408 -- Some PrimOps need not return a manifest primitive or algebraic value
409 -- (i.e. they might return a polymorphic value). These PrimOps *must*
410 -- be out of line, or the code generator won't work.
412 getPrimOpResultInfo :: PrimOp -> PrimOpResultInfo
413 getPrimOpResultInfo op
414 = case (primOpInfo op) of
415 Dyadic _ ty -> ReturnsPrim (typePrimRep ty)
416 Monadic _ ty -> ReturnsPrim (typePrimRep ty)
417 Compare _ ty -> ReturnsAlg boolTyCon
418 GenPrimOp _ _ _ ty | isPrimTyCon tc -> ReturnsPrim (tyConPrimRep tc)
419 | otherwise -> ReturnsAlg tc
421 tc = tyConAppTyCon ty
422 -- All primops return a tycon-app result
423 -- The tycon can be an unboxed tuple, though, which
424 -- gives rise to a ReturnAlg
427 The commutable ops are those for which we will try to move constants
428 to the right hand side for strength reduction.
431 commutableOp :: PrimOp -> Bool
432 #include "primop-commutable.hs-incl"
437 dyadic_fun_ty ty = mkFunTys [ty, ty] ty
438 monadic_fun_ty ty = mkFunTy ty ty
439 compare_fun_ty ty = mkFunTys [ty, ty] boolTy
444 pprPrimOp :: PrimOp -> SDoc
445 pprPrimOp other_op = pprOccName (primOpOcc other_op)