Added docs for consumers_wait_for_messages option (#8010)

Author: jeff-matthews

src/guides/v2.3/config-guide/mq/manage-message-queues.md

@@ -59,9 +59,12 @@ Edit the `/app/etc/env.php` file to configure the cron job `consumers_runner`.
 ```
 
 *  `cron_run` - A boolean value that enables or disables the `consumers_runner` cron job (default = `true`).
-*  `max_messages` - The maximum number of messages each consumer must process before terminating (default = `10000`). Although we do not recommend it, you can use 0 to prevent the consumer from terminating.
+*  `max_messages` - The maximum number of messages each consumer must process before terminating (default = `10000`). Although we do not recommend it, you can use 0 to prevent the consumer from terminating. See [`consumers_wait_for_messages`]({{ page.baseurl }}/config-guide/prod/config-reference-envphp.html#consumers_wait_for_messages) to configure how consumers process messages from the message queue.
 *  `consumers` - An array of strings specifying which consumer(s) to run. An empty array runs *all* consumers.
 
+   {:.bs-callout-info}
+   If your {{ site.data.var.ee }} store is hosted on the Cloud platform, use the [`CONSUMERS_WAIT_FOR_MAX_MESSAGES`]({{ site.baseurl }}/cloud/env/variables-deploy.html#consumers_wait_for_max_messages) to configure how consumers process messages from the message queue.
+
 {% include config/message-queue-consumers.md %}
 
 #### Related Topics

src/guides/v2.3/config-guide/prod/config-reference-envphp.md

@@ -9,22 +9,23 @@ functional_areas:
 
 The `env.php` file contains the following sections:
 
-| Name                  | Description                                    |
-| --------------------- | ---------------------------------------------- |
-| `backend`             | Settings for the Admin area                    |
-| `cache_types`         | Cache storage settings                         |
-| `cron`                | Enable or disable the cron jobs                |
-| `crypt`               | The encryption key for cryptographic functions |
-| `db`                  | Database connection settings                   |
-| `directories`         | Magento directories mapping settings           |
-| `downloadable_domains`| List of downloadable domains                   |
-| `install`             | The installation date                          |
-| `lock`                | Lock provider settings                         |
-| `MAGE_MODE`           | The [Magento mode][magento-mode]               |
-| `queue`               | [Message queues][message-queues] settings      |
-| `resource`            | Mapping of resource name to a connection       |
-| `session`             | Session storage data                           |
-| `x-frame-options`     | Setting for [x-frame-options][x-frame-options] |
+| Name                          | Description                                                     |
+|-------------------------------|-----------------------------------------------------------------|
+| `backend`                     | Settings for the Admin area                                     |
+| `cache_types`                 | Cache storage settings                                          |
+| `consumers_wait_for_messages` | Configure how consumers process messages from the message queue |
+| `cron`                        | Enable or disable the cron jobs                                 |
+| `crypt`                       | The encryption key for cryptographic functions                  |
+| `db`                          | Database connection settings                                    |
+| `directories`                 | Magento directories mapping settings                            |
+| `downloadable_domains`        | List of downloadable domains                                    |
+| `install`                     | The installation date                                           |
+| `lock`                        | Lock provider settings                                          |
+| `MAGE_MODE`                   | The [Magento mode][magento-mode]                                |
+| `queue`                       | [Message queues][message-queues] settings                       |
+| `resource`                    | Mapping of resource name to a connection                        |
+| `session`                     | Session storage data                                            |
+| `x-frame-options`             | Setting for [x-frame-options][x-frame-options]                  |
 
 ## backend
 
@@ -62,6 +63,26 @@ All the Magento cache types configuration are available from this node.
 
 Learn more about different [Cache Types][cache-types].
 
+## consumers_wait_for_messages
+
+Specify whether consumers should continue polling for messages if the number of processed messages is less than the `max_messages` value. The default value is `1`.
+
+```conf
+'queue' => [
+    'consumers_wait_for_messages' => 1
+]
+```
+
+The following options are available:
+
+-  `1`—Consumers continue to process messages from the message queue until reaching the `max_messages` value specified in the `env.php` file before closing the TCP connection and terminating the consumer process. If the queue empties before reaching the `max_messages` value, the consumer waits for more messages to arrive.
+
+   We recommend this setting for large merchants because a constant message flow is expected and delays in processing are undesirable.
+
+-  `0`—Consumers process available messages in the queue, close the TCP connection, and terminate. Consumers do not wait for additional messages to enter the queue, even if the number of processed messages is less than the `max_messages` value specified in the `env.php` file. This can help prevent issues with cron jobs caused by long delays in message queue processing.
+
+   We recommend this setting for smaller merchants that do not expect a constant message flow and prefer to conserve computing resources in exchange for minor processing delays when there could be no messages for days.
+
 ## cron
 
 Enable or disable cron jobs for the Magento application. By default, cron jobs are enabled. To disable them, add the `cron` configuration to the `env.php` file and set the value to `0`.