From 92686de1bd8e5015d5c53fa589a696debbc5a6f3 Mon Sep 17 00:00:00 2001
From: Elizabeth Mattijsen <liz@raku.rocks>
Date: Tue, 7 Mar 2023 15:44:46 +0100
Subject: [PATCH] Document ThreadPoolScheduler.new(:max_threads) a bit better

And the associated RAKUDO_MAX_THREADS environment variable.
---
 doc/Programs/03-environment-variables.rakudoc |  7 ++++++-
 doc/Type/ThreadPoolScheduler.rakudoc          | 16 +++++++++++++++-
 2 files changed, 21 insertions(+), 2 deletions(-)

diff --git a/doc/Programs/03-environment-variables.rakudoc b/doc/Programs/03-environment-variables.rakudoc
index 802733828..c746fc5d2 100644
--- a/doc/Programs/03-environment-variables.rakudoc
+++ b/doc/Programs/03-environment-variables.rakudoc
@@ -135,7 +135,12 @@ X<|Programs,RAKUDO_MAX_THREADS>
 =item C<RAKUDO_MAX_THREADS> (I<UInt>; B<src/core.c/ThreadPoolScheduler.pm6>)
 
 Indicates the maximum number of threads used by default when creating a
-C<ThreadPoolScheduler>. Defaults to 64.
+C<ThreadPoolScheduler>. Defaults to 64 unless there appear to be more than
+8 CPU cores available: in which case it defaults to 8 * number of cores.
+
+As of release 2022.06 of the Rakudo compiler, it is also possible to
+specify "B<unlimited>" or "B<Inf>" to indicate that the number of threads
+available by the operating system, will be the limiting factor.
 
 X<|Programs,TMPDIR>X<|Programs,TEMP>X<|Programs,TMP>
 =item C<TMPDIR>, C<TEMP>, C<TMP> (I<Str>; B<src/core.c/IO/Spec/>)
diff --git a/doc/Type/ThreadPoolScheduler.rakudoc b/doc/Type/ThreadPoolScheduler.rakudoc
index fa78a6682..2419b15d8 100644
--- a/doc/Type/ThreadPoolScheduler.rakudoc
+++ b/doc/Type/ThreadPoolScheduler.rakudoc
@@ -17,9 +17,23 @@ the work.
 
 =head2 new
 
-    method new(Int :$initial_threads = 0, Int :$max_threads=16)
+    method new(Int :$initial_threads = 0, Int :$max_threads = 8 * cores)
 
 Creates a new C<ThreadPoolScheduler> object with the given range of threads to
 maintain.
 
+The default value for C<:initial_threads> is B<0>, so no threads will be
+started when a C<ThreadPoolScheduler> object is created by default.
+
+The default value for C<:max_threads> is B<64>, unless there appear to be
+more than 8 CPU cores available.  In that case the default will be 8 times
+the number of CPU cores.
+
+See also the L<RAKUDO_MAX_THREADS|/programs/03-environment-variables#Other>
+environment variable to set the default maximum number of threads.
+
+As of release 2022.06 of the Rakudo compiler, it is also possible to specify
+C<Inf> or C<*> as a value for C<:max_threads>, indicating that the maximum
+number of threads allowed by the operating system, will be used.
+
 =end pod