Document PERL_TEST_HARNESS_ASAP

which can increase the CPU occupancy when running the test suite in
parallel on a many-core system, resulting in earlier completion.

1 files changed, 21 insertions, 6 deletions

diff --git a/pod/perlhack.pod b/pod/perlhack.pod
index 1f66863485..9d5b45a571 100644
--- a/pod/perlhack.pod
+++ b/pod/perlhack.pod
@@ -910,9 +910,10 @@ Sets PERL_SKIP_TTY_TEST to true before running normal test.
 =head2 Parallel tests
 
 The core distribution can now run its regression tests in parallel on
-Unix-like platforms.  Instead of running C<make test>, set C<TEST_JOBS>
-in your environment to the number of tests to run in parallel, and run
-C<make test_harness>.  On a Bourne-like shell, this can be done as
+Unix-like and Windows platforms.  On Unix, instead of running C<make
+test>, set C<TEST_JOBS> in your environment to the number of tests to
+run in parallel, and run C<make test_harness>.  On a Bourne-like shell,
+this can be done as
 
     TEST_JOBS=3 make test_harness  # Run 3 tests in parallel
 
@@ -921,9 +922,23 @@ because L<TAP::Harness> needs to be able to schedule individual
 non-conflicting test scripts itself, and there is no standard interface
 to C<make> utilities to interact with their job schedulers.
 
-Note that currently some test scripts may fail when run in parallel
-(most notably F<dist/IO/t/io_dir.t>).  If necessary, run just the
-failing scripts again sequentially and see if the failures go away.
+Tests are normally run in a logical order, with the sanity tests first,
+then the main tests of the Perl core functionality, then the tests for
+the non-core modules.  On many-core systems, this may not use the
+hardware as effectively as possible.  By also specifying
+
+ TEST_JOBS=19 PERL_TEST_HARNESS_ASAP=1 make -j19 test_harness
+
+you signal that you want the tests to finish in wall-clock time as short
+as possible.  After the sanity tests are completed, this causes the
+remaining ones to be packed into the available cores as tightly as
+we know how.  This has its greatest effect on slower, many-core systems.
+Throughput was sped up by 20% on an outmoded 24-core system; less on
+more recent faster ones with fewer cores.
+
+Note that the command line above added a C<-j> parameter to make, so as
+to cause parallel compilation.  This may or may not work on your
+platform.
 
 =head2 Running tests by hand