.

go/internal/xtracing/tracetest/tracetest.go

@@ -268,6 +268,13 @@ func (t *T) SetEventRouter(routeEvent func(event interface{}) (stream string)) {
 	t.routeEvent = routeEvent
 }
 
+// t.RxEvent should be synchronously called from test system when an event
+// occurs.
+//
+// The sequential process of the test system where event originated should be
+// paused until RxEvent returns. This requirement can be easily met via ... XXX
+//
+//
 // XXX doc; naming
 // XXX NewEvent? IncomingEvent? OnEvent?
 // XXX pass events in not via t (via something dedicated)?
@@ -299,32 +306,6 @@ func (t *T) RxEvent(event interface{}) {
 		t.fatalfInNonMain("%s: (pre)send: canceled (test failed)", stream)
 	}
 
-	// TODO it is possible to empirically detect here if a test incorrectly
-	// decomposed its system into serial streams: consider unrelated to each
-	// other events A and B are incorrectly routed to the same channel. It
-	// could be so happening that the order of checks on the test side is
-	// almost always correct and so the error is not visible. However
-	//
-	//	if we add delays to delivery of either A or B
-	//	and test both combinations
-	//
-	// we will for sure detect the error as, if A and B are indeed
-	// unrelated, one of the delay combination will result in events
-	// delivered to test in different to what it expects order.
-	//
-	// the time for delay could be taken as follows:
-	//
-	//	- run the test without delay; collect δt between events on particular stream
-	//	- take delay = max(δt)·10
-	//
-	// to make sure there is indeed no different orderings possible on the
-	// stream, rerun the test N(event-on-stream) times, and during i'th run
-	// delay i'th event.
-	//
-	// TODO See also on this topic:
-	// http://www.1024cores.net/home/relacy-race-detector
-	// http://www.1024cores.net/home/relacy-race-detector/rrd-introduction
-
 	if delay != 0 {
 		time.Sleep(delay)
 	}
@@ -564,10 +545,38 @@ func run(t testing.TB, f func(t *T), delayInjectTab map[string]*delayInjectState
 // unexpected events. f is rerun several times and should not alter its
 // behaviour from run to run.
 func Verify(t *testing.T, f func(t *T)) {
+	// run f once. This produces initial trace of events.
 	tT0 := run(t, f, nil)
 
 	// now, if f succeeds, verify f with injected delays.
-	// XXX explain with more text
+	//
+	// We inject delays to empirically detect race conditions and if a test
+	// incorrectly decomposed its system into serial streams: consider
+	// unrelated to each other events A and B are incorrectly routed to the
+	// same channel. It could be so happening that the order of checks on
+	// the test side is almost always correct and so the error is not
+	// visible. However
+	//
+	//	if we add delays to delivery of either A or B
+	//	and test both combinations
+	//
+	// we will for sure detect the error as, if A and B are indeed
+	// unrelated, one of the delay combination will result in events
+	// delivered to test in different to what it expects order.
+	//
+	// the time for delay could be taken as follows:
+	//
+	//	- run the test without delay; collect δt between events on particular stream
+	//	- take delay = max(δt)·10
+	//
+	// to make sure there is indeed no different orderings possible on the
+	// stream, rerun the test N(event-on-stream) times, and during i'th run
+	// delay i'th event.
+	//
+	// See also on this topic:
+	// http://www.1024cores.net/home/relacy-race-detector
+	// http://www.1024cores.net/home/relacy-race-detector/rrd-introduction
+
 	if tT0.Failed() {
 		return
 	}