runtime: diagram flow of stats through heap profile

Every time I modify heap profiling, I find myself redrawing this
diagram, so add it to the comments. This shows how allocations and
frees are accounted, how we arrive at consistent profile snapshots,
and when those snapshots are published to the user.

Change-Id: I106aba1200af3c773b46e24e5f50205e808e2c69
Reviewed-on: https://go-review.googlesource.com/37514
Run-TryBot: Austin Clements <austin@google.com>
TryBot-Result: Gobot Gobot <gobot@golang.org>
Reviewed-by: Rick Hudson <rlh@golang.org>

diff --git a/src/runtime/mprof.go b/src/runtime/mprof.go
index 555a3ac2a680b506e4c490cc9a0dde7c67b26a4d..6b29b6847d974d718090ce07d253474c427be965 100644 (file)
--- a/src/runtime/mprof.go
+++ b/src/runtime/mprof.go
@@ -64,6 +64,34 @@ type memRecord struct {
        // come only after a GC during concurrent sweeping. So if we would
        // naively count them, we would get a skew toward mallocs.
        //
+       // Hence, we delay information to get consistent snapshots as
+       // of mark termination. Allocations count toward the next mark
+       // termination's snapshot, while sweep frees count toward the
+       // previous mark termination's snapshot:
+       //
+       //              MT          MT          MT          MT
+       //             .·|         .·|         .·|         .·|
+       //          .·˙  |      .·˙  |      .·˙  |      .·˙  |
+       //       .·˙     |   .·˙     |   .·˙     |   .·˙     |
+       //    .·˙        |.·˙        |.·˙        |.·˙        |
+       //
+       //       alloc → ▲ ← free
+       //               ┠┅┅┅┅┅┅┅┅┅┅┅P
+       //       r_a     →    p_a    →  allocs
+       //                    p_f    →  frees
+       //
+       //                   alloc → ▲ ← free
+       //                           ┠┅┅┅┅┅┅┅┅┅┅┅P
+       //                   r_a     →    p_a    →  alloc
+       //                                p_f    →  frees
+       //
+       // Since we can't publish a consistent snapshot until all of
+       // the sweep frees are accounted for, we wait until the next
+       // mark termination ("MT" above) to publish the previous mark
+       // termination's snapshot ("P" above). To do this, information
+       // is delayed through "recent" and "prev" stages ("r_*" and
+       // "p_*" above). Specifically:
+       //
        // Mallocs are accounted in recent stats.
        // Explicit frees are accounted in recent stats.
        // GC frees are accounted in prev stats.