Clarify documentation

Signed-off-by: Kimball Thurston <[email protected]>

cmake/OpenEXRSetup.cmake

@@ -42,10 +42,13 @@ option(OPENEXR_INSTALL_PKG_CONFIG "Install OpenEXR.pc file" ON)
 # Whether to enable threading. This can be disabled, although thread pool and tasks
 # are still used, just processed immediately
 option(OPENEXR_ENABLE_THREADING "Enables threaded processing of requests" ON)
-# will use TBB for the global thread pool by default
-# if you create your own additional thread pools, those will NOT use
-# TBB by default, as it can easily cause recursive mutex deadlocks
-# as TBB shares a single thread pool with multiple arenas
+# When set to ON, will change the thread pool to use TBB for the
+# global thread pool by default.
+#
+# Regardless of this setting, if you create your own additional thread
+# pools, those will NOT use TBB by default, as it can easily cause
+# recursive mutex deadlocks as TBB shares a single thread pool with
+# multiple arenas
 option(OPENEXR_USE_TBB "Switch internals of IlmThreadPool to use TBB by default" OFF)
 
 option(OPENEXR_USE_DEFAULT_VISIBILITY "Makes the compile use default visibility (by default compiles tidy, hidden-by-default)"     OFF)

website/install.rst

@@ -393,14 +393,21 @@ TBB Dependency
 ~~~~~~~~~~~~~~
 
 OpenEXR can optionally use the TBB library as the default global
-thread pool as a thread provider. This assumes the OneAPI version of
-TBB which provides cmake modules. This ONLY changes the global thread
-pool as otherwise this can cause mutex deadlocks if you create other
-ThreadPools thinking that they are separate threads (i.e. the previous
-use case), but TBB shares actual threads and uses an arena to control
-thread usage.
-
-To enable this, simple set the flag during config:
+thread pool as a thread provider. This allows applications which also
+use TBB for other purposes to lower the number of active threads. With
+high core count machines more prevalent, this can signficantly lower
+the number of active threads and so the improve available resources
+especially when compiling with a static library and using plugins
+which use OpenEXR.
+
+This is disabled by default, but when turned on, assumes the OneAPI
+version of TBB which provides cmake modules. This ONLY changes the
+global thread pool as otherwise this can cause mutex deadlocks if you
+create other ThreadPools thinking that they are separate threads (i.e.
+the previous use case), but TBB shares actual threads and uses an
+arena to control thread usage.
+
+To enable this, set the flag during config:
 
 .. code-block::