Add doc note regarding processors bound

jasontedor · jasontedor · commit 372e9fba53f7 · 2016-10-14T07:06:01.000-04:00
This commit adds a note to the thread pool docs regarding the bound of 32 on the number of processors used when sizing the thread pools. Relates elastic#20895
diff --git a/docs/reference/modules/threadpool.asciidoc b/docs/reference/modules/threadpool.asciidoc
@@ -121,22 +121,37 @@ threadpool:
 [[processors]]
 === Processors setting
 The number of processors is automatically detected, and the thread pool
-settings are automatically set based on it. Sometimes, the number of processors
-are wrongly detected, in such cases, the number of processors can be
-explicitly set using the `processors` setting.  The example below sets
-the number of processors to 4, which means that the default search thread pool size
-is 4 x 3 = 12.
+settings are automatically set based on it. In some cases it can be
+useful to override the number of detected processors. This can be done
+by explicitly setting the `processors` setting.
 
 [source,js]
 --------------------------------------------------
 processors: 4
 --------------------------------------------------
 
-This setting is important when running multiple node instances on a single 
-bare-metal machine.  Each node will detect that it has the full number of 
-processors.  But in reality, they are sharing processors on the single machine.  
-In other words, it is advised to lower the `processors` setting accordingly.  For example,
-on a 24 core machine and running 3 nodes, set processors to 8.
+There are a few use-cases for explicitly overriding the `processors`
+setting:
+
+. If you are running multiple instances of Elasticsearch on the same
+host but want Elasticsearch to size its thread pools as if it only has a
+fraction of the CPU, you should override the `processors` setting to the
+desired fraction (e.g., if you're running two instances of Elasticsearch
+on a 16-core machine, set `processors` to 8). Note that this is an
+expert-level use-case and there's a lot more involved than just setting
+the `processors` setting as there are other considerations like changing
+the number of garbage collector threads, pinning processes to cores,
+etc.
+. The number of processors is by default bounded to 32. This means that
+on systems that have more than 32 processors, Elasticsearch will size
+its thread pools as if there are only 32 processors present. This
+limitation was added to avoid creating too many threads on systems that
+have not properly adjusted the `ulimit` for max number of processes. In
+cases where you've adjusted the `ulimit` appropriately, you can override
+this bound by explicitly setting the `processors` setting.
+. Sometimes the number of processors is wrongly detected and in such
+cases explicitly setting the `processors` setting will workaround such
+issues.
 
 In order to check the number of processors detected, use the nodes info
 API with the `os` flag.
