ghc/includes/SMClosures.lh

   1 %************************************************************************
   2 %*                                                                      *
   3 \section[closure-layout]{Closure Layout}
   4 %*                                                                      *
   5 %************************************************************************
   6
   7 We first describes the data structures that are shared by
   8 both the reducer and storage manager and then go on to describe
   9 the interface and its implementation.
  10
  11 The heap consists of a contiguous sequence of closures. Each standard
  12 closure occupies a contiguous sequence of machine words, which is laid
  13 out as follows:
  14
  15 \begin{rawlatex}
  16 \begin{center}
  17 \mbox{\epsffile{closure.ps}}
  18 \end{center}
  19 \end{rawlatex}
  20
  21 \begin{onlyinfo}
  22 \begin{verbatim}
  23 < fixed-hdr-size> < var-hdr-size  >
  24 -----------------+-----------------+---------+-------------+
  25 |info|     |     |     |     |     | ptrs... | nonptrs ... |
  26 -----------------+-----------------+---------+-------------+
  27 <------------- header ------------>
  28 \end{verbatim}
  29 \end{onlyinfo}
  30
  31 The closure starts with a header. Typically, the first word in the
  32 header is the {\em info pointer}, and points to its {\em info-table}.
  33 The rest of the header is used for bookkeeping and depends on the
  34 compiler options used. The fixed header is the same for all closures
  35 while the variable header may depend on the closure type.
  36
  37 Following the header is a block of words each of which contains a
  38 pointer to another closure, followed by a block of words containing
  39 non-pointers. The non-pointers may include an unused portion of
  40 ``slop'' needed to pad the closure.  This is to satisfy any minimum
  41 closure size requirements, primarily for updates in place.  The
  42 distinction between the pointers and non-pointers is that the garbage
  43 collector must follow the former but not the latter.  The pointers are
  44 placed first to mimimize the number of distinct closure shapes that
  45 have to be managed by the garbage collector.
  46
  47 There are a few non-standard closures which do not follow the convention
  48 of placing all pointers first, but they are all administrative closures
  49 which require their own unique garbage collection code anyway (such as
  50 @TSO@'s and @STKO@'s in the threaded world).
  51
  52 The heap grows upwards (towards higher addresses), and closures are
  53 laid out with the info pointer at the lowest address.
  54
  55 During reduction, the heap pointer (@Hp@) points to the last word of
  56 allocated space (and not to the first word of free space) and the heap
  57 limit (@HpLim@) points to the last word of available space.
  58
  59 %************************************************************************
  60 %*                                                                      *
  61 \subsection[closure-size]{The ``Size'' of Closures}
  62 %*                                                                      *
  63 %************************************************************************
  64
  65 When we speak of the ``size'' of a closure, we mean {\em the number of
  66 words in the closure, excluding the fixed header, but including the
  67 variable header, the pointers, non-pointers and slop, if any}.
  68
  69 All closures which may be updated must have a size of at least
  70 @MIN_UPD_SIZE@---currently, this is two, so that they may be directly
  71 overwritten with a small constructor closure, such as a @(:)@ cell or
  72 an indirection on the ``mutables'' list.
  73
  74 %************************************************************************
  75 %*                                                                      *
  76 \subsection[closure-kinds]{Types of Closure}
  77 %*                                                                      *
  78 %************************************************************************
  79
  80 {\em This section is now hopelessly out-of-date}.  This stuff is {\em
  81 important} if you want newcomers to understand GHC.  Am I the only
  82 person who bothers with documentation?! KH
  83
  84 Yes, Kevin, you are.  I've taken a stab at this section.  I think {\em
  85 hopelessly out-of-date} is a bit overboard, especially compared to
  86 some of the other documentation in this system.  If you still don't
  87 like it, you're welcome to update it.
  88
  89 (Umm... Before we update it, would anyone like to go for a pizza?
  90 [WDP 95/03])
  91
  92 We identify several kinds of heap closures. Each type of closure
  93 is treated differently by the storage manager. Different
  94 info-table macros are used to declare the appropriate info-tables used
  95 by the storage manager (see section \ref{info-table-macros}).
  96
  97 Note: it is vitally important that every closure has an appropriate
  98 info-table attached---otherwise chaos results!
  99
 100 \begin{description}
 101
 102 \item[@SPEC@ closures:] These are standard closures which contain
 103 specialized garbage collection code that ``knows'' the @size@/@ptrs@
 104 of the closure. It is only possible to use a specialized info-table if
 105 appropriately specialized garbage collection code is present in the
 106 runtime system. This implies that the compiler needs to know which
 107 @size@/@ptr@ combinations have specialized info-tables. A link-time
 108 error results if the compiler attempts to build a @SPEC@ closure for
 109 an inappropriate @size@/@ptr@ combination.
 110
 111 \item[@GEN@ closures:] These are normal closures which use generic
 112 code for garbage collection. This interprets the @size@/@ptrs@
 113 information stored in the info table. @GEN@ closures can be built for
 114 any @size@/@ptrs@ combination.
 115
 116 \item[@DYN@ closures:] Dynamic closures have the layout information
 117 (@size@/@ptrs@) stored within the variable header of the closure
 118 itself. They are currently only used for partial applications (@PAP@s)
 119 and the ``stable pointer table.''
 120 %partain:\begin{center}
 121 \begin{tabular}{|c|c|c|c|c|c|}
 122 \hline
 123 {\em Fixed Hdr} & {\em Size} & {\em No of ptrs} & {\em Pointers\ldots} & {\em Non-pointers\ldots}       \\ \hline
 124 \end{tabular}
 125 %partain:\end{center}
 126
 127 \item[@TUPLE@ closure:] These are similar to @DYN@ closures but for
 128 closures which contain only pointers.  They are currently used for
 129 primitive arrays of pointers when mutuples and immutuples do not have
 130 to be distinguished during garbage collection.
 131 %partain:\begin{center}
 132 \begin{tabular}{|c|c|c|c|}
 133 \hline
 134 {\em Fixed Hdr} & {\em Size (= No of ptrs + TUPLE\_VHS)} & {\em Pointers\ldots} \\ \hline
 135 \end{tabular}
 136 %partain:\end{center}
 137
 138 \item[@DATA@ closures:] These are also similar to @DYN@ closures but
 139 for closures containing only non-pointers. They are currently used for
 140 primitive arrays of bytes (arbitrary precision integers and arrays of
 141 unboxed values, for example).
 142 %partain:\begin{center}
 143 \begin{tabular}{|c|c|c|}
 144 \hline
 145 {\em Fixed Hdr} & {\em Size (= No of non-ptr words + DATA\_VHS)} & {\em Non-pointers\ldots} \\ \hline
 146 \end{tabular}
 147 %partain:\end{center}
 148
 149 \item[@MUTUPLE@ closures:] These are a variant of the @TUPLE@
 150 closure. They are used when the garbage collection strategy requires a
 151 distinction between mutable and immutable tuples (i.e. when there is a
 152 ``mutables'' list.)  Such an array may be frozen, becoming an @IMMUTUPLE@,
 153 with a different info-table.
 154 %partain:\begin{center}
 155 \begin{tabular}{|c|c|c|c|}
 156 \hline
 157 {\em Fixed Hdr} & {\em Size (= No of ptrs + MUTUPLE\_VHS)} & {\em Pointers\ldots} \\ \hline
 158 \end{tabular}
 159 %partain:\end{center}
 160
 161 \item[@IMMUTUPLE@ closures:] These are frozen @MUTUPLE@ closures.
 162 %mattson:\begin{center}
 163 \begin{tabular}{|c|c|c|c|}
 164 \hline
 165 {\em Fixed Hdr} & {\em Size (= No of ptrs + MUTUPLE\_VHS)} & {\em Pointers\ldots} \\ \hline
 166 \end{tabular}
 167 %mattson:\end{center}
 168
 169 \end{description}
 170
 171 %************************************************************************
 172 %*                                                                      *
 173 \subsection[special-closure-types]{Special types}
 174 %*                                                                      *
 175 %************************************************************************
 176
 177 Special kinds of closures are required for static closures, ``black
 178 holes'', indirections, and in-place updates.
 179
 180 When a ``black hole'' is updated it must be updated with a closure of
 181 size @MIN_UPD_SIZE@ or less.  Updates to some specific closure types
 182 are handled specially, as follows:
 183
 184 \begin{itemize}
 185 \item
 186 if the new closure is of zero arity, then the black hole is replaced by
 187 the corresponding static closure (@CONST@);
 188 \item
 189 if the data type of the new closure is isomorphic to Char (one
 190 constructor, with argument type @Char#@), then the black hole is
 191 replaced by the corresponding member of the static character table
 192 (@CHARLIKE@);
 193 \item
 194 if the data type of the new closure is isomorphic to Int (one
 195 constructor, with argument type @Int#@), and the argument is in the
 196 range of the static small-int table then the black hole is replaced by
 197 the corresponding member of the integer table (@INTLIKE@).
 198 \end{itemize}
 199
 200 The special kinds of closure are:
 201
 202 \begin{description}
 203
 204 \item[@STATIC@ closures:] These are closures which are declared
 205 statically and hence do not reside in the heap. Such closures must not
 206 contain any heap pointers and must not be updated.  @CAF@ closures are
 207 an exception; see below.
 208
 209 \item[@CONST@ closures:] There need be only one (static) closure for a
 210 nullary constructor. These are declared static at compile time and all
 211 references use the static closure (avoiding heap allocation). However,
 212 dynamic heap-allocated ones will nevertheless arise through updates.
 213
 214 \item[@CHARLIKE@ and @INTLIKE@ closures] There is a similar story for
 215 constructors which have a single primitive data field such as @Int#@
 216 or @Char#@. During garbage collection, pointers to these closures can
 217 be replaced with a known @STATIC@ closure if an appropriate one exists.
 218
 219 \item[@BH@ closures:] Black hole closures are used to overwrite
 220 closures currently being evaluated. They inform the garbage collector
 221 that there are no live roots in the closure, thus removing a potential
 222 space leak.  They also become synchronization points in the threaded
 223 world.
 224
 225 \item[@BQ@ closures:] Blocking queue closures are black holes with a
 226 list of blocked threads to be awakened when the black hole is updated.
 227
 228 \item[@IND@ closures:] Indirection closures just point to other
 229 closures. They are introduced when a closure is updated with a closure
 230 that has to be allocated in the heap. The closure to be updated is
 231 {\em indirected} to the new closure.  Indirections are normally
 232 removed during garbage collection.  However, when profiling, it may be
 233 necessary to maintain cost center information in an indirection, so
 234 there are also ``permanent indirections'' which are retained forever.
 235
 236 \item[@CAF@ indirections:] These are statically defined closures which have
 237 been updated with a heap-allocated result.
 238 Initially these are exactly the same as a @STATIC@ closure but with
 239 special entry code. On entering the closure the entry code must:
 240 \begin{itemize}
 241 \item Allocate a black hole in the heap which will be updated with
 242       the result.
 243 \item Overwrite the static closure with a special @CAF@ indirection.
 244
 245 \item Link the static indirection onto the list of updated @CAF@s.
 246 \end{itemize}
 247 The indirection and the link field require the initial @STATIC@
 248 closure to be of at least size @MIN_UPD_SIZE@ (excluding the fixed
 249 header).
 250
 251 @CAF@s are treated as special garbage collection roots.  These roots
 252 are explicitly collected by the garbage collector, since they may
 253 appear in code even if they are not linked with the main heap.  They
 254 consequently represent potentially enormous space-leaks.  A @CAF@
 255 closure retains a fixed location in statically allocated data space.
 256 When updated, the contents of the @CAF@ indirection are changed to
 257 reflect the new closure. @CAF@ indirections require special garbage
 258 collection code.
 259
 260 \item[@FETCHME@ closures:] These are simply references to remote
 261 objects in the parallel system.
 262
 263 \item[@TSO@ closures:] These are ``thread state objects,'' which are
 264 used in the threaded world to maintain the context (STG registers,
 265 PC location when asleep, etc.) for individual threads of computation.
 266
 267 \item[@STKO@ closures:] These are ``stack objects,'' which are
 268 used in the threaded world as the stack for each thread is allocated
 269 from the heap in smallish chunks.  (The stack in the sequential world
 270 is allocated outside of the heap.)
 271
 272 \item[@SPEC_RBH@ and @GEN_RBH@ closures:] These are ``revertible black
 273 holes'' for updatable @SPEC@ (respectively @GEN@) closures.  They are
 274 currently used in the parallel system, but they could also be used for
 275 speculation.  They act like a black hole for thread synchronization,
 276 but they can also be reverted back to the original @SPEC@
 277 (respectively @GEN@) form (so they do introduce a space leak).
 278
 279 \end{description}
 280
 281 %************************************************************************
 282 %*                                                                      *
 283 \subsection[closure-layout-macros]{Closure layout macros}
 284 %*                                                                      *
 285 %************************************************************************
 286
 287 \begin{description}
 288 \item[@FIXED_HS@:]
 289 This is the number of fixed-header words present in every closures.
 290 This includes the info pointer---always the first word---and any
 291 other fixed info.  Because this name occurs so often, @_FHS@ is used as
 292 a shorthand form.
 293
 294 \item[@SET_FIXED_HDR(closure, infolbl, costcentre)@:] Initialize the
 295 fixed-header part of @closure@, putting @infolbl@ into the first word
 296 (where the info-table pointer normally lives). Note that @infolbl@
 297 should be the name of the appropriate info-table. If we are profiling
 298 on a sequential machine, then the cost centre will be placed in the
 299 second word of the fixed header.
 300
 301 \item[@<closure-kind>_VHS@:]
 302 This is the number of words in the variable part of the header.  This
 303 includes the @size@ and/or @ptr@ fields if required for this closure
 304 type, and any words which are reserved for garbage collection.
 305
 306 @SPEC@, @CONST@, @CHARLIKE@, @INTLIKE@, @BH@ and @IND@ do
 307 not have variable header parts, hence no @<closure-kind>_VHS@ macro is
 308 defined for any of these closure types.
 309
 310 \item[@SET_<closure-kind>_HDR(closure,infolbl,costcentre,size,no-of-ptrs)@:]
 311 This is used to initialize the header of a \tr{<closure-kind>} closure.
 312 The fixed header is set by using @SET_FIXED_HDR(closure,infolbl,costcentre)@
 313 macro.
 314
 315 The variable part of the header, if present, uses the
 316 @size@/@ptrs@ fields.  The @size@ should {\em include} any slop
 317 words in the closure.  Any field that is not used may be junk.
 318
 319 The fields actually used depend on the type of the closure (other
 320 fields are ignored):
 321
 322 %partain:\begin{center}
 323 \begin{tabular}{|l|l|} \hline
 324 Closure     & Fields Used                              \\ \hline
 325             &                                          \\
 326 \tr{SPEC}   & size/nonptrs fields ignored              \\
 327 \tr{GEN}    & both fields also ignored                 \\
 328 \tr{DYN}    & both fields used                         \\
 329 \tr{TUPLE}  & size used (ptrs = size - \tr{TUPLE_VHS}) \\
 330 \tr{DATA}   & size used (ptrs = 0)                      \\\hline
 331 \end{tabular}
 332 %partain:\end{center}
 333
 334 \item[@<closure-kind>_HS@:]
 335 Total number of words in the header:
 336
 337 \pl{TOT_HDR = FIXED_HDR + VAR_HDR}.
 338
 339 \item[@<closure-kind>_CLOSURE_SIZE(closure)@:]
 340 Returns the size of a closure of this kind.  This includes any @VAR_HDR@
 341 words and slop---but excludes the @FIXED_HDR@ words.
 342
 343 \item[@<closure-kind>_CLOSURE_NoPTRS(closure)@:]
 344 Returns the number of closure pointer words in a closure of this kind.
 345
 346 \item[@<closure-kind>_CLOSURE_NoNONPTRS(closure)@:]
 347 Returns the number of useful non-pointer words (including slop) in a
 348 closure of this kind.  These follow the pointer words in the closure;
 349 \pl{NoNONPTRS = SIZE - NoPTRS - VAR_HDR}.
 350
 351 \item[@<closure-kind>_CLOSURE_PTR(closure,nth)@:]
 352 Returns the $n$th closure pointer in the closure (starting at 1).
 353
 354 If a loop needs to process all the pointers and non-pointers in a closure then
 355 this macro should be avoided. Instead, have a pointer run over the closure;
 356 for example (from @StgUpdate.lhc@):
 357 \begin{pseudocode}
 358 { P_ p = PapClosure + FIXED_HS + DYN_VHS;
 359   I_ NPtrWords = DYN_CLOSURE_NoPTRS(Node);
 360   I_ NNonPtrWords = DYN_CLOSURE_NoNONPTRS(Node);
 361   for (i=0; i<NPtrWords;    i++) SpA[AREL(i)] = *(p++);
 362   for (i=0; i<NNonPtrWords; i++) SpB[BREL(i)] = *(p++);
 363 }
 364 \end{pseudocode}
 365
 366 \end{description}
 367
 368
 369 %************************************************************************
 370 %*                                                                      *
 371 \subsection[SMinterface.h-implementation]{Interface implementation}
 372 %*                                                                      *
 373 %************************************************************************
 374
 375 This section details the implementation of the storage manager
 376 interface.
 377
 378 NB: Heap objects specific to parallel implementations are not defined
 379 here, but in \tr{Parallel.lh} instead.
 380
 381 %************************************************************************
 382 %*                                                                      *
 383 \subsubsection[common-to-all-closures]{Bits common to all closures (esp. @FIXED_HS@)}
 384 %*                                                                      *
 385 %************************************************************************
 386
 387 The maximum number of pointers in a generic closure (@GEN@, @DYN@,
 388 @TUPLE@, @DATA@) is defined here.
 389
 390 Multi-slurp protection:
 391 \begin{code}
 392 #ifndef SMClosures_H
 393 #define SMClosures_H
 394 \end{code}
 395
 396 Macros to make rep-table names:
 397 If you change either of these, change .../nativeGen/StixInfo.lhs
 398 too---or else!
 399 \begin{code}
 400
 401 #define MK_REP_LBL(n,s,p)       CAT6(n,_,s,_,p,_rtbl)
 402 #define MK_REP_REF(n,s,p)       CAT6(n,_,s,_,p,_rtbl)
 403
 404 \end{code}
 405
 406 At the start of a closure is a fixed header. The info-pointer is
 407 normally the first word of a closure, in the fixed header.  Following
 408 this we may have any of (but occuring in this order): parallel words
 409 (currently a global address); profiling words (currently a cost
 410 centre).  It is possible to change the ordering of fixed header
 411 components by changing the @_HDR_POSN@ macros in the appropriate
 412 files, and the @SET_FIXED_HDR@/@SET_STATIC_FIXED_HDR@ macros below.
 413
 414 The @FIXED_HS@, @SET_FIXED_HDR@ macros and the components
 415 which are used to define them must all be defined consistently.
 416
 417 \begin{code}
 418
 419 #define FIXED_HS (INFO_FIXED_HDR + PAR_FIXED_HDR + PROF_FIXED_HDR + TICKY_FIXED_HDR)
 420
 421 /* NB: this *defines* the intended order for the pieces of
 422    the fixed header.  Care should be taken to ensure that this
 423    is followed below and in the component headers.
 424 */
 425
 426 #define _FHS                    FIXED_HS /* shorthand */
 427
 428 #define SET_FIXED_HDR(closure,infolbl,costcentre)       \
 429         SET_INFO_PTR(closure,infolbl);                  \
 430         SET_GRAN_HDR(closure,ThisPE);                   \
 431         SET_PAR_HDR(closure,LOCAL_GA);                  \
 432         SET_PROF_HDR(closure,costcentre);               \
 433         SET_TICKY_HDR(closure,0)
 434
 435 #define UPD_FIXED_HDR(closure,infolbl,costcentre)       \
 436         SET_INFO_PTR(closure,infolbl);                  \
 437         SET_PROF_HDR(closure,costcentre);               \
 438         SET_TICKY_HDR(closure,1)
 439         /* fiddling SET_PAR_HDR would be a bug (says Patrick) */
 440         /* We set ticky-hdr to 1 because the only place we
 441            use this macro is when we have just done an update
 442            (WDP 96/01)
 443         */
 444
 445 /* These items are comma-separated */
 446
 447 #define SET_STATIC_FIXED_HDR(closure,infolbl,cc_ident)  \
 448         SET_STATIC_INFO_PTR(infolbl)                    \
 449         SET_STATIC_PROCS(closure)                       \
 450         SET_STATIC_PAR_HDR(closure)                     \
 451         SET_STATIC_PROF_HDR(cc_ident)                   \
 452         SET_STATIC_TICKY_HDR()
 453
 454 \end{code}
 455
 456 We define @MIN_UPD_SIZE@ to be the minimum size for updatable
 457 closures. This must be at least 2, to allow for @(:)@ cells and
 458 indirections on the ``mutables'' list. This is defined in
 459 \tr{GhcConstants.lh}.
 460
 461 All updates are performed on closures of this size so @BH@ and @IND@
 462 closures all have this size.
 463
 464 Finally we define the number of words that the storage-manager needs
 465 to reserve in the variable header for mutable closures:
 466
 467 \begin{code}
 468 #if defined(GCap) || defined(GCgn)
 469 # define GC_MUT_REQUIRED
 470 # define GC_MUT_RESERVED_WORDS          1
 471 # define MUT_NOT_LINKED                 1 /* Assuming 1 is not a valid pointer */
 472 # define MUT_LINK(closure)              (((P_)(closure))[FIXED_HS])
 473 # define SET_MUT_RESERVED_WORDS(closure) MUT_LINK(closure) = MUT_NOT_LINKED
 474 # define SET_STATIC_MUT_RESERVED_WORDS  , (W_) MUT_NOT_LINKED
 475 #else
 476 # define GC_MUT_RESERVED_WORDS          0
 477 # define SET_STATIC_MUT_RESERVED_WORDS
 478 #endif
 479 \end{code}
 480
 481
 482 %************************************************************************
 483 %*                                                                      *
 484 \subsubsection[SPEC-closures]{@SPEC@ (specialized) closure macros}
 485 %*                                                                      *
 486 %************************************************************************
 487
 488 @SPEC@ closures have no variable header size---it is always 0.
 489 @SPEC_VHS@ is left undefined, so that if anyone tries to use it,
 490 they will hear about it soon enough (WDP 95/05).
 491
 492 \begin{code}
 493 #define SPEC_HS         (FIXED_HS)
 494
 495 #define SPEC_SIZE(fields) (FIXED_HS + (fields))
 496                         /*notational convenience; in SMscan.lc + elsewhere */
 497
 498 #define SPEC_CLOSURE_PTR(closure, no)   (((P_)(closure))[SPEC_HS + (no) - 1])
 499 #define SPEC_CLOSURE_SIZE(closure)      ((W_)INFO_SIZE(INFO_PTR(closure)))
 500 #define SPEC_CLOSURE_NoPTRS(closure)    ((W_)INFO_NoPTRS(INFO_PTR(closure)))
 501 #define SPEC_CLOSURE_NoNONPTRS(closure) (SPEC_CLOSURE_SIZE(closure)-SPEC_CLOSURE_NoPTRS(closure)/*-SPEC_VHS*/)
 502
 503 #define SET_SPEC_HDR(closure,infolbl,cc,size,ptrs) \
 504                                         SET_FIXED_HDR(closure,infolbl,cc)
 505 \end{code}
 506
 507 %************************************************************************
 508 %*                                                                      *
 509 \subsubsection[ForeignObj-closures]{@ForeignObj@ closure macros}
 510 %*                                                                      *
 511 %************************************************************************
 512
 513 Here's what a ForeignObj looks like:
 514
 515 \begin{verbatim}
 516             <Var  Hdr>
 517 +----------+----------+------+-------------+------+
 518 | Info Ptr | Forward  | Data | FreeRoutine | List |
 519 +----------+----------+------+-------------+------+
 520 \end{verbatim}
 521
 522 @List@ is a pointer to the next ForeignObj in the list of all
 523 ForeignObjs.  Note that it is essential that the garbage collector {\em
 524 not\/} follow this link but that the link must get updated with the
 525 new address.
 526
 527 The optional @Forward@ field is used by copying collectors to insert
 528 the forwarding pointer into.  (If we overwrite the @Data@ part, we
 529 don't know which ForeignObj has just died; if we overwrite the @List@ part,
 530 we can't traverse the list of all ForeignObjs.)
 531
 532 The @FreeRoutine@ is a reference to the finalisation routine to call
 533 when the @ForeignObj@ becomes garbage -- SOF 4/96
 534
 535 [8/97 -- from the p.o.v. of the NCG, it is very convenient if
 536 the offset to the data field is constant and not dependent on
 537 what scheme of GC being used by the RTS. So much so, that I'm
 538 uniformly adding a VHS of 1. For schemes using a copying
 539 collector, that's the forward field. For the one-space collector,
 540 it's an unused word.
 541
 542 If the change is reverted back to what it was (conditional on
 543 the setting of _INFO_COPYING), then MachMisc.foHS
 544 needs to be changed accordingly.                -- SOF]
 545
 546 \begin{code}
 547 #if !defined(PAR)
 548
 549 /* See comment above */
 550 #  define ForeignObj_VHS                        1
 551 /*
 552 # if defined(_INFO_COPYING)
 553 #  define ForeignObj_VHS                        1
 554 # else
 555 #  define ForeignObj_VHS                        0
 556 # endif
 557 */
 558
 559 # define ForeignObj_HS                  (FIXED_HS + ForeignObj_VHS)
 560 # define ForeignObj_SIZE                (ForeignObj_VHS + 3)
 561
 562 # define ForeignObj_CLOSURE_NoPTRS(closure)     0
 563 # define ForeignObj_CLOSURE_DATA(closure)       (((StgForeignObj *)(closure))[ForeignObj_HS + 0])
 564 # define ForeignObj_CLOSURE_FINALISER(closure)  (((StgForeignObj *)(closure))[ForeignObj_HS + 1])
 565 # define ForeignObj_CLOSURE_LINK(closure)       (((StgPtrPtr) (closure))[ForeignObj_HS + 2])
 566
 567 # define SET_ForeignObj_HDR(closure,infolbl,cc,size,ptrs) \
 568                                         SET_FIXED_HDR(closure,infolbl,cc)
 569 \end{code}
 570
 571 And to check that a Foreign ptr closure is valid
 572
 573 \begin{code}
 574 EXTDATA_RO(ForeignObj_info);
 575
 576 # if defined(DEBUG)
 577
 578 #  define CHECK_ForeignObj_CLOSURE( closure ) \
 579 do {                                       \
 580   CHECK_ForeignObj_InfoTable( closure );    \
 581 } while (0)
 582
 583 #  define CHECK_ForeignObj_InfoTable( closure ) \
 584   ASSERT( (*((PP_)(closure))) == ForeignObj_info )
 585
 586 extern void Validate_ForeignObjList( P_ MPlist );
 587 #  define VALIDATE_ForeignObjList( mplist ) Validate_ForeignObjList( mplist )
 588
 589 # else /* !DEBUG */
 590
 591 #  define CHECK_ForeignObj_CLOSURE( closure ) /* nothing */
 592 #  define VALIDATE_ForeignObjList( mplist ) /* nothing */
 593
 594 # endif /* !DEBUG */
 595 #endif /* !PAR */
 596 \end{code}
 597
 598 %************************************************************************
 599 %*                                                                      *
 600 \subsubsection[SP-table-closures]{@SPTable@ Stable Pointer Table closure macros}
 601 %*                                                                      *
 602 %************************************************************************
 603
 604
 605 A stable pointer is a name for a Haskell object which can be passed to
 606 the external world.  It is ``stable'' in the sense that the name does
 607 not change when the Haskell garbage collector runs---in contrast to
 608 the address of the object which may well change.
 609
 610 The stable pointer type is parameterized by the type of the thing
 611 which is named.
 612
 613 \begin{verbatim}
 614 type StablePtr# a
 615 \end{verbatim}
 616
 617 A stable pointer is represented by an index into the (unique,
 618 heap-allocated) @StablePointerTable@.  The Haskell garbage collector
 619 treats the @StablePointerTable@ as a source of roots for GC.
 620
 621 In order to provide efficient access to stable pointers and to be able
 622 to cope with any number of stable pointers ($0 \ldots 100000$), the
 623 table of stable pointers is an array stored on the heap and can grow
 624 when it overflows.  (Since we cannot compact the table by moving
 625 stable pointers about, it seems unlikely that a half-empty table can
 626 be reduced in size---this could be fixed if neccessary by using a
 627 hash table of some sort.)
 628
 629 In general a stable pointer table closure looks like this:
 630
 631 \begin{verbatim}
 632 <------------header--------------->
 633 +------+------------+------+-------+---+---+---+-----+-----+--+--+--+----+
 634 | Info | GCReserved | Size | NPtrs |SP0|SP1|...|SPn-1| Top |s0|s1|..|sn-1|
 635 +------+------------+------+-------+---+---+---+-----+-----+--+--+--+----+
 636 \end{verbatim}
 637
 638 The fields are:
 639 \begin{description}
 640
 641 \item[@Size@:] number of words excluding fixed header ($= @DYN_VHS@ + @NPtrs@ + 1 + @NPtrs@$)
 642
 643 \item[@NPtrs@:] number of (stable) pointers.
 644
 645 \item[@SPi@:] ``unstable'' pointer to a closure.  This is the pointer
 646 that gets updated when the garbage collector moves an object we have a
 647 stable pointer to.  If the pointer is not in use, it points to a
 648 static closure.
 649
 650 \item[@si@:] entry in a stack of unused pointers.  Entries in
 651 use will contain a number in the range $0\ldots n-1$.
 652
 653 \item[@Top@] is the index of the first element above the top of the stack.
 654
 655 \end{description}
 656
 657 For example, with $n = 4$ and pointers @0@ and @3@ in use (pointing to
 658 @p1@ and @p2@ respectively), the table might look like this:
 659
 660 \begin{verbatim}
 661 +------+----+---+----+---+---+----+---+---+---+---+---+
 662 | Info | 11 | 4 | p1 | x | x | p2 | 2 | 2 | 1 | ? | ? |
 663 +------+----+---+----+---+---+----+---+---+---+---+---+
 664                                    +-----------^
 665 \end{verbatim}
 666
 667 From the above description, it should be clear that this is just a
 668 special case of a @DYN@ closure.  However, a few macros to access the
 669 various fields would be jolly useful.
 670
 671 Nota Bene: one might think that since the table is mutable, we'd need
 672 to treat it a bit more like a @MUTUPLE@.  This isn't necessary because
 673 we treat the stable pointer table as a root.
 674
 675 \begin{code}
 676 #if !defined(PAR)
 677 \end{code}
 678
 679 \begin{code}
 680 # define SPT_SIZE(closure)         DYN_CLOSURE_SIZE(closure)
 681 # define SPT_NoPTRS(closure)       DYN_CLOSURE_NoPTRS(closure)
 682 # define SPT_TOP(closure)          (((I_ *) closure)[DYN_HS + SPT_NoPTRS(closure)])
 683 # define SPT_SPTR(closure,index)   (((PP_) closure)[DYN_HS + index])
 684 # define SPT_FREE(closure,index)   (((I_ *) closure)[DYN_HS + SPT_NoPTRS(closure) + 1 + index])
 685 \end{code}
 686
 687 And to implement the stack:
 688
 689 \begin{code}
 690 # define SPT_FULL(closure)         (SPT_TOP(closure) == SPT_NoPTRS(closure))
 691 # define SPT_EMPTY(closure)        (SPT_TOP(closure) == 0)
 692
 693 # define SPT_PUSH(closure,free)    SPT_FREE(closure,SPT_TOP(closure)++) = free
 694 # define SPT_POP(closure)          SPT_FREE(closure,--SPT_TOP(closure))
 695 \end{code}
 696
 697 And to check that an SPT_Closure is what it's supposed to be, we check
 698 that the size and number of pointers match up and we check that the
 699 free list and sptr areas are consistent.
 700
 701 Note that we cannot always check the info table since we might be
 702 halfway through garbage collection when we call these (eg in
 703 @freeStablePointer@.
 704
 705 \begin{code}
 706 # if defined(DEBUG)
 707
 708 #  define CHECK_SPT_CLOSURE( closure ) \
 709 do {                                 \
 710   CHECK_SPT_InfoTable( closure );    \
 711   CHECK_SPT_Size( closure );         \
 712   CHECK_SPT_Contents( closure );     \
 713 } while (0)
 714
 715 EXTDATA_RO(StablePointerTable_info);
 716 EXTDATA_RO(EmptyStablePointerTable_info);
 717 EXTDATA(EmptySPTable_closure);
 718 int ValidateSPTable PROTO(( P_ SPTable ));
 719
 720 #  define CHECK_SPT_InfoTable( closure ) \
 721   ASSERT( (*((PP_) (closure)) == EmptyStablePointerTable_info && (closure == EmptySPTable_closure) ) || \
 722           (*((PP_) (closure)) == StablePointerTable_info) )
 723
 724 #  define CHECK_SPT_Size( closure ) \
 725   ASSERT( SPT_SIZE( closure ) == DYN_VHS + 2 * SPT_NoPTRS( closure ) + 1 )
 726
 727 #  define CHECK_SPT_Contents( closure ) \
 728   ASSERT( ValidateSPTable( closure ) == 0 )
 729
 730 # else
 731
 732 #  define CHECK_SPT_InfoTable( closure ) /* nothing */
 733 #  define CHECK_SPT_Contents( closure ) /* nothing */
 734 #  define CHECK_SPT_Size( closure ) /* nothing */
 735 #  define CHECK_SPT_CLOSURE( closure ) /* nothing */
 736
 737 # endif /* DEBUG */
 738 #endif  /* !PAR */
 739 \end{code}
 740
 741 %************************************************************************
 742 %*                                                                      *
 743 \subsubsection[GEN-closures]{@GEN@ (generic) closure macros}
 744 %*                                                                      *
 745 %************************************************************************
 746
 747 \begin{code}
 748 #define GEN_VHS         0
 749 #define GEN_HS          (FIXED_HS + GEN_VHS)
 750
 751 #define GEN_N_VHS       GEN_VHS
 752 #define GEN_N_HS        GEN_HS
 753
 754 #define GEN_S_VHS       GEN_VHS
 755 #define GEN_S_HS        GEN_HS
 756
 757 #define GEN_U_VHS       GEN_VHS
 758 #define GEN_U_HS        GEN_HS
 759
 760 #define GEN_CLOSURE_SIZE(closure)       GEN_INFO_SIZE(INFO_PTR(closure))
 761 #define GEN_CLOSURE_NoPTRS(closure)     GEN_INFO_NoPTRS(INFO_PTR(closure))
 762
 763 #define GEN_CLOSURE_NoNONPTRS(closure)  (GEN_CLOSURE_SIZE(closure) - GEN_CLOSURE_NoPTRS(closure) - GEN_VHS)
 764 #define GEN_CLOSURE_PTR(closure, no)    (((P_)(closure))[GEN_HS + (no) - 1])
 765
 766 #define SET_GEN_HDR(closure,infolbl,cc,size,ptrs) SET_FIXED_HDR(closure,infolbl,cc)
 767 \end{code}
 768
 769 %************************************************************************
 770 %*                                                                      *
 771 \subsubsection[DYN-closures]{@DYN@ (dynamic) closure macros}
 772 %*                                                                      *
 773 %************************************************************************
 774
 775 For dynamic closures (with both pointers and data stored within the closure).
 776
 777 \begin{code}
 778 #define DYN_VHS                 2
 779 #define DYN_HS                  (FIXED_HS + DYN_VHS)
 780
 781 #define DYN_CLOSURE_SIZE(closure)       (((P_)(closure))[FIXED_HS])
 782 #define DYN_CLOSURE_NoPTRS(closure)     (((P_)(closure))[FIXED_HS + 1])
 783
 784 #define DYN_CLOSURE_NoNONPTRS(closure)  (DYN_CLOSURE_SIZE(closure) - DYN_CLOSURE_NoPTRS(closure) - DYN_VHS)
 785 #define DYN_CLOSURE_PTR(closure, no)    (((P_)(closure))[DYN_HS + (no) - 1])
 786
 787 #define SET_DYN_HDR(closure,infolbl,cc,size,ptrs) \
 788         { SET_FIXED_HDR(closure,infolbl,cc);    \
 789           DYN_CLOSURE_NoPTRS(closure) = (W_)(ptrs); \
 790           DYN_CLOSURE_SIZE(closure) = (W_)(size); }
 791 \end{code}
 792
 793 %************************************************************************
 794 %*                                                                      *
 795 \subsubsection[TUPLE-closures]{@TUPLE@ (big purely-pointer) closure macros}
 796 %*                                                                      *
 797 %************************************************************************
 798
 799 For tuple closures (which contain only pointers after the variable header).
 800
 801 \begin{code}
 802 #define TUPLE_VHS               1
 803 #define TUPLE_HS                (FIXED_HS + TUPLE_VHS)
 804
 805 #define TUPLE_CLOSURE_SIZE(closure)     (((P_)(closure))[FIXED_HS])
 806
 807 #define TUPLE_CLOSURE_NoPTRS(closure)   (TUPLE_CLOSURE_SIZE(closure) - TUPLE_VHS)
 808 #define TUPLE_CLOSURE_NoNONPTRS(closure) 0L
 809 #define TUPLE_CLOSURE_PTR(closure, no)  (((P_)(closure))[TUPLE_HS + (no) - 1])
 810
 811 #define SET_TUPLE_HDR(closure,infolbl,cc,size,ptrs) \
 812         { SET_FIXED_HDR(closure,infolbl,cc);    \
 813           TUPLE_CLOSURE_SIZE(closure) = (W_)(size); }
 814 \end{code}
 815
 816 %************************************************************************
 817 %*                                                                      *
 818 \subsubsection[DATA-closures]{@DATA@ (big purely non-pointer) closure macros}
 819 %*                                                                      *
 820 %************************************************************************
 821
 822 For data closures (which contain only raw data (no pointers) after the
 823 variable header):
 824
 825 \begin{code}
 826 #define DATA_VHS        1
 827 #define DATA_HS         (FIXED_HS + DATA_VHS)
 828
 829 #define DATA_CLOSURE_SIZE(closure)      (((P_)(closure))[FIXED_HS])
 830
 831 #define DATA_CLOSURE_NoPTRS(closure)    ((I_)0)
 832 #define DATA_CLOSURE_NoNONPTRS(closure) (DATA_CLOSURE_SIZE(closure) - DATA_VHS)
 833
 834 #define SET_DATA_HDR(closure,infolbl,cc,size,ptrs)      \
 835         { SET_FIXED_HDR(closure,infolbl,cc);            \
 836           DATA_CLOSURE_SIZE(closure) = (W_)(size); }
 837 \end{code}
 838
 839
 840 %************************************************************************
 841 %*                                                                      *
 842 \subsubsection[MUTUPLE-closures]{@MUTUPLE@ (mutable pointer) closure macros}
 843 %*                                                                      *
 844 %************************************************************************
 845
 846 Mutable closures of pointers have to be treated specially for the
 847 benefit of generational garbage collection schemes. If the garbage
 848 collection scheme does not need to treat them specially
 849 @GC_MUT_REQUIRED@ is undefined and the closures are defined
 850 identical to @TUPLE@ closures.
 851
 852 \begin{code}
 853
 854 #if defined(GC_MUT_REQUIRED)
 855
 856 # define MUTUPLE_VHS            (1 + GC_MUT_RESERVED_WORDS)
 857 # define MUTUPLE_HS             (FIXED_HS + MUTUPLE_VHS)
 858
 859 # define MUTUPLE_CLOSURE_SIZE(closure)    (((P_)(closure))[FIXED_HS + GC_MUT_RESERVED_WORDS])
 860
 861 # define MUTUPLE_CLOSURE_NoPTRS(closure)    (MUTUPLE_CLOSURE_SIZE(closure) - MUTUPLE_VHS)
 862 # define MUTUPLE_CLOSURE_NoNONPTRS(closure) 0L
 863 # define MUTUPLE_CLOSURE_PTR(closure, no)   (((P_)(closure))[MUTUPLE_HS + (no) - 1])
 864
 865 # define SET_MUTUPLE_HDR(closure,infolbl,cc,size,ptrs) \
 866         { SET_FIXED_HDR(closure,infolbl,cc);    \
 867           SET_MUT_RESERVED_WORDS(closure);      \
 868           MUTUPLE_CLOSURE_SIZE(closure) = (W_)(size); }
 869
 870 #else   /* ! GC_MUT_REQUIRED---define as TUPLE closure */
 871
 872 # define MUTUPLE_VHS TUPLE_VHS
 873 # define MUTUPLE_HS  TUPLE_HS
 874 # define MUTUPLE_CLOSURE_SIZE(closure)      TUPLE_CLOSURE_SIZE(closure)
 875 # define MUTUPLE_CLOSURE_NoPTRS(closure)    TUPLE_CLOSURE_NoPTRS(closure)
 876 # define MUTUPLE_CLOSURE_NoNONPTRS(closure) TUPLE_CLOSURE_NoNONPTRS(closure)
 877 # define MUTUPLE_CLOSURE_PTR(closure, no)   TUPLE_CLOSURE_PTR(closure, no)
 878 # define SET_MUTUPLE_HDR(closure,infolbl,cc,size,ptrs) \
 879          SET_TUPLE_HDR(closure,infolbl,cc,size,ptrs)
 880 #endif
 881
 882 \end{code}
 883
 884 %************************************************************************
 885 %*                                                                      *
 886 \subsubsection[STATIC-closures]{@STATIC@ closure macros}
 887 %*                                                                      *
 888 %************************************************************************
 889
 890 Static closures are those that are allocated in text/data space at
 891 compile time (i.e., not in dynamic heap).  The odd-looking macro
 892 @SET_STATIC_HDR@ depends on the compiler to cooperate---it must drop
 893 in the closure free-variable words and the concluding @};@!  Also note
 894 that the info-table label is a ``base'' label.
 895
 896 @SET_STATIC_HDR@ is for SPEC-layout closures.
 897
 898 \begin{code}
 899 #define STATIC_VHS              0
 900 #define STATIC_HS               (FIXED_HS)
 901
 902 #define STATIC_CLOSURE_SIZE(closure)            (STATIC_INFO_SIZE(INFO_PTR(closure)))
 903 #define STATIC_CLOSURE_NoPTRS(closure)          (STATIC_INFO_NoPTRS(INFO_PTR(closure)))
 904 #define STATIC_CLOSURE_NoNONPTRS(closure)       (STATIC_CLOSURE_SIZE(closure)-STATIC_CLOSURE_NoPTRS(closure)-STATIC_VHS)
 905
 906 #define SET_STATIC_HDR(closure,infolbl,cc,closure_localness,info_localness_macro) \
 907         info_localness_macro(infolbl); \
 908         closure_localness \
 909         W_ closure[] = {SET_STATIC_FIXED_HDR(&closure[0],infolbl,cc)
 910 \end{code}
 911
 912 %************************************************************************
 913 %*                                                                      *
 914 \subsubsection[IND-closures]{@IND@ (indirection) closure macros}
 915 %*                                                                      *
 916 %************************************************************************
 917
 918 Indirections are introduced when closures are updated. They are only
 919 built by the update macros and the special @CAF@ entry macro in
 920 @SMupdate.lh@.
 921
 922 Indirections also have a fixed size of @IND_CLOSURE_SIZE(closure)@.
 923
 924 Both for @CAF@s and for normal nodes in Appel's collector we have to
 925 be able to identify and link together lists of indirections which are
 926 treated specially by the garbage collector. For this purpose we use
 927 the @MUT_LINK@ field.
 928
 929 @CAF@s (which look like indirections) need to be linked regardless of
 930 whether or not we're doing generational collection, so we don't rely
 931 on @MUT_LINK@ being defined.
 932
 933 \begin{code}
 934 #define IND_VHS                 (1)
 935 #define IND_HS                  (FIXED_HS + IND_VHS)
 936
 937 #define IND_CLOSURE_SIZE(closure) (MIN_UPD_SIZE)
 938 #define IND_CLOSURE_NoPTRS(closure) 1
 939 #define IND_CLOSURE_NoNONPTRS(closure) \
 940             (IND_CLOSURE_SIZE(closure)-IND_CLOSURE_NoPTRS(closure)-IND_VHS)
 941 \end{code}
 942
 943 Indirections must store a pointer to the closure which is the target
 944 of the indirection:
 945 \begin{code}
 946 #define IND_CLOSURE_PTR(closure)  (((P_)(closure))[IND_HS])
 947 #define IND_CLOSURE_LINK(closure) (((P_)(closure))[FIXED_HS])
 948 \end{code}
 949
 950 When we are profiling, we occasionally use ``permanent indirections''
 951 to store cost centres associated in some way with PAPs.  Don't ask me
 952 why.  For now, a permanent indirection must have the same shape as a
 953 regular indirection.  The only difference is that it is, well,
 954 permanent.  That is to say, it is never short-circuited.  (What is the
 955 point, anyway?)
 956
 957 Presumably, such objects could shrink as they moved into the old
 958 generation, but then their header size would change as well (the word
 959 that they get to lose is the VHS word of a standard indirection), and
 960 I just don't feel up to it today.  --JSM.
 961
 962 \begin{code}
 963 #if defined(PROFILING) || defined(TICKY_TICKY)
 964
 965 #define PERM_IND_CLOSURE_PTR(closure,dummy) IND_CLOSURE_PTR(closure)
 966     /* really *must* be the same as IND_CLOSURE_PTR; it is
 967        merely a "two-argument" variant, to fit in with the
 968        bizarre goings-on in SMmark.lhc and friends. WDP 95/12
 969     */
 970 #endif
 971 \end{code}
 972
 973 %************************************************************************
 974 %*                                                                      *
 975 \subsubsection[BH-closures]{@BH@ (black hole) closure macros}
 976 %*                                                                      *
 977 %************************************************************************
 978
 979 There are two flavours of black holes; one for updatable closures
 980 (size @MIN_UPD_SIZE@) and one for single entry closures (size
 981 @MIN_NONUPD_SIZE@).  Note that single-entry black holes can never
 982 become blocking queues, because that would imply multiple entries
 983 to the closure.
 984
 985 Black holes are introduced either on entering a closure or when
 986 performing garbage collection (see section
 987 \ref{black-hole-overwrite}). They indicate that the pointers within
 988 the closure are no longer needed.
 989
 990 The compiler will also allocate an updatable black hole on entering a
 991 @CAF@.
 992
 993 \begin{code}
 994 #define BH_HS           (FIXED_HS)
 995 #define BH_VHS          0L
 996
 997 #define BH_U_SIZE       MIN_UPD_SIZE
 998 #define BH_N_SIZE       MIN_NONUPD_SIZE
 999
1000 #define BH_CLOSURE_SIZE(closure)        ((W_)INFO_SIZE(INFO_PTR(closure)))
1001 #define BH_CLOSURE_NoPTRS(closure)      0L
1002 #define BH_CLOSURE_NoNONPTRS(closure)   (BH_CLOSURE_SIZE(closure)-BH_CLOSURE_NoPTRS(closure)-BH_VHS)
1003
1004 #define SET_BH_HDR(closure,infolbl,cc,size,ptrs) \
1005         SET_FIXED_HDR(closure,infolbl,cc)
1006         /* most args aren't used, but are required for SET_*_HDR uniformity */
1007 \end{code}
1008
1009 %************************************************************************
1010 %*                                                                      *
1011 \subsubsection[RBH-closures]{@RBH@ (revertible black hole) closure macros}
1012 %*                                                                      *
1013 %************************************************************************
1014
1015 There are two kinds of revertible black holes, produced from GEN or
1016 SPEC closures, respectively.  There's no @SET_RBH_HDR@ macro -- use
1017 @convertToRBH@ instead!!
1018
1019 Note that the NoPTRS and NoNONPTRS macros refer to the *original* closure.
1020
1021 \begin{code}
1022 #define SPEC_RBH_VHS                            (1L)
1023 #define SPEC_RBH_HS                             (FIXED_HS + SPEC_RBH_VHS)
1024
1025 #define SPEC_RBH_CLOSURE_PTR(closure, no)       (((P_)(closure))[SPEC_RBH_HS + (no) - 1])
1026 #define SPEC_RBH_CLOSURE_SIZE(closure)          ((W_)INFO_SIZE(REVERT_INFOPTR(INFO_PTR(closure))))
1027 #define SPEC_RBH_CLOSURE_NoPTRS(closure)        ((W_)INFO_NoPTRS(REVERT_INFOPTR(INFO_PTR(closure))))
1028 #define SPEC_RBH_CLOSURE_NoNONPTRS(closure)     (SPEC_RBH_CLOSURE_SIZE(closure)-SPEC_RBH_CLOSURE_NoPTRS(closure))
1029
1030 #define SPEC_RBH_BQ_LOCN                        (SPEC_RBH_HS)
1031 #define SPEC_RBH_BQ(closure)                    (((P_)(closure))[SPEC_RBH_BQ_LOCN])
1032
1033 #define GEN_RBH_VHS                             (1L)
1034 #define GEN_RBH_HS                              (FIXED_HS + GEN_RBH_VHS)
1035
1036 #define GEN_RBH_CLOSURE_PTR(closure, no)        (((P_)(closure))[GEN_RBH_HS + (no) - 1])
1037 #define GEN_RBH_CLOSURE_SIZE(closure)           (GEN_INFO_SIZE(REVERT_INFOPTR(INFO_PTR(closure))))
1038 #define GEN_RBH_CLOSURE_NoPTRS(closure)         (GEN_INFO_NoPTRS(REVERT_INFOPTR(INFO_PTR(closure))))
1039 #define GEN_RBH_CLOSURE_NoNONPTRS(closure)      (GEN_RBH_CLOSURE_SIZE(closure)-GEN_RBH_CLOSURE_NoPTRS(closure)-GEN_VHS)
1040
1041 #define GEN_RBH_BQ_LOCN                         (GEN_RBH_HS)
1042 #define GEN_RBH_BQ(closure)                     (((P_)(closure))[GEN_RBH_BQ_LOCN])
1043
1044 \end{code}
1045
1046
1047 %************************************************************************
1048 %*                                                                      *
1049 \subsubsection[CONST-closures]{@CONST@ (nullary data-constructor) closure macros}
1050 %*                                                                      *
1051 %************************************************************************
1052
1053 These are never allocated normally---static closures are used
1054 instead.  They arise only as a result of in-place updates which use
1055 @INPLACE_UPD_HDR@.
1056
1057 \begin{code}
1058 #define CONST_HS                                (FIXED_HS)
1059 #define CONST_VHS                               (0L)
1060
1061 #define CONST_CLOSURE_SIZE(closure)             (0L)
1062 #define CONST_CLOSURE_NoPTRS(closure)           (0L)
1063 #define CONST_CLOSURE_NoNONPTRS(closure)        (0L)
1064 \end{code}
1065
1066 %************************************************************************
1067 %*                                                                      *
1068 \subsubsection[CHARLIKE-closures]{@CHARLIKE@ closure macros}
1069 %*                                                                      *
1070 %************************************************************************
1071
1072 These are never allocated normally.  They are a static array of
1073 closures indexed by literal characters.  As with @CONST@ closures,
1074 @CHARLIKE@ closures only arise from in-place updates using
1075 @INPLACE_UPD_HDR@.
1076 \begin{code}
1077 #define CHARLIKE_HS             (FIXED_HS)
1078 #define CHARLIKE_VHS                            (0L)
1079
1080 #define CHARLIKE_CLOSURE_SIZE(closure)          (1L)
1081 #define CHARLIKE_CLOSURE_NoPTRS(closure)        (0L)
1082 #define CHARLIKE_CLOSURE_NoNONPTRS(closure)     (1L)
1083
1084 /* Array of static charlike closures */
1085 #ifndef aix_TARGET_OS /* AIX gives link errors with consts in this file (RO assembler section) */
1086 extern const W_ CHARLIKE_closures[];
1087 #else
1088 extern W_ CHARLIKE_closures[];
1089 #endif
1090
1091 /* Macro to retrieve static charlike closure */
1092 #define CHARLIKE_CLOSURE(the_char) \
1093         (& CHARLIKE_closures[(CHARLIKE_HS+1) * ((W_)(the_char))])
1094
1095 #define CHARLIKE_VALUE(closure) \
1096         (((P_)(closure))[CHARLIKE_HS])
1097
1098 /* INPLACE_UPD_HDR used for inplace updates */
1099 \end{code}
1100
1101
1102 %************************************************************************
1103 %*                                                                      *
1104 \subsubsection[INTLIKE-closures]{@INTLIKE@ closure macros}
1105 %*                                                                      *
1106 %************************************************************************
1107
1108 These may be allocated normally (@SET_INTLIKE_HDR@) or result from
1109 inplace updates (@INPLACE_UPD_HDR@). They may be converted to a static
1110 closure during garbage collection.
1111
1112 Note: the garbage collector (@EVAC_FN(IntLike)@) assumes that this has
1113 the same structure as a @SPEC_1_0@ closure.
1114
1115 \begin{code}
1116 #define INTLIKE_HS              (FIXED_HS)
1117 #define INTLIKE_VHS                             (0L)
1118
1119 #define INTLIKE_CLOSURE_SIZE(closure)           (1L)
1120 #define INTLIKE_CLOSURE_NoPTRS(closure)         (0L)
1121 #define INTLIKE_CLOSURE_NoNONPTRS(closure)      (1L)
1122
1123 /* Array of static intlike closures */
1124 extern const P_ INTLIKE_closures;
1125
1126 /* Range of static intlike closures MAX_INTLIKE, MIN_INTLIKE is in GhcConstants.lh */
1127
1128 /* Macro to retrieve static intlike closure */
1129 #define INTLIKE_CLOSURE(the_int) \
1130         (INTLIKE_closures + ((INTLIKE_HS+1) * ((I_)(the_int))))
1131
1132 #define INTLIKE_VALUE(closure) \
1133         ((I_) ((P_)(closure))[INTLIKE_HS])
1134
1135 #define SET_INTLIKE_HDR(closure,infolbl,cc,size,ptrs) \
1136         SET_FIXED_HDR(closure,infolbl,cc)
1137
1138 /* INPLACE_UPD_HDR used for inplace updates */
1139 \end{code}
1140
1141
1142 End multi-slurp protection:
1143 \begin{code}
1144 #endif /* SMClosures_H */
1145 \end{code}