Document SRT scavenging behavior of scavenge_block() and scavenge_one()
authorÖmer Sinan Ağacan <omeragacan@gmail.com>
Thu, 28 Jun 2018 05:44:15 +0000 (08:44 +0300)
committerÖmer Sinan Ağacan <omeragacan@gmail.com>
Thu, 28 Jun 2018 05:44:22 +0000 (08:44 +0300)
Reviewers: simonmar, bgamari, erikd

Reviewed By: simonmar

Subscribers: rwbarton, thomie, carter

Differential Revision: https://phabricator.haskell.org/D4893

rts/sm/Scav.c

index 39374c0..2f61914 100644 (file)
  *
  * ---------------------------------------------------------------------------*/
 
+/* ----------------------------------------------------------------------------
+   We have two main scavenge functions:
+
+   - scavenge_block(bdescr *bd)
+   - scavenge_one(StgPtr p)
+
+   As the names and parameters suggest, first one scavenges a whole block while
+   the second one only scavenges one object. This however is not the only
+   difference. scavenge_block scavenges all SRTs while scavenge_one only
+   scavenges SRTs of stacks. The reason is because scavenge_one is called in two
+   cases:
+
+   - When scavenging a mut_list
+   - When scavenging a large object
+
+   We don't have to scavenge SRTs when scavenging a mut_list, because we only
+   scavenge mut_lists in minor GCs, and static objects are only collected in
+   major GCs.
+
+   However, because scavenge_one is also used to scavenge large objects (which
+   are scavenged even in major GCs), we need to deal with SRTs of large
+   objects. We never allocate large FUNs and THUNKs, but we allocate large
+   STACKs (e.g. in threadStackOverflow), and stack frames can have SRTs. So
+   scavenge_one skips FUN and THUNK SRTs but scavenges stack frame SRTs.
+
+   In summary, in a major GC:
+
+   - scavenge_block() scavenges all SRTs
+   - scavenge_one() scavenges only stack frame SRTs
+   ------------------------------------------------------------------------- */
+
 #include "PosixSource.h"
 #include "Rts.h"