runtime: document subtlety around entering mark termination
The barrier in gcDrain does not account for concurrent gcDrainNs
happening in gchelpwork, so it can actually return while there is
still work being done. It turns out this is okay, but for subtle
reasons involving gcDrainN always being run on the system
stack. Document these reasons.
Change-Id: Ib07b3753cc4e2b54533ab3081a359cbd1c3c08fb
Reviewed-on: https://go-review.googlesource.com/7736
Reviewed-by: Rick Hudson <rlh@golang.org>
diff --git a/src/runtime/mgc.go b/src/runtime/mgc.go
index b82569b..8eba5a8 100644
--- a/src/runtime/mgc.go
+++ b/src/runtime/mgc.go
@@ -333,6 +333,12 @@
var gcw gcWork
gcDrain(&gcw)
gcw.dispose()
+ // Despite the barrier in gcDrain, gcDrainNs may still
+ // be doing work at this point. This is okay because
+ // 1) the gcDrainNs happen on the system stack, so
+ // they will flush their work to the global queues
+ // before we can stop the world, and 2) it's fine if
+ // we go into mark termination with some work queued.
// Begin mark termination.
gctimer.cycle.markterm = nanotime()
diff --git a/src/runtime/mgcmark.go b/src/runtime/mgcmark.go
index 197b6a8..8e0a88f 100644
--- a/src/runtime/mgcmark.go
+++ b/src/runtime/mgcmark.go
@@ -366,6 +366,9 @@
}
// gcDrainN scans n objects, blackening grey objects.
+//
+// This MUST be run on the system stack to prevent a stop-the-world
+// while this locally holds GC work buffers.
//go:nowritebarrier
func gcDrainN(gcw *gcWork, n int) {
checknocurrentwbuf()
