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