ghc/compiler/prelude/PrimOp.lhs

   1 %
   2 % (c) The GRASP/AQUA Project, Glasgow University, 1992-1998
   3 %
   4 \section[PrimOp]{Primitive operations (machine-level)}
   5
   6 \begin{code}
   7 module PrimOp (
   8         PrimOp(..), allThePrimOps,
   9         primOpType, primOpSig, primOpUsg, primOpArity,
  10         mkPrimOpIdName, primOpRdrName, primOpTag, primOpOcc,
  11
  12         commutableOp,
  13
  14         primOpOutOfLine, primOpNeedsWrapper,
  15         primOpOkForSpeculation, primOpIsCheap, primOpIsDupable,
  16         primOpHasSideEffects,
  17
  18         getPrimOpResultInfo,  PrimOpResultInfo(..)
  19     ) where
  20
  21 #include "HsVersions.h"
  22
  23 import PrimRep          -- most of it
  24 import TysPrim
  25 import TysWiredIn
  26
  27 import Demand           ( wwLazy, wwPrim, wwStrict, StrictnessInfo(..) )
  28 import Var              ( TyVar )
  29 import Name             ( Name, mkWiredInName )
  30 import RdrName          ( RdrName, mkRdrOrig )
  31 import OccName          ( OccName, pprOccName, mkVarOcc )
  32 import TyCon            ( TyCon )
  33 import Type             ( Type, mkForAllTys, mkFunTy, mkFunTys, typePrimRep,
  34                           splitFunTy_maybe, tyConAppTyCon, splitTyConApp,
  35                           mkUTy, usOnce, usMany
  36                         )
  37 import Unique           ( mkPrimOpIdUnique )
  38 import BasicTypes       ( Arity, Boxity(..) )
  39 import PrelNames        ( pREL_GHC, pREL_GHC_Name )
  40 import Outputable
  41 import Util             ( zipWithEqual )
  42 import FastTypes
  43 \end{code}
  44
  45 %************************************************************************
  46 %*                                                                      *
  47 \subsection[PrimOp-datatype]{Datatype for @PrimOp@ (an enumeration)}
  48 %*                                                                      *
  49 %************************************************************************
  50
  51 These are in \tr{state-interface.verb} order.
  52
  53 \begin{code}
  54
  55 -- supplies:
  56 -- data PrimOp = ...
  57 #include "primop-data-decl.hs-incl"
  58 \end{code}
  59
  60 Used for the Ord instance
  61
  62 \begin{code}
  63 primOpTag :: PrimOp -> Int
  64 primOpTag op = iBox (tagOf_PrimOp op)
  65
  66 -- supplies
  67 -- tagOf_PrimOp :: PrimOp -> FastInt
  68 #include "primop-tag.hs-incl"
  69 tagOf_PrimOp op = pprPanic# "tagOf_PrimOp: pattern-match" (ppr op)
  70
  71
  72 instance Eq PrimOp where
  73     op1 == op2 = tagOf_PrimOp op1 ==# tagOf_PrimOp op2
  74
  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
  81                       | op1 == op2 = EQ
  82                       | otherwise  = GT
  83
  84 instance Outputable PrimOp where
  85     ppr op = pprPrimOp op
  86
  87 instance Show PrimOp where
  88     showsPrec p op = showsPrecSDoc p (pprPrimOp op)
  89 \end{code}
  90
  91 An @Enum@-derived list would be better; meanwhile... (ToDo)
  92 \begin{code}
  93 allThePrimOps :: [PrimOp]
  94 allThePrimOps =
  95 #include "primop-list.hs-incl"
  96 \end{code}
  97
  98 %************************************************************************
  99 %*                                                                      *
 100 \subsection[PrimOp-info]{The essential info about each @PrimOp@}
 101 %*                                                                      *
 102 %************************************************************************
 103
 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.
 107
 108 The reason for the funny characters in the names is so we do not
 109 interfere with the programmer's Haskell name spaces.
 110
 111 We use @PrimKinds@ for the ``type'' information, because they're
 112 (slightly) more convenient to use than @TyCons@.
 113 \begin{code}
 114 data PrimOpInfo
 115   = Dyadic      OccName         -- string :: T -> T -> T
 116                 Type
 117   | Monadic     OccName         -- string :: T -> T
 118                 Type
 119   | Compare     OccName         -- string :: T -> T -> Bool
 120                 Type
 121
 122   | GenPrimOp   OccName         -- string :: \/a1..an . T1 -> .. -> Tk -> T
 123                 [TyVar]
 124                 [Type]
 125                 Type
 126
 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
 131 \end{code}
 132
 133 %************************************************************************
 134 %*                                                                      *
 135 \subsubsection{Strictness}
 136 %*                                                                      *
 137 %************************************************************************
 138
 139 Not all primops are strict!
 140
 141 \begin{code}
 142 primOpStrictness :: PrimOp -> Arity -> StrictnessInfo
 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"
 147 \end{code}
 148
 149 %************************************************************************
 150 %*                                                                      *
 151 \subsubsection[PrimOp-comparison]{PrimOpInfo basic comparison ops}
 152 %*                                                                      *
 153 %************************************************************************
 154
 155 @primOpInfo@ gives all essential information (from which everything
 156 else, notably a type, can be constructed) for each @PrimOp@.
 157
 158 \begin{code}
 159 primOpInfo :: PrimOp -> PrimOpInfo
 160 #include "primop-primop-info.hs-incl"
 161 \end{code}
 162
 163 Here are a load of comments from the old primOp info:
 164
 165 A @Word#@ is an unsigned @Int#@.
 166
 167 @decodeFloat#@ is given w/ Integer-stuff (it's similar).
 168
 169 @decodeDouble#@ is given w/ Integer-stuff (it's similar).
 170
 171 Decoding of floating-point numbers is sorta Integer-related.  Encoding
 172 is done with plain ccalls now (see PrelNumExtra.lhs).
 173
 174 A @Weak@ Pointer is created by the @mkWeak#@ primitive:
 175
 176         mkWeak# :: k -> v -> f -> State# RealWorld
 177                         -> (# State# RealWorld, Weak# v #)
 178
 179 In practice, you'll use the higher-level
 180
 181         data Weak v = Weak# v
 182         mkWeak :: k -> v -> IO () -> IO (Weak v)
 183
 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.
 187
 188         deRefWeak# :: Weak# v -> State# RealWorld ->
 189                         (# State# RealWorld, v, Int# #)
 190
 191 Only look at v if the Int# returned is /= 0 !!
 192
 193 The higher-level op is
 194
 195         deRefWeak :: Weak v -> IO (Maybe v)
 196
 197 Weak pointers can be finalized early by using the finalize# operation:
 198
 199         finalizeWeak# :: Weak# v -> State# RealWorld ->
 200                            (# State# RealWorld, Int#, IO () #)
 201
 202 The Int# returned is either
 203
 204         0 if the weak pointer has already been finalized, or it has no
 205           finalizer (the third component is then invalid).
 206
 207         1 if the weak pointer is still alive, with the finalizer returned
 208           as the third component.
 209
 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
 213 routines.
 214
 215 \begin{verbatim}
 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#
 220 \end{verbatim}
 221
 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@
 229 operation.)
 230
 231 An important property of stable pointers is that if you call
 232 makeStablePtr# twice on the same object you get the same stable
 233 pointer back.
 234
 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
 237 primop.
 238
 239 Question: Why @RealWorld@ - won't any instance of @_ST@ do the job? [ADR]
 240
 241 Stable Names
 242 ~~~~~~~~~~~~
 243
 244 A stable name is like a stable pointer, but with three important differences:
 245
 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'
 249
 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).
 252
 253 Invariants:
 254
 255         (a) makeStableName always returns the same value for a given
 256             object (same as stable pointers).
 257
 258         (b) if two stable names are equal, it implies that the objects
 259             from which they were created were the same.
 260
 261         (c) stableNameToInt always returns the same Int for a given
 262             stable name.
 263
 264
 265 [Alastair Reid is to blame for this!]
 266
 267 These days, (Glasgow) Haskell seems to have a bit of everything from
 268 other languages: strict operations, mutable variables, sequencing,
 269 pointers, etc.  About the only thing left is LISP's ability to test
 270 for pointer equality.  So, let's add it in!
 271
 272 \begin{verbatim}
 273 reallyUnsafePtrEquality :: a -> a -> Int#
 274 \end{verbatim}
 275
 276 which tests any two closures (of the same type) to see if they're the
 277 same.  (Returns $0$ for @False@, $\neq 0$ for @True@ - to avoid
 278 difficulties of trying to box up the result.)
 279
 280 NB This is {\em really unsafe\/} because even something as trivial as
 281 a garbage collection might change the answer by removing indirections.
 282 Still, no-one's forcing you to use it.  If you're worried about little
 283 things like loss of referential transparency, you might like to wrap
 284 it all up in a monad-like thing as John O'Donnell and John Hughes did
 285 for non-determinism (1989 (Fraserburgh) Glasgow FP Workshop
 286 Proceedings?)
 287
 288 I'm thinking of using it to speed up a critical equality test in some
 289 graphics stuff in a context where the possibility of saying that
 290 denotationally equal things aren't isn't a problem (as long as it
 291 doesn't happen too often.)  ADR
 292
 293 To Will: Jim said this was already in, but I can't see it so I'm
 294 adding it.  Up to you whether you add it.  (Note that this could have
 295 been readily implemented using a @veryDangerousCCall@ before they were
 296 removed...)
 297
 298
 299 -- HWL: The first 4 Int# in all par... annotations denote:
 300 --   name, granularity info, size of result, degree of parallelism
 301 --      Same  structure as _seq_ i.e. returns Int#
 302 -- KSW: v, the second arg in parAt# and parAtForNow#, is used only to determine
 303 --   `the processor containing the expression v'; it is not evaluated
 304
 305 These primops are pretty wierd.
 306
 307         dataToTag# :: a -> Int    (arg must be an evaluated data type)
 308         tagToEnum# :: Int -> a    (result type must be an enumerated type)
 309
 310 The constraints aren't currently checked by the front end, but the
 311 code generator will fall over if they aren't satisfied.
 312
 313 \begin{code}
 314 #ifdef DEBUG
 315 primOpInfo op = pprPanic "primOpInfo:" (ppr op)
 316 #endif
 317 \end{code}
 318
 319 %************************************************************************
 320 %*                                                                      *
 321 \subsubsection[PrimOp-ool]{Which PrimOps are out-of-line}
 322 %*                                                                      *
 323 %************************************************************************
 324
 325 Some PrimOps need to be called out-of-line because they either need to
 326 perform a heap check or they block.
 327
 328 \begin{code}
 329 #include "primop-out-of-line.hs-incl"
 330 \end{code}
 331
 332
 333 primOpOkForSpeculation
 334 ~~~~~~~~~~~~~~~~~~~~~~
 335 Sometimes we may choose to execute a PrimOp even though it isn't
 336 certain that its result will be required; ie execute them
 337 ``speculatively''.  The same thing as ``cheap eagerness.'' Usually
 338 this is OK, because PrimOps are usually cheap, but it isn't OK for
 339 (a)~expensive PrimOps and (b)~PrimOps which can fail.
 340
 341 PrimOps that have side effects also should not be executed speculatively.
 342
 343 Ok-for-speculation also means that it's ok *not* to execute the
 344 primop. For example
 345         case op a b of
 346           r -> 3
 347 Here the result is not used, so we can discard the primop.  Anything
 348 that has side effects mustn't be dicarded in this way, of course!
 349
 350 See also @primOpIsCheap@ (below).
 351
 352
 353 \begin{code}
 354 primOpOkForSpeculation :: PrimOp -> Bool
 355         -- See comments with CoreUtils.exprOkForSpeculation
 356 primOpOkForSpeculation op
 357   = not (primOpHasSideEffects op || primOpOutOfLine op || primOpCanFail op)
 358 \end{code}
 359
 360
 361 primOpIsCheap
 362 ~~~~~~~~~~~~~
 363 @primOpIsCheap@, as used in \tr{SimplUtils.lhs}.  For now (HACK
 364 WARNING), we just borrow some other predicates for a
 365 what-should-be-good-enough test.  "Cheap" means willing to call it more
 366 than once.  Evaluation order is unaffected.
 367
 368 \begin{code}
 369 primOpIsCheap :: PrimOp -> Bool
 370 primOpIsCheap op = False
 371         -- March 2001: be less eager to inline PrimOps
 372         -- Was: not (primOpHasSideEffects op || primOpOutOfLine op)
 373 \end{code}
 374
 375 primOpIsDupable
 376 ~~~~~~~~~~~~~~~
 377 primOpIsDupable means that the use of the primop is small enough to
 378 duplicate into different case branches.  See CoreUtils.exprIsDupable.
 379
 380 \begin{code}
 381 primOpIsDupable :: PrimOp -> Bool
 382         -- See comments with CoreUtils.exprIsDupable
 383         -- We say it's dupable it isn't implemented by a C call with a wrapper
 384 primOpIsDupable op = not (primOpNeedsWrapper op)
 385 \end{code}
 386
 387
 388 \begin{code}
 389 primOpCanFail :: PrimOp -> Bool
 390 #include "primop-can-fail.hs-incl"
 391 \end{code}
 392
 393 And some primops have side-effects and so, for example, must not be
 394 duplicated.
 395
 396 \begin{code}
 397 primOpHasSideEffects :: PrimOp -> Bool
 398 #include "primop-has-side-effects.hs-incl"
 399 \end{code}
 400
 401 Inline primitive operations that perform calls need wrappers to save
 402 any live variables that are stored in caller-saves registers.
 403
 404 \begin{code}
 405 primOpNeedsWrapper :: PrimOp -> Bool
 406 #include "primop-needs-wrapper.hs-incl"
 407 \end{code}
 408
 409 \begin{code}
 410 primOpArity :: PrimOp -> Arity
 411 primOpArity op
 412   = case (primOpInfo op) of
 413       Monadic occ ty                      -> 1
 414       Dyadic occ ty                       -> 2
 415       Compare occ ty                      -> 2
 416       GenPrimOp occ tyvars arg_tys res_ty -> length arg_tys
 417
 418 primOpType :: PrimOp -> Type  -- you may want to use primOpSig instead
 419 primOpType op
 420   = case (primOpInfo op) of
 421       Dyadic occ ty ->      dyadic_fun_ty ty
 422       Monadic occ ty ->     monadic_fun_ty ty
 423       Compare occ ty ->     compare_fun_ty ty
 424
 425       GenPrimOp occ tyvars arg_tys res_ty ->
 426         mkForAllTys tyvars (mkFunTys arg_tys res_ty)
 427
 428 mkPrimOpIdName :: PrimOp -> Name
 429         -- Make the name for the PrimOp's Id
 430         -- We have to pass in the Id itself because it's a WiredInId
 431         -- and hence recursive
 432 mkPrimOpIdName op
 433   = mkWiredInName pREL_GHC (primOpOcc op) (mkPrimOpIdUnique (primOpTag op))
 434
 435 primOpRdrName :: PrimOp -> RdrName
 436 primOpRdrName op = mkRdrOrig pREL_GHC_Name (primOpOcc op)
 437
 438 primOpOcc :: PrimOp -> OccName
 439 primOpOcc op = case (primOpInfo op) of
 440                               Dyadic    occ _     -> occ
 441                               Monadic   occ _     -> occ
 442                               Compare   occ _     -> occ
 443                               GenPrimOp occ _ _ _ -> occ
 444
 445 -- primOpSig is like primOpType but gives the result split apart:
 446 -- (type variables, argument types, result type)
 447 -- It also gives arity, strictness info
 448
 449 primOpSig :: PrimOp -> ([TyVar], [Type], Type, Arity, StrictnessInfo)
 450 primOpSig op
 451   = (tyvars, arg_tys, res_ty, arity, primOpStrictness op arity)
 452   where
 453     arity = length arg_tys
 454     (tyvars, arg_tys, res_ty)
 455       = case (primOpInfo op) of
 456           Monadic   occ ty -> ([],     [ty],    ty    )
 457           Dyadic    occ ty -> ([],     [ty,ty], ty    )
 458           Compare   occ ty -> ([],     [ty,ty], boolTy)
 459           GenPrimOp occ tyvars arg_tys res_ty
 460                            -> (tyvars, arg_tys, res_ty)
 461
 462 -- primOpUsg is like primOpSig but the types it yields are the
 463 -- appropriate sigma (i.e., usage-annotated) types,
 464 -- as required by the UsageSP inference.
 465
 466 primOpUsg :: PrimOp -> ([TyVar],[Type],Type)
 467 #include "primop-usage.hs-incl"
 468
 469 -- Things with no Haskell pointers inside: in actuality, usages are
 470 -- irrelevant here (hence it doesn't matter that some of these
 471 -- apparently permit duplication; since such arguments are never
 472 -- ENTERed anyway, the usage annotation they get is entirely irrelevant
 473 -- except insofar as it propagates to infect other values that *are*
 474 -- pointed.
 475
 476
 477 -- Helper bits & pieces for usage info.
 478
 479 mkZ          = mkUTy usOnce  -- pointed argument used zero
 480 mkO          = mkUTy usOnce  -- pointed argument used once
 481 mkM          = mkUTy usMany  -- pointed argument used multiply
 482 mkP          = mkUTy usOnce  -- unpointed argument
 483 mkR          = mkUTy usMany  -- unpointed result
 484
 485 nomangle op
 486    = case primOpSig op of
 487         (tyvars, arg_tys, res_ty, _, _)
 488            -> (tyvars, map mkP arg_tys, mkR res_ty)
 489
 490 mangle op fs g
 491    = case primOpSig op of
 492         (tyvars, arg_tys, res_ty, _, _)
 493            -> (tyvars, zipWithEqual "primOpUsg" ($) fs arg_tys, g res_ty)
 494
 495 inFun op f g ty
 496    = case splitFunTy_maybe ty of
 497         Just (a,b) -> mkFunTy (f a) (g b)
 498         Nothing    -> pprPanic "primOpUsg:inFun" (ppr op <+> ppr ty)
 499
 500 inUB op fs ty
 501    = case splitTyConApp ty of
 502         (tc,tys) -> ASSERT( tc == tupleTyCon Unboxed (length fs) )
 503                     mkTupleTy Unboxed (length fs) (zipWithEqual "primOpUsg" ($) fs tys)
 504 \end{code}
 505
 506 \begin{code}
 507 data PrimOpResultInfo
 508   = ReturnsPrim     PrimRep
 509   | ReturnsAlg      TyCon
 510
 511 -- Some PrimOps need not return a manifest primitive or algebraic value
 512 -- (i.e. they might return a polymorphic value).  These PrimOps *must*
 513 -- be out of line, or the code generator won't work.
 514
 515 getPrimOpResultInfo :: PrimOp -> PrimOpResultInfo
 516 getPrimOpResultInfo op
 517   = case (primOpInfo op) of
 518       Dyadic  _ ty               -> ReturnsPrim (typePrimRep ty)
 519       Monadic _ ty               -> ReturnsPrim (typePrimRep ty)
 520       Compare _ ty               -> ReturnsAlg boolTyCon
 521       GenPrimOp _ _ _ ty         -> case typePrimRep ty of
 522                                            PtrRep -> ReturnsAlg (tyConAppTyCon ty)
 523                                            rep    -> ReturnsPrim rep
 524 \end{code}
 525
 526 The commutable ops are those for which we will try to move constants
 527 to the right hand side for strength reduction.
 528
 529 \begin{code}
 530 commutableOp :: PrimOp -> Bool
 531 #include "primop-commutable.hs-incl"
 532 \end{code}
 533
 534 Utils:
 535 \begin{code}
 536 dyadic_fun_ty  ty = mkFunTys [ty, ty] ty
 537 monadic_fun_ty ty = mkFunTy  ty ty
 538 compare_fun_ty ty = mkFunTys [ty, ty] boolTy
 539 \end{code}
 540
 541 Output stuff:
 542 \begin{code}
 543 pprPrimOp  :: PrimOp -> SDoc
 544 pprPrimOp other_op
 545   = getPprStyle $ \ sty ->
 546     if ifaceStyle sty then      -- For interfaces Print it qualified with PrelGHC.
 547         ptext SLIT("PrelGHC.") <> pprOccName occ
 548     else
 549         pprOccName occ
 550   where
 551     occ = primOpOcc other_op
 552 \end{code}
 553
 554