Add description of how testsuite parallelization works

... for the benefit of the next poor soul who will need to debug it.

	gcc/testsuite/
	* lib/gcc-defs.exp: Add a comment.

1 files changed, 34 insertions, 0 deletions

diff --git a/gcc/testsuite/lib/gcc-defs.exp b/gcc/testsuite/lib/gcc-defs.exp
index e9119f0..d17308d 100644
--- a/gcc/testsuite/lib/gcc-defs.exp
+++ b/gcc/testsuite/lib/gcc-defs.exp
@@ -176,6 +176,40 @@ if { [info exists env(GCC_RUNTEST_PARALLELIZE_DIR)] \
     global gcc_runtest_parallelize_dir
     global gcc_runtest_parallelize_last
 
+    # GCC testsuite is parallelised by starting N runtest processes -- each
+    # with its own test directory.  These N runtest processes ALL go through
+    # the relevant .exp and ALL attempt to run every test.  And they go
+    # through the tests the same order -- this is important, and if there is
+    # a bug that causes different runtest processes to enumerate the tests
+    # differently, then things will break and some tests will be skipped, while
+    # others will be ran several times.
+    # So, just before a runtest processes runs a specific test it asks
+    # "runtest_file_p" routine whether a particular test is part of
+    # the requested testsuite.  We override this function so that it
+    # returns "yes" to the first-arrived runtest process, and "no" to all
+    # subsequent runtest processes -- this is implemented by creating a marker
+    # file, which persist till the end of the test run.  We optimize this
+    # a bit by batching 10 tests and using a single marker file for the batch.
+    #
+    # Note that the runtest processes all race each other to get to the next
+    # test batch.  This means that batch allocation between testsuite runs
+    # is very likely to change.
+    #
+    # To confirm or deny suspicion that tests are skipped or executed
+    # multiple times due to runtest processes enumerating tests differently ...
+    # 1. Uncomment the three below "verbose -log gcc_parallel_test_run_p ..."
+    #    debug print-outs.
+    # 2. Run the testsuite with "-v" added to RUNTESTFLAGS
+    # 3. Extract debug print-outs with something like:
+    #    for i in $(find -name "*.log.sep"); do
+    #      grep gcc_parallel_test_run_p $i \
+    #        | sed -e "s/\([^ ]*\) \([^ ]*\) \([^ ]*\) \([^ ]*\)/\3 \2/" \
+    #        | sed -e "s#\(/testsuite/[a-z+]*\)[0-9]*/#\1N/#" > $i.order
+    #    done
+    # 4. Compare debug print-outs produced by individual runtest processes:
+    #    find -name "*.log.sep.order" | xargs md5sum | sort
+    # 5. Check that MD5 hashes of all .order files of the same testsuite match
+    #    and investigate if they don't.
     set gcc_runtest_parallelize_counter 0
     set gcc_runtest_parallelize_counter_minor 0
     set gcc_runtest_parallelize_enable 1