From f52cd2f538effc9e51c355587371be792f5d23ed Mon Sep 17 00:00:00 2001 From: Duke Date: Sun, 9 Oct 2022 20:17:30 -0700 Subject: [PATCH 1/3] W-11599413-asyncScope-duke --- modules/ROOT/pages/async-scope-reference.adoc | 35 ++++++++++--------- 1 file changed, 18 insertions(+), 17 deletions(-) diff --git a/modules/ROOT/pages/async-scope-reference.adoc b/modules/ROOT/pages/async-scope-reference.adoc index ad7f36b258..6f18c3c30d 100644 --- a/modules/ROOT/pages/async-scope-reference.adoc +++ b/modules/ROOT/pages/async-scope-reference.adoc @@ -4,48 +4,49 @@ 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 is a branch processing block that executes simultaneously with the main flow. The main flow continues to execute while it initiates the Async scope and processing takes places with in Async. The flow does wait for the last processor within the asynchronous flow to completes its tasks. -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). +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. -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. +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. 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. +Because the Async scope executes in a "fire and forget" manner, the result of the processing within the scope is not available in the main flow. Mule variables created within the flow do not propagate to the main flow, nor do any changes to the payload or other parts of the Mule event. -== Async Configuration +== Reference Async scopes are configurable. -[%header,cols="1,4"] +[%header,cols="1a,1a,1a,4a"] |=== -| 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. +| Field | XML | Default | Description +| *Display Name* | `name` | Async | Name for the Async scope. +| *Max Concurrency* | `maxConcurrency` | See description. | Optional. Sets the maximum number of concurrent Mule messages or variables that the scope can process. By default, the container thread pool optimizes performance by determinng the maximum number of threads to use. -Set `maxConcurrency` to `1` to cause the scope to process requests one at a time. +Setting `maxConcurrency` to `1` causes the scope to process requests one at a time. -See xref:execution-engine.adoc#backpressure[Back-Pressure Management] for details about Mule behavior after reaching the maximum concurrency value. +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. |=== == Async Scopes versus Subflows -Unlike a subflow, an Async scope: +Unlike the xref:flow-component.adoc[Subflow}, the Async scope: * Does not inherit the exception strategy of the main flow. + -To handle errors in an Async scope, use the Try scope. +To handle errors in an Async scope, use the xref:try-scope-concept.adoc[Try scope]. + * Processes messages asynchronously. * Does not pass data back to the main flow. * Exists inline with the main flow thread. -* Is not called by a Flow Reference component. -* Is not reusable +* Is not called by a xref:flowref-about.adoc[Flow Reference] component. +* Is not reusable. -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. -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. +// TODO: DOES THIS INFO BELONG IN THIS SECTION? +// TODO: Do we have a recommendation here? +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. So 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. == Example Async Scope Configuration From 46b9f445866417b3f922a37d52a62ffe5a3622fb Mon Sep 17 00:00:00 2001 From: dukesphere Date: Tue, 11 Oct 2022 14:14:02 -0700 Subject: [PATCH 2/3] W-11599413-asyncScope-duke --- modules/ROOT/pages/async-scope-reference.adoc | 72 ++++++++++--------- 1 file changed, 39 insertions(+), 33 deletions(-) diff --git a/modules/ROOT/pages/async-scope-reference.adoc b/modules/ROOT/pages/async-scope-reference.adoc index 6f18c3c30d..2fb7a063b9 100644 --- a/modules/ROOT/pages/async-scope-reference.adoc +++ b/modules/ROOT/pages/async-scope-reference.adoc @@ -4,50 +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 the Async scope and processing takes places with in Async. The flow does wait for the last processor within the asynchronous flow to completes its tasks. +The Async scope provides a mechanism for processing the Mule event simultaneously with the main flow. Processing within the scope does not block the execution of downstream components outside of Async. The flow does not wait for the last processor within the asynchronous flow to completes its tasks. 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. -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. - image::async-scope-schematic.png[Async+scope+schematic] -Because the Async scope executes in a "fire and forget" manner, the result of the processing within the scope is not available in the main flow. Mule variables created within the flow do not propagate to the main flow, nor do any changes to the payload or other parts of the Mule event. +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. -== Reference - -Async scopes are configurable. +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]. -[%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. Sets the maximum number of concurrent Mule messages or variables that the scope can process. By default, the container thread pool optimizes performance by determinng the maximum number of threads to use. - -Setting `maxConcurrency` to `1` causes the scope to process requests one at a time. - -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. -|=== - -== Async Scopes versus Subflows - -Unlike the xref:flow-component.adoc[Subflow}, 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]. -+ +//// +// 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 xref:flowref-about.adoc[Flow Reference] component. -* Is not reusable. +* Is not called by a Flow Reference component. +* Is not reusable +//// +[[mutable_objects]] +== Async Scope Behavior with Mutable Objects -// TODO: DOES THIS INFO BELONG IN THIS SECTION? -// TODO: Do we have a recommendation here? -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. So 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. +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. +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 @@ -91,8 +80,25 @@ 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. Sets the maximum number of concurrent Mule messages or variables that the scope can process. By default, the container thread pool optimizes performance by determinng 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[] From 25c236a8d54d749c513a1c00ea2a95d1743df229 Mon Sep 17 00:00:00 2001 From: dukesphere Date: Tue, 11 Oct 2022 15:24:18 -0700 Subject: [PATCH 3/3] W-11599413-asyncScope-duke --- modules/ROOT/pages/async-scope-reference.adoc | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/modules/ROOT/pages/async-scope-reference.adoc b/modules/ROOT/pages/async-scope-reference.adoc index 2fb7a063b9..4e59a62341 100644 --- a/modules/ROOT/pages/async-scope-reference.adoc +++ b/modules/ROOT/pages/async-scope-reference.adoc @@ -4,7 +4,7 @@ include::_attributes.adoc[] endif::[] :keywords: Async, scopes, studio, anypoint -The Async scope provides a mechanism for processing the Mule event simultaneously with the main flow. Processing within the scope does not block the execution of downstream components outside of Async. The flow does not wait for the last processor within the asynchronous flow to completes its tasks. +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 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. @@ -88,11 +88,14 @@ Async scopes are configurable. |=== | Field | XML | Default | Description | *Display Name* | `name` | Async | Name for the Async scope. -| *Max Concurrency* | `maxConcurrency` | See description. | Optional. Sets the maximum number of concurrent Mule messages or variables that the scope can process. By default, the container thread pool optimizes performance by determinng the maximum number of threads to use. +| *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. +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. |===