diff --git a/modules/ROOT/pages/async-scope-reference.adoc b/modules/ROOT/pages/async-scope-reference.adoc index ad7f36b258..4e59a62341 100644 --- a/modules/ROOT/pages/async-scope-reference.adoc +++ b/modules/ROOT/pages/async-scope-reference.adoc @@ -4,49 +4,39 @@ include::_attributes.adoc[] endif::[] :keywords: Async, scopes, studio, anypoint -The Async scope is a branch processing block that executes simultaneously with the main flow. The main flow continues to execute while it initiates and processes the Async scope. The flow does not have to pause until the last message processor embedded in the asynchronous flow has completed its task. +The Async scope provides a mechanism for processing the xref:about-mule-event.adoc[Mule event] simultaneously with the main flow. The flow does not wait for the last processor within the asynchronous flow to complete its tasks, and Async does not block the execution of downstream components outside of Async. -Async can be useful for executing time-consuming operations that do not require you to send a response back to the initiating flow (such as printing a file or connecting to a mail server). - -To facilitate simultaneous branch processing, the Async scope sends one copy of the message it has received to the first embedded message processor in its own processing block. At the same time, it sends another copy of the message to the next message processor in the main flow. +Async is useful for executing time-consuming operations that do not require a response to the initiating flow, for example, when printing a file or connecting to an email server. image::async-scope-schematic.png[Async+scope+schematic] -Because the Async scope is executed in a "fire and forget" manner, the result of the processing within the scope is not available in the main flow. - -== Async Configuration - -Async scopes are configurable. - -[%header,cols="1,4"] -|=== -| Field | Description -| Display Name (`name`) | Name for the Async scope. -| Max Concurrency (`maxConcurrency`) a| Optional. Sets the maximum number of concurrent messages that the scope can process. By default, the container thread pool determines the maximum number of threads to use to optimize the performance when processing messages. When the scope is processing the maximum number of concurrent messages, it cannot receive additional requests. +Because the Async scope executes in a "fire and forget" manner, the result of processing within the scope is not available in the main flow except in the case of <> that are modified within Async. -Set `maxConcurrency` to `1` to cause the scope to process requests one at a time. +The Async scope does not inherit the exception strategy of the main flow. To handle errors in an Async scope, use the xref:try-scope-concept.adoc[Try scope]. -See xref:execution-engine.adoc#backpressure[Back-Pressure Management] for details about Mule behavior after reaching the maximum concurrency value. -|=== - -== Async Scopes versus Subflows - -Unlike a subflow, an Async scope: - -* Does not inherit the exception strategy of the main flow. -+ -To handle errors in an Async scope, use the Try scope. -+ +//// +// TODO: Recommend removing the following bullets: +//TODO: Next bullet belongs (and is) in the main description. * Processes messages asynchronously. + //TODO: This is not always true apparently. See info on mutable objects: * Does not pass data back to the main flow. +//TODO: Recommend removing the following bullets, +// as the distinction from subflow isn't necessary: * Exists inline with the main flow thread. * Is not called by a Flow Reference component. * Is not reusable +//// + +[[mutable_objects]] +== Async Scope Behavior with Mutable Objects -Note that even though the Async scope receives a copy of the Mule message, the payload is not copied. The same payload objects are referenced by both Mule messages: One that continues down the original flow, and the one processed by the Async scope. +To facilitate simultaneous branch processing, the Async scope sends one copy of the Mule event (the Mule message and any Mule variables) it receives to the first processor within its processing block. At the same time, the scope sends another copy of this event to the next processor in the main flow. -In other words, if the payload of your message is a mutable object (for example, a bean with different fields in it) and a message processor in your Async scope changes the value of one of the fields, the message processors outside of the Async scope see the changed values. +Though the Async scope receives a copy of the Mule message, Mule does not copy the payload. Instead, each Mule message references the same payload. One payload continues in the main flow, and the other is processed within the Async scope. +If the payload of your message is a mutable object (for example, a bean with different fields in it) and a message processor in your Async scope changes the value of one of the fields, the message processors outside of the Async scope see the changed values. + +//TODO: Ivan, feel free to ADD ANY RECOMMENDATION HERE == Example Async Scope Configuration @@ -90,8 +80,28 @@ The following XML fragment shows an example configuration of an Async scope insi ---- +== Reference + +Async scopes are configurable. + +[%header,cols="1a,1a,1a,4a"] +|=== +| Field | XML | Default | Description +| *Display Name* | `name` | Async | Name for the Async scope. +| *Max Concurrency* | `maxConcurrency` | See description. | Optional. +//TODO: Re "maximum number of _messages_" next, is it limited to Mule messages? +// What is processed concurrently? +Sets the maximum number of concurrent messages that the scope can process. By default, the container thread pool optimizes performance by determining the maximum number of threads to use. + +Setting `maxConcurrency` to `1` causes the scope to process requests one at a time and not in parallel. + +Upon reaching maximum concurrency, the scope cannot receive additional requests. See xref:execution-engine.adoc#backpressure[Back-Pressure Management] for details about the behavior of Mule when it reaches the maximum concurrency value. +|=== + + == See Also -* xref:about-components.adoc[Core Components] +* xref:about-mule-event.adoc[] +* xref:about-components.adoc[] * xref:transaction-management.adoc#tx_scopes_routers[How Transactions Affect Scopes and Routers] -* xref:tuning-backpressure-maxconcurrency.adoc[Back-Pressure and MaxConcurrency] +* xref:tuning-backpressure-maxconcurrency.adoc[]