This is an automated email from the ASF dual-hosted git repository.
schultz pushed a commit to branch 8.5.x
in repository https://gitbox.apache.org/repos/asf/tomcat.git
The following commit(s) were added to refs/heads/8.5.x by this push:
new df39f20 Fix https://bz.apache.org/bugzilla/show_bug.cgi?id=62723
df39f20 is described below
commit df39f2024023fcc07cfbc69cc6b0999cb5560a68
Author: Christopher Schultz <ch...@christopherschultz.net>
AuthorDate: Tue Aug 4 17:10:01 2020 -0400
Fix https://bz.apache.org/bugzilla/show_bug.cgi?id=62723
Clarify the effects of some cluster channelSendOptions.
Patch provided by Mitch Claborn.
---
webapps/docs/changelog.xml | 4 ++++
webapps/docs/cluster-howto.xml | 22 +++++++++++++++++----
webapps/docs/config/cluster.xml | 44 ++++++++++++++++++++++++++++++++++++++++-
3 files changed, 65 insertions(+), 5 deletions(-)
diff --git a/webapps/docs/changelog.xml b/webapps/docs/changelog.xml
index dff49fb..ac90ee8 100644
--- a/webapps/docs/changelog.xml
+++ b/webapps/docs/changelog.xml
@@ -99,6 +99,10 @@
Clean-up / standardize the XSL files used to generate the
documentation.
PR provided by John Bampton. (markt)
</fix>
+ <fix>
+ <bug>62723</bug>: Clarify the effects of some options for cluster
+ <code>channelSendOptions</code>. Patch provided by Mitch Claborn.
+ (schultz)
</changelog>
</subsection>
</section>
diff --git a/webapps/docs/cluster-howto.xml b/webapps/docs/cluster-howto.xml
index cce6726..09cdb2c 100644
--- a/webapps/docs/cluster-howto.xml
+++ b/webapps/docs/cluster-howto.xml
@@ -217,10 +217,24 @@ should be completed:</p>
sent over the wire and reinstantiated on all the other cluster nodes.
Synchronous vs. asynchronous is configured using the
<code>channelSendOptions</code>
flag and is an integer value. The default value for the
<code>SimpleTcpCluster/DeltaManager</code> combo is
- 8, which is asynchronous. You can read more on the <a
href="tribes/introduction.html">send flag(overview)</a> or the
- <doc path="/api/org/apache/catalina/tribes/Channel.html">send
flag(javadoc)</doc>.
- During async replication, the request is returned before the data has been
replicated. async replication yields shorter
- request times, and synchronous replication guarantees the session to be
replicated before the request returns.
+ 8, which is asynchronous.
+ See the <a
href="config/cluster.html#SimpleTcpCluster_Attributes">configuration
reference</a>
+ for more discussion on the various <code>channelSendOptions</code> values.
+</p>
+<p>
+ For convenience, <code>channelSendOptions</code> can be set by name(s)
rather than integer,
+ which are then translated to their integer value upon startup. The valid
option names are:
+ "asynchronous" (alias "async"), "byte_message" (alias "byte"),
"multicast", "secure",
+ "synchronized_ack" (alias "sync"), "udp", "use_ack". Use comma to
separate multiple names,
+ e.g. pass "async, multicast" for the options
+ <code>SEND_OPTIONS_ASYNCHRONOUS | SEND_OPTIONS_MULTICAST</code>.
+</p>
+<p>
+ You can read more on the <a href="tribes/introduction.html">send
flag(overview)</a> or the
+ <doc path="/api/org/apache/catalina/tribes/Channel.html">send
flag(javadoc)</doc>.
+ During async replication, the request is returned before the data has been
replicated. async
+ replication yields shorter request times, and synchronous replication
guarantees the session
+ to be replicated before the request returns.
</p>
</section>
diff --git a/webapps/docs/config/cluster.xml b/webapps/docs/config/cluster.xml
index f6cd407..9211edd 100644
--- a/webapps/docs/config/cluster.xml
+++ b/webapps/docs/config/cluster.xml
@@ -143,7 +143,49 @@ Tomcat cluster. These include:</p>
<br/>
Note that if you use ASYNC messaging it is possible for update messages
for a session to be processed by the receiving nodes in a different order
- to the order in which they were sent.</p>
+ to the order in which they were sent.
+ </p>
+ <p>
+ The various <code>channelSendOptions</code> values offer a tradeoff
+ between throughput on the sending node and the reliability of
+ replication should the sending or receiving node(s) fail. Here are
+ some common options. "Message" could be any message sent between nodes,
+ but only session-change messages are considered, here.
+ </p>
+ <p>
+ <code>channelSendOptions="8"</code> /
<code>channelSendOptions="async"</code>
+ As far as the sender is concerned, the message is "sent"
+ as soon as it has been placed in the queue on the sender for
+ transmission to the other nodes. The message may not reach any or all
+ of the recipient nodes and may not be successfully processed on any
+ nodes that it does reach. This option offers the highest throughput on
+ the sender but the least reliability, as the triggering request will
+ complete without any knowledge of the success/failure of the session
+ replication.
+ </p>
+ <p>
+ <code>channelSendOptions="2"</code> /
<code>channelSendOptions="use_ack"</code>
+ The sender will block the completion of the current request until all
+ of the receiving nodes have acknowledged that they have received the
+ message, but have not necessarily processed that message. This option
+ will result in lower throughput on the sending node, because the
message
+ must be transmitted and the acknowledgement received, but the
+ reliability is greater than the asynchronous model.
+ </p>
+ <p>
+ <code>channelSendOptions="6"</code> /
<code>channelSendOptions="sync,use_ack"</code>
+ The sender will block the completion of the current request until
+ all of the receiving nodes have acknowledged that they have received
+ <u>and</u> processed the message. This option will have the lowest
+ throughput (of these three) but the greatest reliability.
+ </p>
+ <p>
+ You may also set these options as a comma separated string, e.g. "async,
multicast", which
+ will be translated into <code>Channel.SEND_OPTIONS_ASYNCHRONOUS |
Channel.SEND_OPTIONS_MULTICAST</code>
+ <br/>
+ The valid option names are "asynchronous" (alias "async"),
"byte_message" (alias "byte")
+ , "multicast", "secure", "synchronized_ack" (alias "sync"), "udp",
"use_ack"
+ </p>
</attribute>
<attribute name="channelStartOptions" required="false">
<p>Sets the start and stop flags for the <Channel> object used by
the cluster.
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscr...@tomcat.apache.org
For additional commands, e-mail: dev-h...@tomcat.apache.org
