[jboss-cvs] JBoss Messaging SVN: r6814 - trunk/docs/user-manual/en/modules.
jboss-cvs-commits at lists.jboss.org
jboss-cvs-commits at lists.jboss.org
Fri May 15 16:56:11 EDT 2009
Author: clebert.suconic at jboss.com
Date: 2009-05-15 16:56:11 -0400 (Fri, 15 May 2009)
New Revision: 6814
Modified:
trunk/docs/user-manual/en/modules/paging.xml
Log:
paging chapter
Modified: trunk/docs/user-manual/en/modules/paging.xml
===================================================================
--- trunk/docs/user-manual/en/modules/paging.xml 2009-05-15 17:49:11 UTC (rev 6813)
+++ trunk/docs/user-manual/en/modules/paging.xml 2009-05-15 20:56:11 UTC (rev 6814)
@@ -1,8 +1,166 @@
<?xml version="1.0" encoding="UTF-8"?>
<chapter id="paging">
<title>Paging</title>
- <para>blah.</para>
-
+ <para>JBoss Messaging pages messages on disk, avoiding this way running out of Memory.</para>
+ <para>Messages are regularly routed to their queues, persisted on disk for eventual recovery in
+ case of server failure, sent to consumers or kept in memory if the consumers are not ready
+ to read the messages.</para>
+ <para>If there are no consumers reading the queues, the memory could build up beyond the memory
+ capacity of the server. We prevent this problem by buffering messages on disk before the
+ used memory gets too high.</para>
+ <para>When in page mode, we store messages into files, before routing at the address level. Each
+ file is called a <literal>page-file</literal>, and each page has a maximum site. When the
+ page-file hits the maximum size, we close that file and open a new page-file.</para>
+ <para>Messages are aways read out of the paging system in batches of pages. We read a file when
+ there is enough space in memory. That means we never depage more messages than it would fit
+ in memory.</para>
+ <para>There are two page modes supported by JBoss Messaging. Global Page Mode (<xref
+ linkend="paging.global.mode"/>) and Address Paging Mode <xref
+ linkend="paging.address.mode"/></para>
+ <section>
+ <title>Memory Size</title>
+ <para>We compute a memory estimate for every message stored in memory computing this level
+ both at a global and address level.</para>
+ </section>
+ <section id="paging.global.mode">
+ <title>Global Paging Mode</title>
+ <para>When the total memory reaches the max configured size, the entire server enters in
+ page mode, JBoss Messaging starts to page messages for every address.</para>
+ <para>As messages are acknowledged, we start recovering them from the disk (we call this
+ operation as depaging) as soon as the memory is bellow a watermark size.</para>
+ <para>The maximum memory is determined by <literal>paging-max-global-size-bytes</literal>,
+ and the watermark is configured by <literal>paging-global-watermark-size</literal>
+ (<xref linkend="paging.main.config"/>). </para>
+ </section>
+ <section id="paging.address.mode">
+ <title>Address Paging Mode</title>
+ <para>It is possible to configured what's the maximum size at any given address. On this
+ case only the destination configured with that maximum size will be in page mode.</para>
+ <programlisting> <address-settings>
+ <address-setting match="jms.someaddress">
+ <max-size-bytes>-1</max-size-bytes>
+ <page-size-bytes>10485760</page-size-bytes>
+ <drop-messages-when-full>10485760</drop-messages-when-full>
+ </address-setting>
+ </address-settings>
+ </programlisting>
+ <para>This is the list of available parameters on the address settings.</para>
+ <para>
+ <table frame="topbot">
+ <title/>
+ <tgroup cols="3">
+ <colspec colname="c1" colnum="1"/>
+ <colspec colname="c2" colnum="2"/>
+ <colspec colname="c3" colnum="3"/>
+ <thead>
+ <row>
+ <entry>Property Name</entry>
+ <entry>Description</entry>
+ <entry>Default</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry><literal>max-size</literal></entry>
+ <entry>What's the max memory the address could have before entering on
+ page mode.</entry>
+ <entry>-1 (disabled)</entry>
+ </row>
+ <row>
+ <entry><literal>page-size-bytes</literal></entry>
+ <entry>The size of each page file used on the paging system</entry>
+ <entry>10MB (10 * 1024 * 1024 bytes)</entry>
+ </row>
+ <row>
+ <entry><literal>drop-messages-when-full</literal></entry>
+ <entry>if true, messages are dropped instead of paged when <literal
+ >used-memory</literal> is greater than <literal
+ >max-size</literal></entry>
+ <entry>false</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ </para>
+ <section>
+ <title>Configuration</title>
+ <para>All the configuratio for address paging mode is contained into :</para>
+ </section>
+ </section>
+ <section id="paging.main.config">
+ <title>Configuration</title>
+ <para>Global paging parameters are specified on the main configuration file. (<xref
+ linkend="usingserver.mainconfig"/>)</para>
+ <programlisting><configuration xmlns="urn:jboss:messaging"
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="urn:jboss:messaging /schema/jbm-configuration.xsd">
-
+...
+
+ <paging-max-global-size-bytes>20485760</paging-max-global-size-bytes>
+ <paging-global-watermark-size>1048576</paging-global-watermark-size>
+
+... </programlisting>
+ <para>
+ <table frame="topbot">
+ <title/>
+ <tgroup cols="3">
+ <colspec colname="c1" colnum="1"/>
+ <colspec colname="c2" colnum="2"/>
+ <colspec colname="c3" colnum="3"/>
+ <thead>
+ <row>
+ <entry>Property Name</entry>
+ <entry>Description</entry>
+ <entry>Default</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry><literal>paging-directory</literal></entry>
+ <entry>Where page files are stored. JBoss Messaging will create one
+ folder for each address being paged under this configured
+ location.</entry>
+ <entry>data/paging</entry>
+ </row>
+ <row>
+ <entry><literal>paging-max-global-size-bytes</literal></entry>
+ <entry>JBoss Messaging enters into global page mode as soon as the total
+ memory consumed by messages hits this value.(<xref
+ linkend="paging.global.mode"/>) </entry>
+ <entry>-1 (disabled)</entry>
+ </row>
+ <row>
+ <entry><literal>paging-global-watermark-size</literal></entry>
+ <entry>The watermark used to determine when we start depaging. This
+ value should be equivalent to a page-file size.</entry>
+ <entry>10MB (10 * 1024 * 1024 bytes)</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ </para>
+ </section>
+ <section>
+ <title>Caution with Addresses with Multiple Queues</title>
+ <para>When a message is sent to multiple queues, on JMS Topics, or on Addresses with
+ multiple queues, the same message is shared as a reference between multiple queues. The
+ message only leaves the memory when it is consumed in all the queus.</para>
+ <para>For example:</para>
+ <itemizedlist>
+ <listitem>
+ <para>An Address has 10 queues </para>
+ </listitem>
+ <listitem>
+ <para>It only has 9 consumers. One of the Queues is leaving messages on the
+ memory.</para>
+ </listitem>
+ <listitem>
+ <para> Messages are continuously being produced</para>
+ </listitem>
+ </itemizedlist>
+ <para>This will make memory to build on the server, and start paging mode eventually. Once
+ the Address enters in page mode, messages will be stored on disk and not routed to
+ queues until messages are consumed on that queue.</para>
+ </section>
</chapter>
More information about the jboss-cvs-commits
mailing list