[jboss-cvs] JBoss Messaging SVN: r6875 - in trunk/docs/user-manual/en: modules and 1 other directory.
jboss-cvs-commits at lists.jboss.org
jboss-cvs-commits at lists.jboss.org
Tue May 19 07:25:43 EDT 2009
Author: timfox
Date: 2009-05-19 07:25:43 -0400 (Tue, 19 May 2009)
New Revision: 6875
Added:
trunk/docs/user-manual/en/modules/send-guarantees.xml
Modified:
trunk/docs/user-manual/en/master.xml
trunk/docs/user-manual/en/modules/interoperability.xml
trunk/docs/user-manual/en/modules/perf-tuning.xml
Log:
added send guarantees chapter
Modified: trunk/docs/user-manual/en/master.xml
===================================================================
--- trunk/docs/user-manual/en/master.xml 2009-05-19 10:36:21 UTC (rev 6874)
+++ trunk/docs/user-manual/en/master.xml 2009-05-19 11:25:43 UTC (rev 6875)
@@ -34,6 +34,7 @@
<!ENTITY queue-attributes SYSTEM "modules/queue-attributes.xml">
<!ENTITY scheduled-messages SYSTEM "modules/scheduled-messages.xml">
<!ENTITY security SYSTEM "modules/security.xml">
+ <!ENTITY send-guarantees SYSTEM "modules/send-guarantees.xml">
<!ENTITY thread-pooling SYSTEM "modules/thread-pooling.xml">
<!ENTITY undelivered-messages SYSTEM "modules/undelivered-messages.xml">
<!ENTITY using-core SYSTEM "modules/using-core.xml">
@@ -62,6 +63,7 @@
&security;
&wildcard-syntax;
&persistence;
+ &send-guarantees;
&connection-ttl;
&management;
&large-messages;
Modified: trunk/docs/user-manual/en/modules/interoperability.xml
===================================================================
--- trunk/docs/user-manual/en/modules/interoperability.xml 2009-05-19 10:36:21 UTC (rev 6874)
+++ trunk/docs/user-manual/en/modules/interoperability.xml 2009-05-19 11:25:43 UTC (rev 6875)
@@ -18,6 +18,5 @@
<para>Make sure this file is in the classpath along with the StompConnect jar and the JBoss
Messaging jars and simply run <literal>java
org.codehaus.stomp.jms.Main</literal>.</para>
- <para>JBoss Messaging is now available for Stomp clients to connect to.</para>
</section>
</chapter>
Modified: trunk/docs/user-manual/en/modules/perf-tuning.xml
===================================================================
--- trunk/docs/user-manual/en/modules/perf-tuning.xml 2009-05-19 10:36:21 UTC (rev 6874)
+++ trunk/docs/user-manual/en/modules/perf-tuning.xml 2009-05-19 11:25:43 UTC (rev 6875)
@@ -1,7 +1,20 @@
<?xml version="1.0" encoding="UTF-8"?>
<chapter id="perf-tuning">
<title>Performance Tuning</title>
- <para>blah</para>
+ <para>In this chapter we'll discuss how to tune JBoss Messaging for optimum performance.</para>
+ <section>
+ <title>Tuning the journal</title>
+ <para></para>
+ </section>
+ <section>
+ <title>Tuning JMS</title>
+ <para></para>
+ </section>
+ <section>
+ <title>Tuning the VM</title>
+ <para></para>
+ </section>
+
+
-
</chapter>
Added: trunk/docs/user-manual/en/modules/send-guarantees.xml
===================================================================
--- trunk/docs/user-manual/en/modules/send-guarantees.xml (rev 0)
+++ trunk/docs/user-manual/en/modules/send-guarantees.xml 2009-05-19 11:25:43 UTC (rev 6875)
@@ -0,0 +1,129 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<chapter id="send-guarantees">
+ <title>Guarantees of Transactional and Non-Transactional Sends and Asynchronous Send
+ Acknowledgements</title>
+ <section>
+ <title>Guarantees of Transaction Completion</title>
+ <para>When committing or rolling back a transaction with JBoss Messaging, the request to
+ commit or rollback is sent to the server, and the call will block on the client side
+ until a response has been received from the server that the commit or rollback was
+ executed.</para>
+ <para>When the commit or rollback is received on the server, it will be committed to the
+ journal, and depending on the value of the parameter <literal
+ >journal-sync-transactional</literal> the server will ensure that the commit or
+ rollback is durably persisted to storage before sending the response back to the client.
+ If this parameter has the value <literal>false</literal> then commit or rollback may not
+ actually get persisted to storage until some time after the response has been sent to
+ the client. In event of server failure this may mean the commit or rollback never gets
+ persisted to storage. The default value of this parameter is <literal>true</literal> so
+ the client can be sure all transaction commits or rollbacks have been persisted to
+ storage by the time the call to commit or rollback returns.</para>
+ <para>Setting this parameter to <literal>false</literal> can improve performance at the
+ expense of some loss of transaction durability.</para>
+ <para>This parameter is set in <literal>jbm-configuration.xml</literal></para>
+ </section>
+ <section id="non-transactional-sends">
+ <title>Guarantees of Non Transactional Message Sends</title>
+ <para>If you are sending messages to a server using a non transacted session, JBoss
+ Messaging can be configured to block the call to send until the message has definitely
+ reached the server, and a response has been sent back to the client. This can be
+ configured individually for persistent and non-persistent messages, and is determined by
+ the following two parameters:</para>
+ <itemizedlist>
+ <listitem>
+ <para><literal>BlockOnPersistentSend</literal>. If this is set to <literal
+ >true</literal> then all calls to send for persistent messages on non
+ transacted sessions will block until the message has reached the server, and a
+ response has been sent back. The default value is <literal>false</literal>.
+ </para>
+ </listitem>
+ <listitem>
+ <para><literal>BlockOnNonPersistentSend</literal>. If this is set to <literal
+ >true</literal> then all calls to send for non-persistent messages on non
+ transacted sessions will block until the message has reached the server, and a
+ response has been sent back. The default value is <literal
+ >false</literal>.</para>
+ </listitem>
+ </itemizedlist>
+ <para>Setting block on sends to <literal>true</literal> can reduce performance since each
+ send requires a network round trip before the next send can be performed. This means the
+ performance of sending messages will be limited by the network round trip time (RTT) of
+ your network, rather than the bandwidth of your network. For better performance we
+ recommend either batching many messages sends together in a transaction since with a
+ transactional session, only the commit / rollback blocks not every send, or, using JBoss
+ Messaging's advanced <emphasis>asynchronous send acknowledgements</emphasis>
+ feature.</para>
+ <para>If you are using JMS and you're using the JMS service on the server to load your JMS
+ connection factory instances into JNDI then these parameters can be configured in
+ <literal>jbm-jms.xml</literal> using the elements <literal
+ >send-p-messages-synchronously</literal> and <literal
+ >send-np-messages-synchronously</literal>. If you're using JMS but not using JNDI
+ then you can set these values directly on the <literal>JBossConnectionFactory</literal>
+ instance using the appropriate setter methods.</para>
+ <para>If you're using core you can set these values directly on the <literal
+ >ClientSessionFactory</literal> instance using the appropriate setter
+ methods.</para>
+ <para>When the server receives a message sent from a non transactional session, and that
+ message is persistent and the message is routed to at least one durable queue, then the
+ server will persist the message in permanent storage. If the journal parameter <literal
+ >journal-sync-non-transactional</literal> is set to <literal>true</literal> the
+ server will not send a response back to the client until the message has been persisted
+ and the server has a guarantee that the data has been persisted to disk. The default
+ value for this parameter is <literal>false</literal>.</para>
+ </section>
+ <section>
+ <title>Guarantees of Non Transactional Acknowledgements</title>
+ <para>If you are acknowledging the delivery of a message at the client side using a non
+ transacted session, JBoss Messaging can be configured to block the call to acknowledge
+ until the acknowledge has definitely reached the server, and a response has been sent
+ back to the client. This is configured with the parameter <literal
+ >BlockOnAcknowledge</literal>. If this is set to <literal>true</literal> then all
+ calls to acknowledge on non transacted sessions will block until the acknowledge has
+ reached the server, and a response has been sent back. The default value is <literal
+ >false</literal></para>
+ </section>
+ <section>
+ <title>Asynchronous Send Acknowledgements</title>
+ <para>If you are using a non transacted session but want a guarantee that every message sent
+ to the server has reached it, then, as discussed in section <xref
+ linkend="non-transactional-sends"/>, you can configure JBoss Messaging to block the
+ call to send until the server has received the message, persisted it and sent back a
+ response. This works well but has a severe performance penalty - each call to send needs
+ to block for at least the time of a network round trip (RTT) - the performance of
+ sending is thus limited by the latency of the network, <emphasis>not</emphasis> limited
+ by the network bandwidth.</para>
+ <para>Let's do a little bit of maths to see how severe that is. We'll consider a standard
+ 1Gib ethernet with a network round trip between the server and the client of 0.25
+ ms.</para>
+ <para>With a RTT of 0.25 ms, the client can send <emphasis>at most</emphasis> 1000/ 0.25 =
+ 4000 messages per second if it blocks on each message send.</para>
+ <para>If each message is < 1500 bytes and a standard 1500 bytes MTU size is used on the
+ network, then a 1GiB network has a <emphasis>theoretical</emphasis> upper limit of (1024
+ * 1024 * 1024 / 8) / 1500 = 89478 messages per second if messages are sent without
+ blocking! These figures aren't an exact science but you can clearly see that being
+ limited by network RTT can have serious effect on performance.</para>
+ <para>To remedy this, JBoss Messaging provides an advanced new feature called
+ <emphasis>asynchronous send acknowledgements</emphasis>. With this feature, JBoss
+ Messaging can be configured to send messages without blocking on one direction and
+ asynchronously getting acknowledgement from the server that the messages were received
+ in a separate stream. By de-coupling the send from the acknowledgement of the send, the
+ system is not limited by the network RTT, but is limited by the network bandwidth.
+ Consequently much throughput can be achieved than is possible using a blocking approach,
+ while at the same time having absolute guarantees that messages have successfully
+ reached the server.</para>
+ <section>
+ <title>Asynchronous Send Acknowledgements</title>
+ <para>To use the feature using the core API, you implement the interface <literal
+ >org.jboss.messaging.core.client.SendAcknowledgementHandler</literal> and set a
+ handler instance on your <literal>ClientSession</literal>.</para>
+ <para>Then, you just send messages as normal using your <literal
+ >ClientSession</literal>, and as messages reach the server, the server will send
+ back an acknowledgment of the send asynchronously, and some time later you are
+ informed at the client side by JBoss Messaging calling your handler's <literal
+ >sendAcknowledged(ClientMessage message)</literal> method, passing in a
+ reference to the message that was sent.</para>
+ <para>Please see the send acknowledgements example for a full working example
+ [LINK]</para>
+ </section>
+ </section>
+</chapter>
More information about the jboss-cvs-commits
mailing list