Patch #1454481: Make thread stack size runtime tunable.

Heavily revised, comprising revisions:
46640 - original trunk revision (backed out in r46655)
46647 - markup fix (backed out in r46655)
46692:46918 merged from branch aimacintyre-sf1454481

branch tested on buildbots (Windows buildbots had problems
not related to these changes).

2 files changed, 40 insertions, 0 deletions

diff --git a/Doc/lib/libthread.tex b/Doc/lib/libthread.tex
index 9573ab3fb0..d007eecde8 100644
--- a/Doc/lib/libthread.tex
+++ b/Doc/lib/libthread.tex
@@ -74,6 +74,26 @@ data.  Thread identifiers may be recycled when a thread exits and
 another thread is created.
 \end{funcdesc}
 
+\begin{funcdesc}{stack_size}{\optional{size}}
+Return the thread stack size used when creating new threads.  The
+optional \var{size} argument specifies the stack size to be used for
+subsequently created threads, and must be 0 (use platform or
+configured default) or a positive integer value of at least 32,768 (32kB).
+If changing the thread stack size is unsupported, a \exception{ThreadError}
+is raised.  If the specified stack size is invalid, a \exception{ValueError}
+is raised and the stack size is unmodified.  32kB is currently the minimum
+supported stack size value to guarantee sufficient stack space for the
+interpreter itself.  Note that some platforms may have particular
+restrictions on values for the stack size, such as requiring a minimum
+stack size > 32kB or requiring allocation in multiples of the system
+memory page size - platform documentation should be referred to for
+more information (4kB pages are common; using multiples of 4096 for
+the stack size is the suggested approach in the absence of more
+specific information).
+Availability: Windows, systems with \POSIX{} threads.
+\versionadded{2.5}
+\end{funcdesc}
+
 
 Lock objects have the following methods:
 
diff --git a/Doc/lib/libthreading.tex b/Doc/lib/libthreading.tex
index 8fb3137744..033475020a 100644
--- a/Doc/lib/libthreading.tex
+++ b/Doc/lib/libthreading.tex
@@ -125,6 +125,26 @@ method is called.
 \versionadded{2.3}
 \end{funcdesc}
 
+\begin{funcdesc}{stack_size}{\optional{size}}
+Return the thread stack size used when creating new threads.  The
+optional \var{size} argument specifies the stack size to be used for
+subsequently created threads, and must be 0 (use platform or
+configured default) or a positive integer value of at least 32,768 (32kB).
+If changing the thread stack size is unsupported, a \exception{ThreadError}
+is raised.  If the specified stack size is invalid, a \exception{ValueError}
+is raised and the stack size is unmodified.  32kB is currently the minimum
+supported stack size value to guarantee sufficient stack space for the
+interpreter itself.  Note that some platforms may have particular
+restrictions on values for the stack size, such as requiring a minimum
+stack size > 32kB or requiring allocation in multiples of the system
+memory page size - platform documentation should be referred to for
+more information (4kB pages are common; using multiples of 4096 for
+the stack size is the suggested approach in the absence of more
+specific information).
+Availability: Windows, systems with \POSIX{} threads.
+\versionadded{2.5}
+\end{funcdesc}
+
 Detailed interfaces for the objects are documented below.  
 
 The design of this module is loosely based on Java's threading model.