New MONO_THREADS_SUSPEND env var to select suspend policy

Set to one of "preemptive", "coop" or "hybrid".

Unlike the old MONO_ENABLE_COOP, MONO_ENABLE_COOP_SUSPEND,
MONO_ENABLE_HYBRID_SUSPEND, the value of MONO_THREADS_SUSPEND will take
priority over the configure flags default.

For compatability the old environment variables will be respected if neither
MONO_THREADS_SUSPEND nor a configure flag was set.  A warning will be emitted
if MONO_THREADS_SUSPEND isn't set.  (Rationale: maybe the environment set both
because they're not sure which version of Mono they will be running - so don't
nag them).

1 files changed, 26 insertions, 12 deletions

diff --git a/man/mono.1 b/man/mono.1
index ec8c9c0762f..8f9f6439f79 100644
--- a/man/mono.1
+++ b/man/mono.1
@@ -1178,19 +1178,33 @@ If set, tells mono to attempt using native asynchronous I/O services. If not
 set, a default select/poll implementation is used. Currently epoll and kqueue
 are supported.
 .TP
+\fBMONO_THREADS_SUSPEND\fR
+Selects a mechanism that Mono will use to suspend threads.  May be set to
+"preemptive", "coop", or "hybrid".  Threads may need to be suspended by the
+debugger, or using some .NET threading APIs, and most commonly when the SGen
+garbage collector needs to stop all threads during a critical phase of garbage
+collection.  Preemptive mode is the mode that Mono has used historically, going
+back to the Boehm days, where the garbage collector would run at any point and
+suspend execution of all threads as required to perform a garbage collection.
+The cooperative mode on the other hand requires the cooperation of all threads
+to stop at a safe point.  This makes for an easier to debug garbage collector.
+As of Mono 4.3.0 it is a work in progress, and while it works, it has not been
+used extensively.  This option enables the feature and allows us to find spots
+that need to be tuned for this mode of operation.  Hybrid mode is a combination
+of the two that retains better compatability with scenarios where Mono is
+embedded in another application: threads that are running managed code or code
+that comprises the Mono runtime will be cooperatively suspended, while threads
+running embedder code will be preemptively suspended.
+
+Alternatively, coop and hybrid mode can be enabled at compile time by using the
+--enable-cooperative-suspend or --enable-hybrid-suspend flags, respectively,
+when calling configure.  The \fBMONO_THREADS_SUSPEND\fR environment variable
+takes priority over the compiled default.
+.TP
 \fBMONO_ENABLE_COOP_SUSPEND\fR
-This makes the Mono runtime and the SGen garbage collector run in cooperative
-mode as opposed to run on preemptive mode.   Preemptive mode is the mode
-that Mono has used historically, going back to the Boehm days, where the
-garbage collector would run at any point and suspend execution of all 
-threads as required to perform a garbage collection.  The cooperative mode
-on the other hand requires the cooperation of all threads to stop at a 
-safe point.   This makes for an easier to debug garbage collector.   As
-of Mono 4.3.0 it is a work in progress, and while it works, it has not
-been used extensively.   This option enabled the feature and allows us to
-find spots that need to be tuned for this mode of operation.   Alternatively,
-this mode can be enabled at compile time by using the --enable-cooperative-suspend
-flag when calling configure.
+This environment variable is obsolete, but retained for backward compatibility.
+Use \fBMONO_THREADS_SUSPEND\fR set to "coop" instead.  Note that if configure flags
+were provided to enable cooperative or hybrid suspend, this variable is ignored.
 .TP
 \fBMONO_ENV_OPTIONS\fR
 This environment variable allows you to pass command line arguments to