[#1342] Add note on the need of fixed :pool_size to guide subscriptio…

…ns.md

guides/subscriptions.md

@@ -45,6 +45,14 @@ line:
     Supervisor.start_link(children, opts)
 ```
 
+> Note: If your application is deployed in an environment, where the number of CPU cores can differ between the application instances,
+> be sure to specify a fixed `:pool_size` option, otherwise the messages will not be delivered reliably between your nodes. This can
+> happen often on cloud deployment platforms.
+
+```elixir
+{Absinthe.Subscription, name: MyAppWeb.Endpoint, pool_size: 8}
+```
+
 See `Absinthe.Subscription.child_spec/1` for more information on the supported
 options.
 

lib/absinthe/subscription.ex

@@ -59,6 +59,10 @@ defmodule Absinthe.Subscription do
     compressed or not.
   * `:pool_size` - (Optional - default `System.schedulers() * 2`) An integer
     specifying the number of `Absinthe.Subscription.Proxy` processes to start.
+    You may want to specify a fixed `:pool_size` if your deployment environment
+    does not guarantee an equal number of CPU cores to be available on all
+    application nodes. In such case, using the defaults may lead to missing
+    messages. This situation often happens on cloud-based deployment environments.
   """
   @spec child_spec(atom() | [opt()]) :: Supervisor.child_spec()
   def child_spec(pubsub) when is_atom(pubsub) do