2 % (c) The GRASP/AQUA Project, Glasgow University, 1992-1996
4 \section[ClosureInfo]{Data structures which describe closures}
6 Much of the rationale for these things is in the ``details'' part of
10 #include "HsVersions.h"
13 ClosureInfo, LambdaFormInfo, SMRep, -- all abstract
18 mkClosureLFInfo, mkConLFInfo, mkSelectorLFInfo, mkVapLFInfo,
19 mkLFImported, mkLFArgument, mkLFLetNoEscape,
22 closureSize, closureHdrSize,
23 closureNonHdrSize, closureSizeWithoutFixedHdr,
24 closureGoodStuffSize, closurePtrsSize,
25 slopSize, fitsMinUpdSize,
27 layOutDynClosure, layOutDynCon, layOutStaticClosure,
28 layOutStaticNoFVClosure, layOutPhantomClosure,
31 nodeMustPointToIt, getEntryConvention,
32 SYN_IE(FCode), CgInfoDownwards, CgState,
36 staticClosureRequired,
37 slowFunEntryCodeRequired, funInfoTableRequired,
38 stdVapRequired, noUpdVapRequired,
41 closureId, infoTableLabelFromCI, fastLabelFromCI,
44 closureLFInfo, closureSMRep, closureUpdReqd,
45 closureSingleEntry, closureSemiTag, closureType,
46 closureReturnsUnboxedType, getStandardFormThunkInfo,
50 closureKind, closureTypeDescr, -- profiling
52 isStaticClosure, allocProfilingMsg,
56 dataConLiveness -- concurrency
60 #if defined(__GLASGOW_HASKELL__) && __GLASGOW_HASKELL__ <= 201
61 IMPORT_DELOOPER(AbsCLoop) -- here for paranoia-checking
64 import AbsCSyn ( MagicId, node, mkLiveRegsMask,
65 {- GHC 0.29 only -} AbstractC, CAddrMode
70 import Constants ( mIN_UPD_SIZE, mIN_SIZE_NonUpdHeapObject,
71 mAX_SPEC_ALL_PTRS, mAX_SPEC_MIXED_FIELDS,
75 import CgRetConv ( assignRegs, dataReturnConvAlg,
76 DataReturnConvention(..)
78 import CLabel ( CLabel, mkStdEntryLabel, mkFastEntryLabel,
79 mkPhantomInfoTableLabel, mkInfoTableLabel,
80 mkConInfoTableLabel, mkStaticClosureLabel,
81 mkBlackHoleInfoTableLabel, mkVapInfoTableLabel,
82 mkStaticInfoTableLabel, mkStaticConEntryLabel,
83 mkConEntryLabel, mkClosureLabel, mkVapEntryLabel
85 import CmdLineOpts ( opt_SccProfilingOn, opt_ForConcurrent )
86 import HeapOffs ( intOff, addOff, totHdrSize, varHdrSize,
87 SYN_IE(VirtualHeapOffset), HeapOffset
89 import Id ( idType, getIdArity,
91 dataConTag, fIRST_TAG,
92 isDataCon, isNullaryDataCon, dataConTyCon,
93 isTupleCon, SYN_IE(DataCon),
94 GenId{-instance Eq-}, SYN_IE(Id)
96 import IdInfo ( ArityInfo(..) )
97 import Maybes ( maybeToBool )
98 import Name ( getOccString )
99 import Outputable ( PprStyle(..), Outputable(..) )
100 import PprType ( getTyDescription, GenType{-instance Outputable-} )
101 import Pretty --ToDo:rm
102 import PrelInfo ( maybeCharLikeTyCon, maybeIntLikeTyCon )
103 import PrimRep ( getPrimRepSize, separateByPtrFollowness, PrimRep )
104 import SMRep -- all of it
105 import TyCon ( TyCon{-instance NamedThing-} )
106 import Type ( isPrimType, splitFunTyExpandingDictsAndPeeking,
107 mkFunTys, maybeAppSpecDataTyConExpandingDicts,
110 import Util ( isIn, mapAccumL, panic, pprPanic, assertPanic )
113 The ``wrapper'' data type for closure information:
118 Id -- The thing bound to this closure
119 LambdaFormInfo -- info derivable from the *source*
120 SMRep -- representation used by storage manager
123 %************************************************************************
125 \subsection[ClosureInfo-OLD-DOC]{OLD DOCUMENTATION PROBABLY SUPERCEDED BY stg-details}
127 %************************************************************************
129 We can optimise the function-entry code as follows.
132 \item If the ``function'' is not updatable, we can jump directly to its
133 entry code, rather than indirecting via the info pointer in the
134 closure. (For updatable thunks we must go via the closure, in
135 case it has been updated.)
137 \item If the former bullet applies, and the application we are
138 compiling gives the function as many arguments as it needs, we
139 can jump to its fast-entry code. (This only applies if the
140 function has one or more args, because zero-arg closures have
143 \item If the function is a top-level non-constructor or imported, there
144 is no need to make Node point to its closure. In order for
145 this to be right, we need to ensure that:
147 \item If such closures are updatable then they push their
148 static address in the update frame, not Node. Actually
149 we create a black hole and push its address.
151 \item The arg satisfaction check should load Node before jumping to
154 \item Top-level constructor closures need careful handling. If we are to
155 jump direct to the constructor code, we must load Node first, even
156 though they are top-level. But if we go to their ``own''
157 standard-entry code (which loads Node and then jumps to the
158 constructor code) we don't need to load Node.
163 {\em Top level constructors (@mkStaticConEntryInfo@)}
166 x = {y,ys} \ {} Cons {y,ys} -- Std form constructor
169 x-closure: Cons-info-table, y-closure, ys-closure
171 x-entry: Node = x-closure; jump( Cons-entry )
173 x's EntryInfo in its own module:
175 Base-label = Cons -- Not x!!
177 ClosureClass = Constructor
180 So if x is entered, Node will be set up and
181 we'll jump direct to the Cons code.
183 x's EntryInfo in another module: (which may not know that x is a constructor)
185 Base-label = x -- Is x!!
186 NodeMustPoint = False -- All imported things have False
187 ClosureClass = non-committal
190 If x is entered, we'll jump to x-entry, which will set up Node
191 before jumping to the standard Cons code
193 {\em Top level non-constructors (@mkStaticEntryInfo@)}
198 For updatable thunks, x-entry must push an allocated BH in update frame, not Node.
200 For non-zero arity, arg satis check must load Node before jumping to
203 x's EntryInfo in its own module:
206 NodeMustPoint = False
207 ClosureClass = whatever
210 {\em Inner constructors (@mkConEntryInfo@)}
213 Base-label = Cons -- Not x!!
214 NodeMustPoint = True -- If its arity were zero, it would
215 -- have been lifted to top level
216 ClosureClass = Constructor
219 {\em Inner non-constructors (@mkEntryInfo@)}
223 NodeMustPoint = True -- If no free vars, would have been
224 -- lifted to top level
225 ClosureClass = whatever
234 NodeMustPoint = False
235 ClosureClass = whatever
239 THINK: we could omit making Node point to top-level constructors
240 of arity zero; but that might interact nastily with updates.
245 The info we need to import for imported things is:
248 data ImportInfo = UnknownImportInfo
249 | HnfImport Int -- Not updatable, arity given
250 -- Arity can be zero, for (eg) constrs
251 | UpdatableImport -- Must enter via the closure
254 ToDo: move this stuff???
257 mkStaticEntryInfo lbl cl_class
258 = MkEntryInfo lbl False cl_class
260 mkStaticConEntryInfo lbl
261 = MkEntryInfo lbl True ConstructorClosure
263 mkEntryInfo lbl cl_class
264 = MkEntryInfo lbl True cl_class
267 = MkEntryInfo lbl True ConstructorClosure
270 %************************************************************************
272 \subsection[ClosureInfo-datatypes]{Data types for closure information}
274 %************************************************************************
276 %************************************************************************
278 \subsubsection[LambdaFormInfo-datatype]{@LambdaFormInfo@: source-derivable info}
280 %************************************************************************
284 = LFReEntrant -- Reentrant closure; used for PAPs too
285 Bool -- True if top level
287 Bool -- True <=> no fvs
289 | LFCon -- Constructor
290 DataCon -- The constructor (may be specialised)
291 Bool -- True <=> zero arity
294 DataCon -- The tuple constructor (may be specialised)
295 Bool -- True <=> zero arity
297 | LFThunk -- Thunk (zero arity)
298 Bool -- True <=> top level
299 Bool -- True <=> no free vars
300 Bool -- True <=> updatable (i.e., *not* single-entry)
303 | LFArgument -- Used for function arguments. We know nothing about
304 -- this closure. Treat like updatable "LFThunk"...
306 | LFImported -- Used for imported things. We know nothing about this
307 -- closure. Treat like updatable "LFThunk"...
308 -- Imported things which we do know something about use
309 -- one of the other LF constructors (eg LFReEntrant for
312 | LFLetNoEscape -- See LetNoEscape module for precise description of
315 StgLiveVars-- list of variables live in the RHS of the let.
316 -- (ToDo: maybe not used)
318 | LFBlackHole -- Used for the closures allocated to hold the result
319 -- of a CAF. We want the target of the update frame to
320 -- be in the heap, so we make a black hole to hold it.
322 -- This last one is really only for completeness;
323 -- it isn't actually used for anything interesting
324 {- | LFIndirection -}
326 data StandardFormInfo -- Tells whether this thunk has one of a small number
329 = NonStandardThunk -- No, it isn't
333 DataCon -- Constructor
334 Int -- 0-origin offset of ak within the "goods" of constructor
335 -- (Recall that the a1,...,an may be laid out in the heap
336 -- in a non-obvious order.)
338 {- A SelectorThunk is of form
343 and the constructor is from a single-constr type.
344 If we can't convert the heap-offset of the selectee into an Int, e.g.,
345 it's "GEN_VHS+i", we just give up.
351 Bool -- True <=> the function is not top-level, so
352 -- must be stored in the thunk too
354 {- A VapThunk is of form
358 where f is a known function, with arity n
359 So for this thunk we can use the label for f's heap-entry
360 info table (generated when f's defn was dealt with),
361 rather than generating a one-off info table and entry code
366 mkLFArgument = LFArgument
367 mkLFBlackHole = LFBlackHole
368 mkLFLetNoEscape = LFLetNoEscape
370 mkLFImported :: Id -> LambdaFormInfo
372 = case getIdArity id of
373 ArityExactly 0 -> LFThunk True{-top-lev-} True{-no fvs-}
374 True{-updatable-} NonStandardThunk
375 ArityExactly n -> LFReEntrant True n True -- n > 0
376 other -> LFImported -- Not sure of exact arity
379 %************************************************************************
381 \subsection[ClosureInfo-construction]{Functions which build LFInfos}
383 %************************************************************************
385 @mkClosureLFInfo@ figures out the appropriate LFInfo for the closure.
388 mkClosureLFInfo :: Bool -- True of top level
390 -> UpdateFlag -- Update flag
394 mkClosureLFInfo top fvs upd_flag args@(_:_) -- Non-empty args
395 = LFReEntrant top (length args) (null fvs)
397 mkClosureLFInfo top fvs ReEntrant []
398 = LFReEntrant top 0 (null fvs)
400 mkClosureLFInfo top fvs upd_flag []
401 = LFThunk top (null fvs) (isUpdatable upd_flag) NonStandardThunk
403 isUpdatable ReEntrant = False
404 isUpdatable SingleEntry = False
405 isUpdatable Updatable = True
408 @mkConLFInfo@ is similar, for constructors.
411 mkConLFInfo :: DataCon -> LambdaFormInfo
414 = -- the isNullaryDataCon will do this: ASSERT(isDataCon con)
415 (if isTupleCon con then LFTuple else LFCon) con (isNullaryDataCon con)
417 mkSelectorLFInfo scrutinee con offset
418 = LFThunk False False True (SelectorThunk scrutinee con offset)
420 mkVapLFInfo fvs upd_flag fun_id args fun_in_vap
421 = LFThunk False (null fvs) (isUpdatable upd_flag) (VapThunk fun_id args fun_in_vap)
425 %************************************************************************
427 \subsection[ClosureInfo-sizes]{Functions about closure {\em sizes}}
429 %************************************************************************
432 closureSize :: ClosureInfo -> HeapOffset
433 closureSize cl_info@(MkClosureInfo _ _ sm_rep)
434 = totHdrSize sm_rep `addOff` (intOff (closureNonHdrSize cl_info))
436 closureSizeWithoutFixedHdr :: ClosureInfo -> HeapOffset
437 closureSizeWithoutFixedHdr cl_info@(MkClosureInfo _ _ sm_rep)
438 = varHdrSize sm_rep `addOff` (intOff (closureNonHdrSize cl_info))
440 closureHdrSize :: ClosureInfo -> HeapOffset
441 closureHdrSize (MkClosureInfo _ _ sm_rep)
444 closureNonHdrSize :: ClosureInfo -> Int
445 closureNonHdrSize cl_info@(MkClosureInfo _ lf_info sm_rep)
446 = tot_wds + computeSlopSize tot_wds sm_rep (closureUpdReqd cl_info) --ToDo: pass lf_info?
448 tot_wds = closureGoodStuffSize cl_info
450 closureGoodStuffSize :: ClosureInfo -> Int
451 closureGoodStuffSize (MkClosureInfo _ _ sm_rep)
452 = let (ptrs, nonptrs) = sizes_from_SMRep sm_rep
455 closurePtrsSize :: ClosureInfo -> Int
456 closurePtrsSize (MkClosureInfo _ _ sm_rep)
457 = let (ptrs, _) = sizes_from_SMRep sm_rep
461 sizes_from_SMRep (SpecialisedRep k ptrs nonptrs _) = (ptrs, nonptrs)
462 sizes_from_SMRep (GenericRep ptrs nonptrs _) = (ptrs, nonptrs)
463 sizes_from_SMRep (BigTupleRep ptrs) = (ptrs, 0)
464 sizes_from_SMRep (MuTupleRep ptrs) = (ptrs, 0)
465 sizes_from_SMRep (DataRep nonptrs) = (0, nonptrs)
466 sizes_from_SMRep BlackHoleRep = (0, 0)
467 sizes_from_SMRep (StaticRep ptrs nonptrs) = (ptrs, nonptrs)
469 sizes_from_SMRep PhantomRep = panic "sizes_from_SMRep: PhantomRep"
470 sizes_from_SMRep DynamicRep = panic "sizes_from_SMRep: DynamicRep"
475 fitsMinUpdSize :: ClosureInfo -> Bool
476 fitsMinUpdSize (MkClosureInfo _ _ BlackHoleRep) = True
477 fitsMinUpdSize cl_info = isSpecRep (closureSMRep cl_info) && closureNonHdrSize cl_info <= mIN_UPD_SIZE
480 Computing slop size. WARNING: this looks dodgy --- it has deep
481 knowledge of what the storage manager does with the various
487 Updateable closures must be @mIN_UPD_SIZE@.
490 Cons cell requires 2 words
492 Indirections require 1 word
494 Appels collector indirections 2 words
496 THEREFORE: @mIN_UPD_SIZE = 2@.
499 Collectable closures which are allocated in the heap
500 must be @mIN_SIZE_NonUpdHeapObject@.
502 Copying collector forward pointer requires 1 word
504 THEREFORE: @mIN_SIZE_NonUpdHeapObject = 1@
507 @SpecialisedRep@ closures closures may require slop:
510 @ConstantRep@ and @CharLikeRep@ closures always use the address of
511 a static closure. They are never allocated or
512 collected (eg hold forwarding pointer) hence never any slop.
515 @IntLikeRep@ are never updatable.
516 May need slop to be collected (as they will be size 1 or more
517 this probably has no affect)
520 @SpecRep@ may be updateable and will be collectable
523 @StaticRep@ may require slop if updatable. Non-updatable ones are OK.
526 @GenericRep@ closures will always be larger so never require slop.
529 ***** ToDo: keep an eye on this!
533 slopSize cl_info@(MkClosureInfo _ lf_info sm_rep)
534 = computeSlopSize (closureGoodStuffSize cl_info) sm_rep (closureUpdReqd cl_info)
536 computeSlopSize :: Int -> SMRep -> Bool -> Int
538 computeSlopSize tot_wds (SpecialisedRep ConstantRep _ _ _) _
540 computeSlopSize tot_wds (SpecialisedRep CharLikeRep _ _ _) _
543 computeSlopSize tot_wds (SpecialisedRep _ _ _ _) True -- Updatable
544 = max 0 (mIN_UPD_SIZE - tot_wds)
545 computeSlopSize tot_wds (StaticRep _ _) True -- Updatable
546 = max 0 (mIN_UPD_SIZE - tot_wds)
547 computeSlopSize tot_wds BlackHoleRep _ -- Updatable
548 = max 0 (mIN_UPD_SIZE - tot_wds)
550 computeSlopSize tot_wds (SpecialisedRep _ _ _ _) False -- Not updatable
551 = max 0 (mIN_SIZE_NonUpdHeapObject - tot_wds)
553 computeSlopSize tot_wds other_rep _ -- Any other rep
557 %************************************************************************
559 \subsection[layOutDynClosure]{Lay out a dynamic closure}
561 %************************************************************************
564 layOutDynClosure, layOutStaticClosure
565 :: Id -- STG identifier w/ which this closure assoc'd
566 -> (a -> PrimRep) -- function w/ which to be able to get a PrimRep
567 -> [a] -- the "things" being layed out
568 -> LambdaFormInfo -- what sort of closure it is
569 -> (ClosureInfo, -- info about the closure
570 [(a, VirtualHeapOffset)]) -- things w/ offsets pinned on them
572 layOutDynClosure name kind_fn things lf_info
573 = (MkClosureInfo name lf_info sm_rep,
576 (tot_wds, -- #ptr_wds + #nonptr_wds
578 things_w_offsets) = mkVirtHeapOffsets sm_rep kind_fn things
579 sm_rep = chooseDynSMRep lf_info tot_wds ptr_wds
581 layOutStaticClosure name kind_fn things lf_info
582 = (MkClosureInfo name lf_info (StaticRep ptr_wds (tot_wds - ptr_wds)),
585 (tot_wds, -- #ptr_wds + #nonptr_wds
587 things_w_offsets) = mkVirtHeapOffsets (StaticRep bot bot) kind_fn things
588 bot = panic "layoutStaticClosure"
590 layOutStaticNoFVClosure :: Id -> LambdaFormInfo -> ClosureInfo
591 layOutStaticNoFVClosure name lf_info
592 = MkClosureInfo name lf_info (StaticRep ptr_wds nonptr_wds)
594 -- I am very uncertain that this is right - it will show up when testing
595 -- my dynamic loading code. ADR
596 -- (If it's not right, we'll have to grab the kinds of the arguments from
601 layOutPhantomClosure :: Id -> LambdaFormInfo -> ClosureInfo
602 layOutPhantomClosure name lf_info = MkClosureInfo name lf_info PhantomRep
605 A wrapper for when used with data constructors:
607 layOutDynCon :: DataCon
610 -> (ClosureInfo, [(a,VirtualHeapOffset)])
612 layOutDynCon con kind_fn args
613 = ASSERT(isDataCon con)
614 layOutDynClosure con kind_fn args (mkConLFInfo con)
618 %************************************************************************
620 \subsection[SMreps]{Choosing SM reps}
622 %************************************************************************
627 -> Int -> Int -- Tot wds, ptr wds
630 chooseDynSMRep lf_info tot_wds ptr_wds
632 nonptr_wds = tot_wds - ptr_wds
634 updatekind = case lf_info of
635 LFThunk _ _ upd _ -> if upd then SMUpdatable else SMSingleEntry
636 LFBlackHole -> SMUpdatable
639 if (nonptr_wds == 0 && ptr_wds <= mAX_SPEC_ALL_PTRS)
640 || (tot_wds <= mAX_SPEC_MIXED_FIELDS)
641 || (ptr_wds == 0 && nonptr_wds <= mAX_SPEC_ALL_NONPTRS) then
643 spec_kind = case lf_info of
645 (LFTuple _ True) -> ConstantRep
647 (LFTuple _ _) -> SpecRep
649 (LFCon _ True) -> ConstantRep
651 (LFCon con _ ) -> if maybeToBool (maybeCharLikeTyCon tycon) then CharLikeRep
652 else if maybeToBool (maybeIntLikeTyCon tycon) then IntLikeRep
655 tycon = dataConTyCon con
659 SpecialisedRep spec_kind ptr_wds nonptr_wds updatekind
661 GenericRep ptr_wds nonptr_wds updatekind
665 %************************************************************************
667 \subsection[mkVirtHeapOffsets]{Assigning heap offsets in a closure}
669 %************************************************************************
671 @mkVirtHeapOffsets@ (the heap version) always returns boxed things with
672 smaller offsets than the unboxed things, and furthermore, the offsets in
676 mkVirtHeapOffsets :: SMRep -- Representation to be used by storage manager
677 -> (a -> PrimRep) -- To be able to grab kinds;
678 -- w/ a kind, we can find boxedness
679 -> [a] -- Things to make offsets for
680 -> (Int, -- *Total* number of words allocated
681 Int, -- Number of words allocated for *pointers*
682 [(a, VirtualHeapOffset)])
683 -- Things with their offsets from start of object
684 -- in order of increasing offset
686 -- First in list gets lowest offset, which is initial offset + 1.
688 mkVirtHeapOffsets sm_rep kind_fun things
689 = let (ptrs, non_ptrs) = separateByPtrFollowness kind_fun things
690 (wds_of_ptrs, ptrs_w_offsets) = mapAccumL computeOffset 0 ptrs
691 (tot_wds, non_ptrs_w_offsets) = mapAccumL computeOffset wds_of_ptrs non_ptrs
693 (tot_wds, wds_of_ptrs, ptrs_w_offsets ++ non_ptrs_w_offsets)
695 offset_of_first_word = totHdrSize sm_rep
696 computeOffset wds_so_far thing
697 = (wds_so_far + (getPrimRepSize . kind_fun) thing,
698 (thing, (offset_of_first_word `addOff` (intOff wds_so_far)))
702 %************************************************************************
704 \subsection[ClosureInfo-4-questions]{Four major questions about @ClosureInfo@}
706 %************************************************************************
708 Be sure to see the stg-details notes about these...
711 nodeMustPointToIt :: LambdaFormInfo -> FCode Bool
712 nodeMustPointToIt lf_info
714 do_profiling = opt_SccProfilingOn
717 LFReEntrant top arity no_fvs -> returnFC (
718 not no_fvs || -- Certainly if it has fvs we need to point to it
720 not top -- If it is not top level we will point to it
721 -- We can have a \r closure with no_fvs which
722 -- is not top level as special case cgRhsClosure
723 -- has been dissabled in favour of let floating
725 -- For lex_profiling we also access the cost centre for a
726 -- non-inherited function i.e. not top level
727 -- the not top case above ensures this is ok.
730 LFCon _ zero_arity -> returnFC True
731 LFTuple _ zero_arity -> returnFC True
733 -- Strictly speaking, the above two don't need Node to point
734 -- to it if the arity = 0. But this is a *really* unlikely
735 -- situation. If we know it's nil (say) and we are entering
736 -- it. Eg: let x = [] in x then we will certainly have inlined
737 -- x, since nil is a simple atom. So we gain little by not
738 -- having Node point to known zero-arity things. On the other
739 -- hand, we do lose something; Patrick's code for figuring out
740 -- when something has been updated but not entered relies on
741 -- having Node point to the result of an update. SLPJ
744 LFThunk _ no_fvs updatable NonStandardThunk
745 -> returnFC (updatable || not no_fvs || do_profiling)
747 -- For the non-updatable (single-entry case):
749 -- True if has fvs (in which case we need access to them, and we
750 -- should black-hole it)
751 -- or profiling (in which case we need to recover the cost centre
754 LFThunk _ no_fvs updatable some_standard_form_thunk
756 -- Node must point to any standard-form thunk.
759 -- generates a Vap thunk for (f y), and even if y is a global
760 -- variable we must still make Node point to the thunk before entering it
761 -- because that's what the standard-form code expects.
763 LFArgument -> returnFC True
764 LFImported -> returnFC True
765 LFBlackHole -> returnFC True
766 -- BH entry may require Node to point
768 LFLetNoEscape _ _ -> returnFC False
771 The entry conventions depend on the type of closure being entered,
772 whether or not it has free variables, and whether we're running
773 sequentially or in parallel.
775 \begin{tabular}{lllll}
776 Closure Characteristics & Parallel & Node Req'd & Argument Passing & Enter Via \\
777 Unknown & no & yes & stack & node \\
778 Known fun ($\ge$ 1 arg), no fvs & no & no & registers & fast entry (enough args) \\
779 \ & \ & \ & \ & slow entry (otherwise) \\
780 Known fun ($\ge$ 1 arg), fvs & no & yes & registers & fast entry (enough args) \\
781 0 arg, no fvs @\r,\s@ & no & no & n/a & direct entry \\
782 0 arg, no fvs @\u@ & no & yes & n/a & node \\
783 0 arg, fvs @\r,\s@ & no & yes & n/a & direct entry \\
784 0 arg, fvs @\u@ & no & yes & n/a & node \\
786 Unknown & yes & yes & stack & node \\
787 Known fun ($\ge$ 1 arg), no fvs & yes & no & registers & fast entry (enough args) \\
788 \ & \ & \ & \ & slow entry (otherwise) \\
789 Known fun ($\ge$ 1 arg), fvs & yes & yes & registers & node \\
790 0 arg, no fvs @\r,\s@ & yes & no & n/a & direct entry \\
791 0 arg, no fvs @\u@ & yes & yes & n/a & node \\
792 0 arg, fvs @\r,\s@ & yes & yes & n/a & node \\
793 0 arg, fvs @\u@ & yes & yes & n/a & node\\
796 When black-holing, single-entry closures could also be entered via node
797 (rather than directly) to catch double-entry.
801 = ViaNode -- The "normal" convention
803 | StdEntry CLabel -- Jump to this code, with args on stack
804 (Maybe CLabel) -- possibly setting infoptr to this
806 | DirectEntry -- Jump directly to code, with args in regs
807 CLabel -- The code label
809 [MagicId] -- Its register assignments (possibly empty)
811 getEntryConvention :: Id -- Function being applied
812 -> LambdaFormInfo -- Its info
813 -> [PrimRep] -- Available arguments
814 -> FCode EntryConvention
816 getEntryConvention id lf_info arg_kinds
817 = nodeMustPointToIt lf_info `thenFC` \ node_points ->
819 is_concurrent = opt_ForConcurrent
823 if (node_points && is_concurrent) then ViaNode else
827 LFReEntrant _ arity _ ->
828 if arity == 0 || (length arg_kinds) < arity then
829 StdEntry (mkStdEntryLabel id) Nothing
831 DirectEntry (mkFastEntryLabel id arity) arity arg_regs
833 (arg_regs, _) = assignRegs live_regs (take arity arg_kinds)
834 live_regs = if node_points then [node] else []
837 -> let itbl = if zero_arity then
838 mkPhantomInfoTableLabel con
840 mkConInfoTableLabel con
842 --false:ASSERT (null arg_kinds) -- Should have no args (meaning what?)
843 StdEntry (mkConEntryLabel con) (Just itbl)
845 LFTuple tup zero_arity
846 -> --false:ASSERT (null arg_kinds) -- Should have no args (meaning what?)
847 StdEntry (mkConEntryLabel tup) (Just (mkConInfoTableLabel tup))
849 LFThunk _ _ updatable std_form_info
852 else StdEntry (thunkEntryLabel id std_form_info updatable) Nothing
854 LFArgument -> ViaNode
855 LFImported -> ViaNode
856 LFBlackHole -> ViaNode -- Presumably the black hole has by now
857 -- been updated, but we don't know with
858 -- what, so we enter via Node
860 LFLetNoEscape arity _
861 -> ASSERT(arity == length arg_kinds)
862 DirectEntry (mkStdEntryLabel id) arity arg_regs
864 (arg_regs, _) = assignRegs live_regs arg_kinds
865 live_regs = if node_points then [node] else []
868 blackHoleOnEntry :: Bool -- No-black-holing flag
872 -- Static closures are never themselves black-holed.
873 -- Updatable ones will be overwritten with a CAFList cell, which points to a black hole;
874 -- Single-entry ones have no fvs to plug, and we trust they don't form part of a loop.
876 blackHoleOnEntry no_black_holing (MkClosureInfo _ _ (StaticRep _ _)) = False
878 blackHoleOnEntry no_black_holing (MkClosureInfo _ lf_info _)
880 LFReEntrant _ _ _ -> False
881 LFThunk _ no_fvs updatable _
883 then not no_black_holing
885 other -> panic "blackHoleOnEntry" -- Should never happen
887 getStandardFormThunkInfo
889 -> Maybe [StgArg] -- Nothing => not a standard-form thunk
890 -- Just atoms => a standard-form thunk with payload atoms
892 getStandardFormThunkInfo (LFThunk _ _ _ (SelectorThunk scrutinee _ _))
893 = --trace "Selector thunk: missed opportunity to save info table + code"
895 -- Just [StgVarArg scrutinee]
896 -- We can't save the info tbl + code until we have a way to generate
897 -- a fixed family thereof.
899 getStandardFormThunkInfo (LFThunk _ _ _ (VapThunk fun_id args fun_in_payload))
900 | fun_in_payload = Just (StgVarArg fun_id : args)
901 | otherwise = Just args
903 getStandardFormThunkInfo other_lf_info = Nothing
905 maybeSelectorInfo (MkClosureInfo _ (LFThunk _ _ _ (SelectorThunk _ con offset)) _) = Just (con,offset)
906 maybeSelectorInfo _ = Nothing
909 Avoiding generating entries and info tables
910 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
911 At present, for every function we generate all of the following,
912 just in case. But they aren't always all needed, as noted below:
914 [NB1: all of this applies only to *functions*. Thunks always
915 have closure, info table, and entry code.]
917 [NB2: All are needed if the function is *exported*, just to play safe.]
920 * Fast-entry code ALWAYS NEEDED
923 Needed iff (a) we have any un-saturated calls to the function
924 OR (b) the function is passed as an arg
925 OR (c) we're in the parallel world and the function has free vars
926 [Reason: in parallel world, we always enter functions
927 with free vars via the closure.]
929 * The function closure
930 Needed iff (a) we have any un-saturated calls to the function
931 OR (b) the function is passed as an arg
932 OR (c) if the function has free vars (ie not top level)
934 Why case (a) here? Because if the arg-satis check fails,
935 UpdatePAP stuffs a pointer to the function closure in the PAP.
936 [Could be changed; UpdatePAP could stuff in a code ptr instead,
937 but doesn't seem worth it.]
939 [NB: these conditions imply that we might need the closure
940 without the slow-entry code. Here's how.
942 f x y = let g w = ...x..y..w...
946 Here we need a closure for g which contains x and y,
947 but since the calls are all saturated we just jump to the
948 fast entry point for g, with R1 pointing to the closure for g.]
951 * Standard info table
952 Needed iff (a) we have any un-saturated calls to the function
953 OR (b) the function is passed as an arg
954 OR (c) the function has free vars (ie not top level)
956 NB. In the sequential world, (c) is only required so that the function closure has
957 an info table to point to, to keep the storage manager happy.
958 If (c) alone is true we could fake up an info table by choosing
959 one of a standard family of info tables, whose entry code just
962 [NB In the parallel world (c) is needed regardless because
963 we enter functions with free vars via the closure.]
965 If (c) is retained, then we'll sometimes generate an info table
966 (for storage mgr purposes) without slow-entry code. Then we need
967 to use an error label in the info table to substitute for the absent
970 * Standard vap-entry code
971 Standard vap-entry info table
972 Needed iff we have any updatable thunks of the standard vap-entry shape.
974 * Single-update vap-entry code
975 Single-update vap-entry info table
976 Needed iff we have any non-updatable thunks of the
977 standard vap-entry shape.
981 staticClosureRequired
986 staticClosureRequired binder (StgBinderInfo arg_occ unsat_occ _ _ _)
987 (LFReEntrant top_level _ _) -- It's a function
988 = ASSERT( top_level ) -- Assumption: it's a top-level, no-free-var binding
989 arg_occ -- There's an argument occurrence
990 || unsat_occ -- There's an unsaturated call
991 || externallyVisibleId binder
993 staticClosureRequired binder other_binder_info other_lf_info = True
995 slowFunEntryCodeRequired -- Assumption: it's a function, not a thunk.
1000 slowFunEntryCodeRequired binder (StgBinderInfo arg_occ unsat_occ _ _ _) entry_conv
1001 = arg_occ -- There's an argument occurrence
1002 || unsat_occ -- There's an unsaturated call
1003 || externallyVisibleId binder
1004 || (case entry_conv of { DirectEntry _ _ _ -> False; other -> True })
1005 {- The last case deals with the parallel world; a function usually
1006 as a DirectEntry convention, but if it doesn't we must generate slow-entry code -}
1008 slowFunEntryCodeRequired binder NoStgBinderInfo _ = True
1010 funInfoTableRequired
1015 funInfoTableRequired binder (StgBinderInfo arg_occ unsat_occ _ _ _)
1016 (LFReEntrant top_level _ _)
1018 || arg_occ -- There's an argument occurrence
1019 || unsat_occ -- There's an unsaturated call
1020 || externallyVisibleId binder
1022 funInfoTableRequired other_binder_info binder other_lf_info = True
1024 -- We need the vector-apply entry points for a function if
1025 -- there's a vector-apply occurrence in this module
1027 stdVapRequired, noUpdVapRequired :: StgBinderInfo -> Bool
1029 stdVapRequired binder_info
1030 = case binder_info of
1031 StgBinderInfo _ _ std_vap_occ _ _ -> std_vap_occ
1034 noUpdVapRequired binder_info
1035 = case binder_info of
1036 StgBinderInfo _ _ _ no_upd_vap_occ _ -> no_upd_vap_occ
1040 @lfArity@ extracts the arity of a function from its LFInfo
1043 {- Not needed any more
1045 lfArity_maybe (LFReEntrant _ arity _) = Just arity
1047 -- Removed SLPJ March 97. I don't believe these two;
1048 -- LFCon is used for construcor *applications*, not constructors!
1050 -- lfArity_maybe (LFCon con _) = Just (dataConArity con)
1051 -- lfArity_maybe (LFTuple con _) = Just (dataConArity con)
1053 lfArity_maybe other = Nothing
1057 %************************************************************************
1059 \subsection[ClosureInfo-misc-funs]{Misc functions about @ClosureInfo@, etc.}
1061 %************************************************************************
1065 isStaticClosure :: ClosureInfo -> Bool
1066 isStaticClosure (MkClosureInfo _ _ rep) = isStaticRep rep
1068 closureId :: ClosureInfo -> Id
1069 closureId (MkClosureInfo id _ _) = id
1071 closureSMRep :: ClosureInfo -> SMRep
1072 closureSMRep (MkClosureInfo _ _ sm_rep) = sm_rep
1074 closureLFInfo :: ClosureInfo -> LambdaFormInfo
1075 closureLFInfo (MkClosureInfo _ lf_info _) = lf_info
1077 closureUpdReqd :: ClosureInfo -> Bool
1079 closureUpdReqd (MkClosureInfo _ (LFThunk _ _ upd _) _) = upd
1080 closureUpdReqd (MkClosureInfo _ LFBlackHole _) = True
1081 -- Black-hole closures are allocated to receive the results of an
1082 -- alg case with a named default... so they need to be updated.
1083 closureUpdReqd other_closure = False
1085 closureSingleEntry :: ClosureInfo -> Bool
1087 closureSingleEntry (MkClosureInfo _ (LFThunk _ _ upd _) _) = not upd
1088 closureSingleEntry other_closure = False
1091 Note: @closureType@ returns appropriately specialised tycon and
1094 closureType :: ClosureInfo -> Maybe (TyCon, [Type], [Id])
1096 -- First, a turgid special case. When we are generating the
1097 -- standard code and info-table for Vaps (which is done when the function
1098 -- defn is encountered), we don't have a convenient Id to hand whose
1099 -- type is that of (f x y z). So we need to figure out the type
1100 -- rather than take it from the Id. The Id is probably just "f"!
1102 closureType (MkClosureInfo id (LFThunk _ _ _ (VapThunk fun_id args _)) _)
1103 = maybeAppSpecDataTyConExpandingDicts (fun_result_ty (length args) fun_id)
1105 closureType (MkClosureInfo id lf _) = maybeAppSpecDataTyConExpandingDicts (idType id)
1108 @closureReturnsUnboxedType@ is used to check whether a closure, {\em
1109 once it has eaten its arguments}, returns an unboxed type. For
1110 example, the closure for a function:
1114 returns an unboxed type. This is important when dealing with stack
1117 closureReturnsUnboxedType :: ClosureInfo -> Bool
1119 closureReturnsUnboxedType (MkClosureInfo fun_id (LFReEntrant _ arity _) _)
1120 = isPrimType (fun_result_ty arity fun_id)
1122 closureReturnsUnboxedType other_closure = False
1123 -- All non-function closures aren't functions,
1124 -- and hence are boxed, since they are heap alloc'd
1126 -- ToDo: need anything like this in Type.lhs?
1127 fun_result_ty arity id
1129 (arg_tys, res_ty) = splitFunTyExpandingDictsAndPeeking (idType id)
1131 -- ASSERT(arity >= 0 && length arg_tys >= arity)
1132 (if (arity >= 0 && length arg_tys >= arity) then (\x->x) else pprPanic "fun_result_ty:" (hsep [int arity, ppr PprShowAll id, ppr PprDebug (idType id)])) $
1133 mkFunTys (drop arity arg_tys) res_ty
1137 closureSemiTag :: ClosureInfo -> Int
1139 closureSemiTag (MkClosureInfo _ lf_info _)
1141 LFCon data_con _ -> dataConTag data_con - fIRST_TAG
1143 _ -> fromInteger oTHER_TAG
1147 isToplevClosure :: ClosureInfo -> Bool
1149 isToplevClosure (MkClosureInfo _ lf_info _)
1151 LFReEntrant top _ _ -> top
1152 LFThunk top _ _ _ -> top
1153 _ -> panic "ClosureInfo:isToplevClosure"
1159 fastLabelFromCI :: ClosureInfo -> CLabel
1160 fastLabelFromCI (MkClosureInfo id lf_info _)
1161 {- [SLPJ Changed March 97]
1162 (was ok, but is the only call to lfArity,
1163 and the id should guarantee to have the correct arity in it.
1165 = case lfArity_maybe lf_info of
1168 = case getIdArity id of
1169 ArityExactly arity -> mkFastEntryLabel id arity
1170 other -> pprPanic "fastLabelFromCI" (ppr PprDebug id)
1172 infoTableLabelFromCI :: ClosureInfo -> CLabel
1173 infoTableLabelFromCI (MkClosureInfo id lf_info rep)
1175 LFCon con _ -> mkConInfoPtr con rep
1176 LFTuple tup _ -> mkConInfoPtr tup rep
1178 LFBlackHole -> mkBlackHoleInfoTableLabel
1180 LFThunk _ _ upd_flag (VapThunk fun_id args _) -> mkVapInfoTableLabel fun_id upd_flag
1181 -- Use the standard vap info table
1182 -- for the function, rather than a one-off one
1183 -- for this particular closure
1185 {- For now, we generate individual info table and entry code for selector thunks,
1186 so their info table should be labelled in the standard way.
1187 The only special thing about them is that the info table has a field which
1188 tells the GC that it really is a selector.
1190 Later, perhaps, we'll have some standard RTS code for selector-thunk info tables,
1191 in which case this line will spring back to life.
1193 LFThunk _ _ upd_flag (SelectorThunk _ _ offset) -> mkSelectorInfoTableLabel upd_flag offset
1194 -- Ditto for selectors
1197 other -> {-NO: if isStaticRep rep
1198 then mkStaticInfoTableLabel id
1199 else -} mkInfoTableLabel id
1201 mkConInfoPtr :: Id -> SMRep -> CLabel
1202 mkConInfoPtr con rep
1203 = ASSERT(isDataCon con)
1205 PhantomRep -> mkPhantomInfoTableLabel con
1206 StaticRep _ _ -> mkStaticInfoTableLabel con
1207 _ -> mkConInfoTableLabel con
1209 mkConEntryPtr :: Id -> SMRep -> CLabel
1210 mkConEntryPtr con rep
1211 = ASSERT(isDataCon con)
1213 StaticRep _ _ -> mkStaticConEntryLabel con
1214 _ -> mkConEntryLabel con
1217 closureLabelFromCI (MkClosureInfo id _ rep)
1219 = mkStaticClosureLabel id
1220 -- This case catches those pesky static closures for nullary constructors
1222 closureLabelFromCI (MkClosureInfo id _ other_rep) = mkClosureLabel id
1224 entryLabelFromCI :: ClosureInfo -> CLabel
1225 entryLabelFromCI (MkClosureInfo id lf_info rep)
1227 LFThunk _ _ upd_flag std_form_info -> thunkEntryLabel id std_form_info upd_flag
1228 LFCon con _ -> mkConEntryPtr con rep
1229 LFTuple tup _ -> mkConEntryPtr tup rep
1230 other -> mkStdEntryLabel id
1232 -- thunkEntryLabel is a local help function, not exported. It's used from both
1233 -- entryLabelFromCI and getEntryConvention.
1234 -- I don't think it needs to deal with the SelectorThunk case
1235 -- Well, it's falling over now, so I've made it deal with it. (JSM)
1237 thunkEntryLabel thunk_id (VapThunk fun_id args _) is_updatable
1238 = mkVapEntryLabel fun_id is_updatable
1239 thunkEntryLabel thunk_id _ is_updatable
1240 = mkStdEntryLabel thunk_id
1244 allocProfilingMsg :: ClosureInfo -> FAST_STRING
1246 allocProfilingMsg (MkClosureInfo _ lf_info _)
1248 LFReEntrant _ _ _ -> SLIT("ALLOC_FUN")
1249 LFCon _ _ -> SLIT("ALLOC_CON")
1250 LFTuple _ _ -> SLIT("ALLOC_CON")
1251 LFThunk _ _ _ _ -> SLIT("ALLOC_THK")
1252 LFBlackHole -> SLIT("ALLOC_BH")
1253 LFImported -> panic "ALLOC_IMP"
1256 We need a black-hole closure info to pass to @allocDynClosure@ when we
1257 want to allocate the black hole on entry to a CAF.
1260 blackHoleClosureInfo (MkClosureInfo id _ _)
1261 = MkClosureInfo id LFBlackHole BlackHoleRep
1264 The register liveness when returning from a constructor. For
1265 simplicity, we claim just [node] is live for all but PhantomRep's. In
1266 truth, this means that non-constructor info tables also claim node,
1267 but since their liveness information is never used, we don't care.
1270 dataConLiveness (MkClosureInfo con _ PhantomRep)
1271 = case (dataReturnConvAlg con) of
1272 ReturnInRegs regs -> mkLiveRegsMask regs
1273 ReturnInHeap -> panic "dataConLiveness:PhantomRep in heap???"
1275 dataConLiveness _ = mkLiveRegsMask [node]
1278 %************************************************************************
1280 \subsection[ClosureInfo-Profiling-funs]{Misc functions about for profiling info.}
1282 %************************************************************************
1284 Profiling requires three pices of information to be determined for
1285 each closure's info table --- kind, description and type.
1287 The description is stored directly in the @CClosureInfoTable@ when the
1288 info table is built.
1290 The kind is determined from the @LambdaForm@ stored in the closure
1291 info using @closureKind@.
1293 The type is determined from the type information stored with the @Id@
1294 in the closure info using @closureTypeDescr@.
1297 closureKind :: ClosureInfo -> String
1299 closureKind (MkClosureInfo _ lf _)
1301 LFReEntrant _ n _ -> if n > 0 then "FN_K" else "THK_K"
1302 LFCon _ _ -> "CON_K"
1303 LFTuple _ _ -> "CON_K"
1304 LFThunk _ _ _ _ -> "THK_K"
1305 LFBlackHole -> "THK_K" -- consider BHs as thunks for the moment... (ToDo?)
1306 LFImported -> panic "IMP_KIND"
1308 closureTypeDescr :: ClosureInfo -> String
1309 closureTypeDescr (MkClosureInfo id lf _)
1310 = if (isDataCon id) then -- DataCon has function types
1311 getOccString (dataConTyCon id) -- We want the TyCon not the ->
1313 getTyDescription (idType id)