ghc/compiler/codeGen/ClosureInfo.lhs

   1 %
   2 % (c) The Univserity of Glasgow 1992-2004
   3 %
   4
   5         Data structures which describe closures, and
   6         operations over those data structures
   7
   8                 Nothing monadic in here
   9
  10 Much of the rationale for these things is in the ``details'' part of
  11 the STG paper.
  12
  13 \begin{code}
  14 module ClosureInfo (
  15         ClosureInfo, LambdaFormInfo, SMRep,     -- all abstract
  16         StandardFormInfo,
  17
  18         ArgDescr(..), Liveness(..),
  19         C_SRT(..), needsSRT,
  20
  21         mkLFThunk, mkLFReEntrant, mkConLFInfo, mkSelectorLFInfo,
  22         mkApLFInfo, mkLFImported, mkLFArgument, mkLFLetNoEscape,
  23
  24         mkClosureInfo, mkConInfo,
  25
  26         closureSize, closureNonHdrSize,
  27         closureGoodStuffSize, closurePtrsSize,
  28         slopSize,
  29
  30         closureName, infoTableLabelFromCI,
  31         closureLabelFromCI, closureSRT,
  32         closureLFInfo, closureSMRep, closureUpdReqd,
  33         closureNeedsUpdSpace,
  34         closureSingleEntry, closureReEntrant, isConstrClosure_maybe,
  35         closureFunInfo, isStandardFormThunk, isKnownFun,
  36
  37         enterIdLabel, enterLocalIdLabel, enterReturnPtLabel,
  38
  39         nodeMustPointToIt,
  40         CallMethod(..), getCallMethod,
  41
  42         blackHoleOnEntry,
  43
  44         staticClosureRequired,
  45         getClosureType,
  46
  47         isToplevClosure,
  48         closureValDescr, closureTypeDescr,      -- profiling
  49
  50         isStaticClosure,
  51         cafBlackHoleClosureInfo, seCafBlackHoleClosureInfo,
  52
  53         staticClosureNeedsLink,
  54     ) where
  55
  56 #include "../includes/MachDeps.h"
  57 #include "HsVersions.h"
  58
  59 import StgSyn
  60 import SMRep            -- all of it
  61
  62 import CLabel
  63
  64 import Constants        ( mIN_UPD_SIZE, mIN_SIZE_NonUpdHeapObject )
  65 import Packages         ( isDllName )
  66 import CmdLineOpts      ( DynFlags, opt_SccProfilingOn, opt_OmitBlackHoling,
  67                           opt_Parallel, opt_DoTickyProfiling,
  68                           opt_SMP )
  69 import Id               ( Id, idType, idArity, idName )
  70 import DataCon          ( DataCon, dataConTyCon, isNullaryRepDataCon, dataConName )
  71 import Name             ( Name, nameUnique, getOccName, getOccString )
  72 import OccName          ( occNameUserString )
  73 import Type             ( isUnLiftedType, Type, repType, splitTyConApp_maybe )
  74 import TcType           ( tcSplitSigmaTy )
  75 import TyCon            ( isFunTyCon, isAbstractTyCon )
  76 import BasicTypes       ( TopLevelFlag(..), isNotTopLevel, isTopLevel, ipNameName )
  77 import FastString
  78 import Outputable
  79 import Constants
  80
  81 import TypeRep  -- TEMP
  82 \end{code}
  83
  84
  85 %************************************************************************
  86 %*                                                                      *
  87 \subsection[ClosureInfo-datatypes]{Data types for closure information}
  88 %*                                                                      *
  89 %************************************************************************
  90
  91 Information about a closure, from the code generator's point of view.
  92
  93 A ClosureInfo decribes the info pointer of a closure.  It has
  94 enough information
  95   a) to construct the info table itself
  96   b) to allocate a closure containing that info pointer (i.e.
  97         it knows the info table label)
  98
  99 We make a ClosureInfo for
 100         - each let binding (both top level and not)
 101         - each data constructor (for its shared static and
 102                 dynamic info tables)
 103
 104 \begin{code}
 105 data ClosureInfo
 106   = ClosureInfo {
 107         closureName   :: !Name,           -- The thing bound to this closure
 108         closureLFInfo :: !LambdaFormInfo, -- NOTE: not an LFCon (see below)
 109         closureSMRep  :: !SMRep,          -- representation used by storage mgr
 110         closureSRT    :: !C_SRT,          -- What SRT applies to this closure
 111         closureType   :: !Type,           -- Type of closure (ToDo: remove)
 112         closureDescr  :: !String          -- closure description (for profiling)
 113     }
 114
 115   -- Constructor closures don't have a unique info table label (they use
 116   -- the constructor's info table), and they don't have an SRT.
 117   | ConInfo {
 118         closureCon       :: !DataCon,
 119         closureSMRep     :: !SMRep,
 120         closureDllCon    :: !Bool       -- is in a separate DLL
 121     }
 122
 123 -- C_SRT is what StgSyn.SRT gets translated to...
 124 -- we add a label for the table, and expect only the 'offset/length' form
 125
 126 data C_SRT = NoC_SRT
 127            | C_SRT !CLabel !WordOff !StgHalfWord {-bitmap or escape-}
 128
 129 needsSRT :: C_SRT -> Bool
 130 needsSRT NoC_SRT       = False
 131 needsSRT (C_SRT _ _ _) = True
 132 \end{code}
 133
 134 %************************************************************************
 135 %*                                                                      *
 136 \subsubsection[LambdaFormInfo-datatype]{@LambdaFormInfo@: source-derivable info}
 137 %*                                                                      *
 138 %************************************************************************
 139
 140 Information about an identifier, from the code generator's point of
 141 view.  Every identifier is bound to a LambdaFormInfo in the
 142 environment, which gives the code generator enough info to be able to
 143 tail call or return that identifier.
 144
 145 Note that a closure is usually bound to an identifier, so a
 146 ClosureInfo contains a LambdaFormInfo.
 147
 148 \begin{code}
 149 data LambdaFormInfo
 150   = LFReEntrant         -- Reentrant closure (a function)
 151         TopLevelFlag    -- True if top level
 152         !Int            -- Arity. Invariant: always > 0
 153         !Bool           -- True <=> no fvs
 154         ArgDescr        -- Argument descriptor (should reall be in ClosureInfo)
 155
 156   | LFCon               -- A saturated constructor application
 157         DataCon         -- The constructor
 158
 159   | LFThunk             -- Thunk (zero arity)
 160         TopLevelFlag
 161         !Bool           -- True <=> no free vars
 162         !Bool           -- True <=> updatable (i.e., *not* single-entry)
 163         StandardFormInfo
 164         !Bool           -- True <=> *might* be a function type
 165
 166   | LFUnknown           -- Used for function arguments and imported things.
 167                         --  We know nothing about  this closure.  Treat like
 168                         -- updatable "LFThunk"...
 169                         -- Imported things which we do know something about use
 170                         -- one of the other LF constructors (eg LFReEntrant for
 171                         -- known functions)
 172         !Bool           -- True <=> *might* be a function type
 173
 174   | LFLetNoEscape       -- See LetNoEscape module for precise description of
 175                         -- these "lets".
 176         !Int            -- arity;
 177
 178   | LFBlackHole         -- Used for the closures allocated to hold the result
 179                         -- of a CAF.  We want the target of the update frame to
 180                         -- be in the heap, so we make a black hole to hold it.
 181         CLabel          -- Flavour (info label, eg CAF_BLACKHOLE_info).
 182
 183
 184 -------------------------
 185 -- An ArgDsecr describes the argument pattern of a function
 186
 187 data ArgDescr
 188   = ArgSpec             -- Fits one of the standard patterns
 189         !Int            -- RTS type identifier ARG_P, ARG_N, ...
 190
 191   | ArgGen              -- General case
 192         Liveness        -- Details about the arguments
 193
 194
 195 -------------------------
 196 -- We represent liveness bitmaps as a Bitmap (whose internal
 197 -- representation really is a bitmap).  These are pinned onto case return
 198 -- vectors to indicate the state of the stack for the garbage collector.
 199 --
 200 -- In the compiled program, liveness bitmaps that fit inside a single
 201 -- word (StgWord) are stored as a single word, while larger bitmaps are
 202 -- stored as a pointer to an array of words.
 203
 204 data Liveness
 205   = SmallLiveness       -- Liveness info that fits in one word
 206         StgWord         -- Here's the bitmap
 207
 208   | BigLiveness         -- Liveness info witha a multi-word bitmap
 209         CLabel          -- Label for the bitmap
 210
 211
 212 -------------------------
 213 -- StandardFormInfo tells whether this thunk has one of
 214 -- a small number of standard forms
 215
 216 data StandardFormInfo
 217   = NonStandardThunk
 218         -- Not of of the standard forms
 219
 220   | SelectorThunk
 221         -- A SelectorThunk is of form
 222         --      case x of
 223         --             con a1,..,an -> ak
 224         -- and the constructor is from a single-constr type.
 225        WordOff                  -- 0-origin offset of ak within the "goods" of
 226                         -- constructor (Recall that the a1,...,an may be laid
 227                         -- out in the heap in a non-obvious order.)
 228
 229   | ApThunk
 230         -- An ApThunk is of form
 231         --      x1 ... xn
 232         -- The code for the thunk just pushes x2..xn on the stack and enters x1.
 233         -- There are a few of these (for 1 <= n <= MAX_SPEC_AP_SIZE) pre-compiled
 234         -- in the RTS to save space.
 235         Int             -- Arity, n
 236 \end{code}
 237
 238 %************************************************************************
 239 %*                                                                      *
 240 \subsection[ClosureInfo-construction]{Functions which build LFInfos}
 241 %*                                                                      *
 242 %************************************************************************
 243
 244 \begin{code}
 245 mkLFReEntrant :: TopLevelFlag   -- True of top level
 246               -> [Id]           -- Free vars
 247               -> [Id]           -- Args
 248               -> ArgDescr       -- Argument descriptor
 249               -> LambdaFormInfo
 250
 251 mkLFReEntrant top fvs args arg_descr
 252   = LFReEntrant top (length args) (null fvs) arg_descr
 253
 254 mkLFThunk thunk_ty top fvs upd_flag
 255   = ASSERT( not (isUpdatable upd_flag) || not (isUnLiftedType thunk_ty) )
 256     LFThunk top (null fvs)
 257             (isUpdatable upd_flag)
 258             NonStandardThunk
 259             (might_be_a_function thunk_ty)
 260
 261 might_be_a_function :: Type -> Bool
 262 might_be_a_function ty
 263   | Just (tc,_) <- splitTyConApp_maybe (repType ty),
 264     not (isFunTyCon tc)  && not (isAbstractTyCon tc) = False
 265         -- don't forget to check for abstract types, which might
 266         -- be functions too.
 267   | otherwise = True
 268 \end{code}
 269
 270 @mkConLFInfo@ is similar, for constructors.
 271
 272 \begin{code}
 273 mkConLFInfo :: DataCon -> LambdaFormInfo
 274 mkConLFInfo con = LFCon con
 275
 276 mkSelectorLFInfo id offset updatable
 277   = LFThunk NotTopLevel False updatable (SelectorThunk offset)
 278         (might_be_a_function (idType id))
 279
 280 mkApLFInfo id upd_flag arity
 281   = LFThunk NotTopLevel (arity == 0) (isUpdatable upd_flag) (ApThunk arity)
 282         (might_be_a_function (idType id))
 283 \end{code}
 284
 285 Miscellaneous LF-infos.
 286
 287 \begin{code}
 288 mkLFArgument id = LFUnknown (might_be_a_function (idType id))
 289
 290 mkLFLetNoEscape = LFLetNoEscape
 291
 292 mkLFImported :: Id -> LambdaFormInfo
 293 mkLFImported id
 294   = case idArity id of
 295       n | n > 0 -> LFReEntrant TopLevel n True (panic "arg_descr")  -- n > 0
 296       other -> mkLFArgument id -- Not sure of exact arity
 297 \end{code}
 298
 299 %************************************************************************
 300 %*                                                                      *
 301         Building ClosureInfos
 302 %*                                                                      *
 303 %************************************************************************
 304
 305 \begin{code}
 306 mkClosureInfo :: Bool           -- Is static
 307               -> Id
 308               -> LambdaFormInfo
 309               -> Int -> Int     -- Total and pointer words
 310               -> C_SRT
 311               -> String         -- String descriptor
 312               -> ClosureInfo
 313 mkClosureInfo is_static id lf_info tot_wds ptr_wds srt_info descr
 314   = ClosureInfo { closureName = name,
 315                   closureLFInfo = lf_info,
 316                   closureSMRep = sm_rep,
 317                   closureSRT = srt_info,
 318                   closureType = idType id,
 319                   closureDescr = descr }
 320   where
 321     name   = idName id
 322     sm_rep = chooseSMRep is_static lf_info tot_wds ptr_wds
 323
 324 mkConInfo :: DynFlags
 325           -> Bool       -- Is static
 326           -> DataCon
 327           -> Int -> Int -- Total and pointer words
 328           -> ClosureInfo
 329 mkConInfo dflags is_static data_con tot_wds ptr_wds
 330    = ConInfo {  closureSMRep = sm_rep,
 331                 closureCon = data_con,
 332                 closureDllCon = isDllName dflags (dataConName data_con) }
 333   where
 334     sm_rep = chooseSMRep is_static (mkConLFInfo data_con) tot_wds ptr_wds
 335 \end{code}
 336
 337 %************************************************************************
 338 %*                                                                      *
 339 \subsection[ClosureInfo-sizes]{Functions about closure {\em sizes}}
 340 %*                                                                      *
 341 %************************************************************************
 342
 343 \begin{code}
 344 closureSize :: ClosureInfo -> WordOff
 345 closureSize cl_info = fixedHdrSize + closureNonHdrSize cl_info
 346
 347 closureNonHdrSize :: ClosureInfo -> WordOff
 348 closureNonHdrSize cl_info
 349   = tot_wds + computeSlopSize tot_wds
 350                               (closureSMRep cl_info)
 351                               (closureNeedsUpdSpace cl_info)
 352   where
 353     tot_wds = closureGoodStuffSize cl_info
 354
 355 -- we leave space for an update if either (a) the closure is updatable
 356 -- or (b) it is a static thunk.  This is because a static thunk needs
 357 -- a static link field in a predictable place (after the slop), regardless
 358 -- of whether it is updatable or not.
 359 closureNeedsUpdSpace (ClosureInfo { closureLFInfo =
 360                                         LFThunk TopLevel _ _ _ _ }) = True
 361 closureNeedsUpdSpace cl_info = closureUpdReqd cl_info
 362
 363 slopSize :: ClosureInfo -> WordOff
 364 slopSize cl_info
 365   = computeSlopSize (closureGoodStuffSize cl_info)
 366                     (closureSMRep cl_info)
 367                     (closureNeedsUpdSpace cl_info)
 368
 369 closureGoodStuffSize :: ClosureInfo -> WordOff
 370 closureGoodStuffSize cl_info
 371   = let (ptrs, nonptrs) = sizes_from_SMRep (closureSMRep cl_info)
 372     in  ptrs + nonptrs
 373
 374 closurePtrsSize :: ClosureInfo -> WordOff
 375 closurePtrsSize cl_info
 376   = let (ptrs, _) = sizes_from_SMRep (closureSMRep cl_info)
 377     in  ptrs
 378
 379 -- not exported:
 380 sizes_from_SMRep :: SMRep -> (WordOff,WordOff)
 381 sizes_from_SMRep (GenericRep _ ptrs nonptrs _)   = (ptrs, nonptrs)
 382 sizes_from_SMRep BlackHoleRep                    = (0, 0)
 383 \end{code}
 384
 385 Computing slop size.  WARNING: this looks dodgy --- it has deep
 386 knowledge of what the storage manager does with the various
 387 representations...
 388
 389 Slop Requirements:
 390 \begin{itemize}
 391 \item
 392 Updateable closures must be @mIN_UPD_SIZE@.
 393         \begin{itemize}
 394         \item
 395         Indirections require 1 word
 396         \item
 397         Appels collector indirections 2 words
 398         \end{itemize}
 399 THEREFORE: @mIN_UPD_SIZE = 2@.
 400
 401 \item
 402 Collectable closures which are allocated in the heap
 403 must be @mIN_SIZE_NonUpdHeapObject@.
 404
 405 Copying collector forward pointer requires 1 word
 406
 407 THEREFORE: @mIN_SIZE_NonUpdHeapObject = 1@
 408 \end{itemize}
 409
 410 Static closures have an extra ``static link field'' at the end, but we
 411 don't bother taking that into account here.
 412
 413 \begin{code}
 414 computeSlopSize :: WordOff -> SMRep -> Bool -> WordOff
 415
 416 computeSlopSize tot_wds (GenericRep _ _ _ _) True               -- Updatable
 417   = max 0 (mIN_UPD_SIZE - tot_wds)
 418
 419 computeSlopSize tot_wds (GenericRep True _ _ _) False   -- Non updatable
 420   = 0                                                   -- Static
 421
 422 computeSlopSize tot_wds (GenericRep False _ _ _) False  -- Non updatable
 423   = max 0 (mIN_SIZE_NonUpdHeapObject - tot_wds)         -- Dynamic
 424
 425 computeSlopSize tot_wds BlackHoleRep _                  -- Updatable
 426   = max 0 (mIN_UPD_SIZE - tot_wds)
 427 \end{code}
 428
 429 %************************************************************************
 430 %*                                                                      *
 431 \subsection[SMreps]{Choosing SM reps}
 432 %*                                                                      *
 433 %************************************************************************
 434
 435 \begin{code}
 436 chooseSMRep
 437         :: Bool                 -- True <=> static closure
 438         -> LambdaFormInfo
 439         -> WordOff -> WordOff   -- Tot wds, ptr wds
 440         -> SMRep
 441
 442 chooseSMRep is_static lf_info tot_wds ptr_wds
 443   = let
 444          nonptr_wds   = tot_wds - ptr_wds
 445          closure_type = getClosureType is_static ptr_wds lf_info
 446     in
 447     GenericRep is_static ptr_wds nonptr_wds closure_type
 448
 449 -- We *do* get non-updatable top-level thunks sometimes.  eg. f = g
 450 -- gets compiled to a jump to g (if g has non-zero arity), instead of
 451 -- messing around with update frames and PAPs.  We set the closure type
 452 -- to FUN_STATIC in this case.
 453
 454 getClosureType :: Bool -> WordOff -> LambdaFormInfo -> ClosureType
 455 getClosureType is_static ptr_wds lf_info
 456   = case lf_info of
 457         LFCon con | is_static && ptr_wds == 0   -> ConstrNoCaf
 458                   | otherwise                   -> Constr
 459         LFReEntrant _ _ _ _                     -> Fun
 460         LFThunk _ _ _ (SelectorThunk _) _       -> ThunkSelector
 461         LFThunk _ _ _ _ _                       -> Thunk
 462         _ -> panic "getClosureType"
 463 \end{code}
 464
 465 %************************************************************************
 466 %*                                                                      *
 467 \subsection[ClosureInfo-4-questions]{Four major questions about @ClosureInfo@}
 468 %*                                                                      *
 469 %************************************************************************
 470
 471 Be sure to see the stg-details notes about these...
 472
 473 \begin{code}
 474 nodeMustPointToIt :: LambdaFormInfo -> Bool
 475 nodeMustPointToIt (LFReEntrant top _ no_fvs _)
 476   = not no_fvs ||   -- Certainly if it has fvs we need to point to it
 477     isNotTopLevel top
 478                     -- If it is not top level we will point to it
 479                     --   We can have a \r closure with no_fvs which
 480                     --   is not top level as special case cgRhsClosure
 481                     --   has been dissabled in favour of let floating
 482
 483                 -- For lex_profiling we also access the cost centre for a
 484                 -- non-inherited function i.e. not top level
 485                 -- the  not top  case above ensures this is ok.
 486
 487 nodeMustPointToIt (LFCon _) = True
 488
 489         -- Strictly speaking, the above two don't need Node to point
 490         -- to it if the arity = 0.  But this is a *really* unlikely
 491         -- situation.  If we know it's nil (say) and we are entering
 492         -- it. Eg: let x = [] in x then we will certainly have inlined
 493         -- x, since nil is a simple atom.  So we gain little by not
 494         -- having Node point to known zero-arity things.  On the other
 495         -- hand, we do lose something; Patrick's code for figuring out
 496         -- when something has been updated but not entered relies on
 497         -- having Node point to the result of an update.  SLPJ
 498         -- 27/11/92.
 499
 500 nodeMustPointToIt (LFThunk _ no_fvs updatable NonStandardThunk _)
 501   = updatable || not no_fvs || opt_SccProfilingOn
 502           -- For the non-updatable (single-entry case):
 503           --
 504           -- True if has fvs (in which case we need access to them, and we
 505           --                should black-hole it)
 506           -- or profiling (in which case we need to recover the cost centre
 507           --             from inside it)
 508
 509 nodeMustPointToIt (LFThunk _ no_fvs updatable some_standard_form_thunk _)
 510   = True  -- Node must point to any standard-form thunk
 511
 512 nodeMustPointToIt (LFUnknown _)     = True
 513 nodeMustPointToIt (LFBlackHole _)   = True    -- BH entry may require Node to point
 514 nodeMustPointToIt (LFLetNoEscape _) = False
 515 \end{code}
 516
 517 The entry conventions depend on the type of closure being entered,
 518 whether or not it has free variables, and whether we're running
 519 sequentially or in parallel.
 520
 521 \begin{tabular}{lllll}
 522 Closure Characteristics & Parallel & Node Req'd & Argument Passing & Enter Via \\
 523 Unknown                         & no & yes & stack      & node \\
 524 Known fun ($\ge$ 1 arg), no fvs         & no & no  & registers  & fast entry (enough args) \\
 525 \ & \ & \ & \                                           & slow entry (otherwise) \\
 526 Known fun ($\ge$ 1 arg), fvs    & no & yes & registers  & fast entry (enough args) \\
 527 0 arg, no fvs @\r,\s@           & no & no  & n/a        & direct entry \\
 528 0 arg, no fvs @\u@              & no & yes & n/a        & node \\
 529 0 arg, fvs @\r,\s@              & no & yes & n/a        & direct entry \\
 530 0 arg, fvs @\u@                 & no & yes & n/a        & node \\
 531
 532 Unknown                         & yes & yes & stack     & node \\
 533 Known fun ($\ge$ 1 arg), no fvs         & yes & no  & registers & fast entry (enough args) \\
 534 \ & \ & \ & \                                           & slow entry (otherwise) \\
 535 Known fun ($\ge$ 1 arg), fvs    & yes & yes & registers & node \\
 536 0 arg, no fvs @\r,\s@           & yes & no  & n/a       & direct entry \\
 537 0 arg, no fvs @\u@              & yes & yes & n/a       & node \\
 538 0 arg, fvs @\r,\s@              & yes & yes & n/a       & node \\
 539 0 arg, fvs @\u@                 & yes & yes & n/a       & node\\
 540 \end{tabular}
 541
 542 When black-holing, single-entry closures could also be entered via node
 543 (rather than directly) to catch double-entry.
 544
 545 \begin{code}
 546 data CallMethod
 547   = EnterIt                             -- no args, not a function
 548
 549   | JumpToIt CLabel                     -- no args, not a function, but we
 550                                         -- know what its entry code is
 551
 552   | ReturnIt                            -- it's a function, but we have
 553                                         -- zero args to apply to it, so just
 554                                         -- return it.
 555
 556   | ReturnCon DataCon                   -- It's a data constructor, just return it
 557
 558   | SlowCall                            -- Unknown fun, or known fun with
 559                                         -- too few args.
 560
 561   | DirectEntry                         -- Jump directly, with args in regs
 562         CLabel                          --   The code label
 563         Int                             --   Its arity
 564
 565 getCallMethod :: DynFlags
 566               -> Name           -- Function being applied
 567               -> LambdaFormInfo -- Its info
 568               -> Int            -- Number of available arguments
 569               -> CallMethod
 570
 571 getCallMethod dflags name lf_info n_args
 572   | nodeMustPointToIt lf_info && opt_Parallel
 573   =     -- If we're parallel, then we must always enter via node.
 574         -- The reason is that the closure may have been
 575         -- fetched since we allocated it.
 576     EnterIt
 577
 578 getCallMethod dflags name (LFReEntrant _ arity _ _) n_args
 579   | n_args == 0    = ASSERT( arity /= 0 )
 580                      ReturnIt   -- No args at all
 581   | n_args < arity = SlowCall   -- Not enough args
 582   | otherwise      = DirectEntry (enterIdLabel dflags name) arity
 583
 584 getCallMethod dflags name (LFCon con) n_args
 585   = ASSERT( n_args == 0 )
 586     ReturnCon con
 587
 588 getCallMethod dflags name (LFThunk _ _ updatable std_form_info is_fun) n_args
 589   | is_fun      -- Must always "call" a function-typed
 590   = SlowCall    -- thing, cannot just enter it [in eval/apply, the entry code
 591                 -- is the fast-entry code]
 592
 593   | updatable || opt_DoTickyProfiling  -- to catch double entry
 594               || opt_SMP    -- Always enter via node on SMP, since the
 595                             -- thunk might have been blackholed in the
 596                             -- meantime.
 597   = ASSERT( n_args == 0 ) EnterIt
 598
 599   | otherwise   -- Jump direct to code for single-entry thunks
 600   = ASSERT( n_args == 0 )
 601     JumpToIt (thunkEntryLabel dflags name std_form_info updatable)
 602
 603 getCallMethod dflags name (LFUnknown True) n_args
 604   = SlowCall -- might be a function
 605
 606 getCallMethod dflags name (LFUnknown False) n_args
 607   = ASSERT2 ( n_args == 0, ppr name <+> ppr n_args )
 608     EnterIt -- Not a function
 609
 610 getCallMethod dflags name (LFBlackHole _) n_args
 611   = SlowCall    -- Presumably the black hole has by now
 612                 -- been updated, but we don't know with
 613                 -- what, so we slow call it
 614
 615 getCallMethod dflags name (LFLetNoEscape 0) n_args
 616   = JumpToIt (enterReturnPtLabel (nameUnique name))
 617
 618 getCallMethod dflags name (LFLetNoEscape arity) n_args
 619   | n_args == arity = DirectEntry (enterReturnPtLabel (nameUnique name)) arity
 620   | otherwise = pprPanic "let-no-escape: " (ppr name <+> ppr arity)
 621
 622 blackHoleOnEntry :: ClosureInfo -> Bool
 623 -- Static closures are never themselves black-holed.
 624 -- Updatable ones will be overwritten with a CAFList cell, which points to a
 625 -- black hole;
 626 -- Single-entry ones have no fvs to plug, and we trust they don't form part
 627 -- of a loop.
 628
 629 blackHoleOnEntry ConInfo{} = False
 630 blackHoleOnEntry (ClosureInfo { closureLFInfo = lf_info, closureSMRep = rep })
 631   | isStaticRep rep
 632   = False       -- Never black-hole a static closure
 633
 634   | otherwise
 635   = case lf_info of
 636         LFReEntrant _ _ _ _       -> False
 637         LFLetNoEscape _           -> False
 638         LFThunk _ no_fvs updatable _ _
 639           -> if updatable
 640              then not opt_OmitBlackHoling
 641              else opt_DoTickyProfiling || not no_fvs
 642                   -- the former to catch double entry,
 643                   -- and the latter to plug space-leaks.  KSW/SDM 1999-04.
 644
 645         other -> panic "blackHoleOnEntry"       -- Should never happen
 646
 647 isStandardFormThunk :: LambdaFormInfo -> Bool
 648 isStandardFormThunk (LFThunk _ _ _ (SelectorThunk _) _) = True
 649 isStandardFormThunk (LFThunk _ _ _ (ApThunk _) _)       = True
 650 isStandardFormThunk other_lf_info                       = False
 651
 652 isKnownFun :: LambdaFormInfo -> Bool
 653 isKnownFun (LFReEntrant _ _ _ _) = True
 654 isKnownFun (LFLetNoEscape _) = True
 655 isKnownFun _ = False
 656 \end{code}
 657
 658 -----------------------------------------------------------------------------
 659 SRT-related stuff
 660
 661 \begin{code}
 662 staticClosureNeedsLink :: ClosureInfo -> Bool
 663 -- A static closure needs a link field to aid the GC when traversing
 664 -- the static closure graph.  But it only needs such a field if either
 665 --      a) it has an SRT
 666 --      b) it's a constructor with one or more pointer fields
 667 -- In case (b), the constructor's fields themselves play the role
 668 -- of the SRT.
 669 staticClosureNeedsLink (ClosureInfo { closureSRT = srt })
 670   = needsSRT srt
 671 staticClosureNeedsLink (ConInfo { closureSMRep = sm_rep, closureCon = con })
 672   = not (isNullaryRepDataCon con) && not_nocaf_constr
 673   where
 674     not_nocaf_constr =
 675         case sm_rep of
 676            GenericRep _ _ _ ConstrNoCaf -> False
 677            _other                       -> True
 678 \end{code}
 679
 680 Avoiding generating entries and info tables
 681 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 682 At present, for every function we generate all of the following,
 683 just in case.  But they aren't always all needed, as noted below:
 684
 685 [NB1: all of this applies only to *functions*.  Thunks always
 686 have closure, info table, and entry code.]
 687
 688 [NB2: All are needed if the function is *exported*, just to play safe.]
 689
 690
 691 * Fast-entry code  ALWAYS NEEDED
 692
 693 * Slow-entry code
 694         Needed iff (a) we have any un-saturated calls to the function
 695         OR         (b) the function is passed as an arg
 696         OR         (c) we're in the parallel world and the function has free vars
 697                         [Reason: in parallel world, we always enter functions
 698                         with free vars via the closure.]
 699
 700 * The function closure
 701         Needed iff (a) we have any un-saturated calls to the function
 702         OR         (b) the function is passed as an arg
 703         OR         (c) if the function has free vars (ie not top level)
 704
 705   Why case (a) here?  Because if the arg-satis check fails,
 706   UpdatePAP stuffs a pointer to the function closure in the PAP.
 707   [Could be changed; UpdatePAP could stuff in a code ptr instead,
 708    but doesn't seem worth it.]
 709
 710   [NB: these conditions imply that we might need the closure
 711   without the slow-entry code.  Here's how.
 712
 713         f x y = let g w = ...x..y..w...
 714                 in
 715                 ...(g t)...
 716
 717   Here we need a closure for g which contains x and y,
 718   but since the calls are all saturated we just jump to the
 719   fast entry point for g, with R1 pointing to the closure for g.]
 720
 721
 722 * Standard info table
 723         Needed iff (a) we have any un-saturated calls to the function
 724         OR         (b) the function is passed as an arg
 725         OR         (c) the function has free vars (ie not top level)
 726
 727         NB.  In the sequential world, (c) is only required so that the function closure has
 728         an info table to point to, to keep the storage manager happy.
 729         If (c) alone is true we could fake up an info table by choosing
 730         one of a standard family of info tables, whose entry code just
 731         bombs out.
 732
 733         [NB In the parallel world (c) is needed regardless because
 734         we enter functions with free vars via the closure.]
 735
 736         If (c) is retained, then we'll sometimes generate an info table
 737         (for storage mgr purposes) without slow-entry code.  Then we need
 738         to use an error label in the info table to substitute for the absent
 739         slow entry code.
 740
 741 \begin{code}
 742 staticClosureRequired
 743         :: Name
 744         -> StgBinderInfo
 745         -> LambdaFormInfo
 746         -> Bool
 747 staticClosureRequired binder bndr_info
 748                       (LFReEntrant top_level _ _ _)     -- It's a function
 749   = ASSERT( isTopLevel top_level )
 750         -- Assumption: it's a top-level, no-free-var binding
 751         not (satCallsOnly bndr_info)
 752
 753 staticClosureRequired binder other_binder_info other_lf_info = True
 754 \end{code}
 755
 756 %************************************************************************
 757 %*                                                                      *
 758 \subsection[ClosureInfo-misc-funs]{Misc functions about @ClosureInfo@, etc.}
 759 %*                                                                      *
 760 %************************************************************************
 761
 762 \begin{code}
 763
 764 isStaticClosure :: ClosureInfo -> Bool
 765 isStaticClosure cl_info = isStaticRep (closureSMRep cl_info)
 766
 767 closureUpdReqd :: ClosureInfo -> Bool
 768 closureUpdReqd (ClosureInfo { closureLFInfo = LFThunk _ _ upd _ _ }) = upd
 769 closureUpdReqd (ClosureInfo { closureLFInfo = LFBlackHole _ })     = True
 770         -- Black-hole closures are allocated to receive the results of an
 771         -- alg case with a named default... so they need to be updated.
 772 closureUpdReqd other_closure = False
 773
 774 closureSingleEntry :: ClosureInfo -> Bool
 775 closureSingleEntry (ClosureInfo { closureLFInfo = LFThunk _ _ upd _ _}) = not upd
 776 closureSingleEntry other_closure = False
 777
 778 closureReEntrant :: ClosureInfo -> Bool
 779 closureReEntrant (ClosureInfo { closureLFInfo = LFReEntrant _ _ _ _ }) = True
 780 closureReEntrant other_closure = False
 781
 782 isConstrClosure_maybe :: ClosureInfo -> Maybe DataCon
 783 isConstrClosure_maybe (ConInfo { closureCon = data_con }) = Just data_con
 784 isConstrClosure_maybe _                                   = Nothing
 785
 786 closureFunInfo :: ClosureInfo -> Maybe (Int, ArgDescr)
 787 closureFunInfo (ClosureInfo { closureLFInfo = LFReEntrant _ arity _ arg_desc})
 788   = Just (arity, arg_desc)
 789 closureFunInfo _
 790   = Nothing
 791 \end{code}
 792
 793 \begin{code}
 794 isToplevClosure :: ClosureInfo -> Bool
 795 isToplevClosure (ClosureInfo { closureLFInfo = lf_info })
 796   = case lf_info of
 797       LFReEntrant TopLevel _ _ _ -> True
 798       LFThunk TopLevel _ _ _ _   -> True
 799       other -> False
 800 isToplevClosure _ = False
 801 \end{code}
 802
 803 Label generation.
 804
 805 \begin{code}
 806 infoTableLabelFromCI :: ClosureInfo -> CLabel
 807 infoTableLabelFromCI (ClosureInfo { closureName = name,
 808                                     closureLFInfo = lf_info,
 809                                     closureSMRep = rep })
 810   = case lf_info of
 811         LFBlackHole info -> info
 812
 813         LFThunk _ _ upd_flag (SelectorThunk offset) _ ->
 814                 mkSelectorInfoLabel upd_flag offset
 815
 816         LFThunk _ _ upd_flag (ApThunk arity) _ ->
 817                 mkApInfoTableLabel upd_flag arity
 818
 819         LFThunk{}      -> mkLocalInfoTableLabel name
 820
 821         LFReEntrant _ _ _ _ -> mkLocalInfoTableLabel name
 822
 823         other -> panic "infoTableLabelFromCI"
 824
 825 infoTableLabelFromCI (ConInfo { closureCon = con,
 826                                 closureSMRep = rep,
 827                                 closureDllCon = dll })
 828   | isStaticRep rep = mkStaticInfoTableLabel  name dll
 829   | otherwise       = mkConInfoTableLabel     name dll
 830   where
 831     name = dataConName con
 832
 833 -- ClosureInfo for a closure (as opposed to a constructor) is always local
 834 closureLabelFromCI (ClosureInfo { closureName = nm }) = mkLocalClosureLabel nm
 835 closureLabelFromCI _ = panic "closureLabelFromCI"
 836
 837 -- thunkEntryLabel is a local help function, not exported.  It's used from both
 838 -- entryLabelFromCI and getCallMethod.
 839
 840 thunkEntryLabel dflags thunk_id (ApThunk arity) is_updatable
 841   = enterApLabel is_updatable arity
 842 thunkEntryLabel dflags thunk_id (SelectorThunk offset) upd_flag
 843   = enterSelectorLabel upd_flag offset
 844 thunkEntryLabel dflags thunk_id _ is_updatable
 845   = enterIdLabel dflags thunk_id
 846
 847 enterApLabel is_updatable arity
 848   | tablesNextToCode = mkApInfoTableLabel is_updatable arity
 849   | otherwise        = mkApEntryLabel is_updatable arity
 850
 851 enterSelectorLabel upd_flag offset
 852   | tablesNextToCode = mkSelectorInfoLabel upd_flag offset
 853   | otherwise        = mkSelectorEntryLabel upd_flag offset
 854
 855 enterIdLabel dflags id
 856   | tablesNextToCode = mkInfoTableLabel dflags id
 857   | otherwise        = mkEntryLabel dflags id
 858
 859 enterLocalIdLabel id
 860   | tablesNextToCode = mkLocalInfoTableLabel id
 861   | otherwise        = mkLocalEntryLabel id
 862
 863 enterReturnPtLabel name
 864   | tablesNextToCode = mkReturnInfoLabel name
 865   | otherwise        = mkReturnPtLabel name
 866 \end{code}
 867
 868
 869 We need a black-hole closure info to pass to @allocDynClosure@ when we
 870 want to allocate the black hole on entry to a CAF.  These are the only
 871 ways to build an LFBlackHole, maintaining the invariant that it really
 872 is a black hole and not something else.
 873
 874 \begin{code}
 875 cafBlackHoleClosureInfo (ClosureInfo { closureName = nm,
 876                                        closureType = ty })
 877   = ClosureInfo { closureName   = nm,
 878                   closureLFInfo = LFBlackHole mkCAFBlackHoleInfoTableLabel,
 879                   closureSMRep  = BlackHoleRep,
 880                   closureSRT    = NoC_SRT,
 881                   closureType   = ty,
 882                   closureDescr  = "" }
 883 cafBlackHoleClosureInfo _ = panic "cafBlackHoleClosureInfo"
 884
 885 seCafBlackHoleClosureInfo (ClosureInfo { closureName = nm,
 886                                          closureType = ty })
 887   = ClosureInfo { closureName   = nm,
 888                   closureLFInfo = LFBlackHole mkSECAFBlackHoleInfoTableLabel,
 889                   closureSMRep  = BlackHoleRep,
 890                   closureSRT    = NoC_SRT,
 891                   closureType   = ty,
 892                   closureDescr  = ""  }
 893 seCafBlackHoleClosureInfo _ = panic "seCafBlackHoleClosureInfo"
 894 \end{code}
 895
 896 %************************************************************************
 897 %*                                                                      *
 898 \subsection[ClosureInfo-Profiling-funs]{Misc functions about for profiling info.}
 899 %*                                                                      *
 900 %************************************************************************
 901
 902 Profiling requires two pieces of information to be determined for
 903 each closure's info table --- description and type.
 904
 905 The description is stored directly in the @CClosureInfoTable@ when the
 906 info table is built.
 907
 908 The type is determined from the type information stored with the @Id@
 909 in the closure info using @closureTypeDescr@.
 910
 911 \begin{code}
 912 closureValDescr, closureTypeDescr :: ClosureInfo -> String
 913 closureValDescr (ClosureInfo {closureDescr = descr})
 914   = descr
 915 closureValDescr (ConInfo {closureCon = con})
 916   = occNameUserString (getOccName con)
 917
 918 closureTypeDescr (ClosureInfo { closureType = ty })
 919   = getTyDescription ty
 920 closureTypeDescr (ConInfo { closureCon = data_con })
 921   = occNameUserString (getOccName (dataConTyCon data_con))
 922
 923 getTyDescription :: Type -> String
 924 getTyDescription ty
 925   = case (tcSplitSigmaTy ty) of { (_, _, tau_ty) ->
 926     case tau_ty of
 927       TyVarTy _              -> "*"
 928       AppTy fun _            -> getTyDescription fun
 929       FunTy _ res            -> '-' : '>' : fun_result res
 930       TyConApp tycon _       -> getOccString tycon
 931       NoteTy (FTVNote _) ty  -> getTyDescription ty
 932       NoteTy (SynNote ty1) _ -> getTyDescription ty1
 933       PredTy sty             -> getPredTyDescription sty
 934       ForAllTy _ ty          -> getTyDescription ty
 935     }
 936   where
 937     fun_result (FunTy _ res) = '>' : fun_result res
 938     fun_result other         = getTyDescription other
 939
 940 getPredTyDescription (ClassP cl tys) = getOccString cl
 941 getPredTyDescription (IParam ip ty)  = getOccString (ipNameName ip)
 942 \end{code}
 943
 944