[jboss-cvs] JBoss Messaging SVN: r6740 - trunk/docs/user-manual/en/modules.
jboss-cvs-commits at lists.jboss.org
jboss-cvs-commits at lists.jboss.org
Tue May 12 08:59:24 EDT 2009
Author: timfox
Date: 2009-05-12 08:59:24 -0400 (Tue, 12 May 2009)
New Revision: 6740
Modified:
trunk/docs/user-manual/en/modules/persistence.xml
trunk/docs/user-manual/en/modules/using-core.xml
Log:
more on docs
Modified: trunk/docs/user-manual/en/modules/persistence.xml
===================================================================
--- trunk/docs/user-manual/en/modules/persistence.xml 2009-05-12 10:54:14 UTC (rev 6739)
+++ trunk/docs/user-manual/en/modules/persistence.xml 2009-05-12 12:59:24 UTC (rev 6740)
@@ -1,8 +1,212 @@
<?xml version="1.0" encoding="UTF-8"?>
<chapter id="persistence">
<title>Persistence</title>
- <para>blah</para>
-
-
-
+ <para>In this chapter we will describe how persistence works with JBoss Messaging, and you will
+ discover how to configure it.</para>
+ <para>JBoss Messaging includes a high performance journal to provide excellent persistent
+ message performance. By managing its own persistence JBoss Messaging does not require a
+ relational or other database to perform that function. This means that JBoss Messaging can
+ provide much higher persistent rates than are available using a database for persistence
+ since the journal is optimised for its goal, whereas a database is for general purpose data
+ persistence.</para>
+ <para>A JBoss Messaging journal is an <emphasis>append only</emphasis> journal. It consists of a
+ set of files on disk. Each file is of a fixed size and is initially filled with padding. As
+ operations are performed on the server, e.g. add message, update message, delete message, a
+ record is appended to the journal for each operation.</para>
+ <para>Operation records are only added to the end of the journal. By only adding records to the
+ end of the journal, we minimise disk head movement since we're not doing random access
+ operations.</para>
+ <para>When one journal file is full we move to the next one. We typically choose each journal
+ file to be about the right size to fit on a disk cylinder. Modern disk topologies are
+ complex and we are not in control over which cylinder(s) the file is mapped onto so this is
+ not an exact science. By minimising the number of disk cylinders the file is using, we can
+ minimise the amount of disk head movement, since an entire disk cyclinder is accessible
+ simply by the disk rotating - the head does not have to move.</para>
+ <para>As delete records are added to the journal, JBoss Messaging has a sophisticated file
+ garbage collection algorithm which can determine if a particular journal file is needed any
+ more - i.e. has all it's data been deleted in the same or other files. If so, the file can
+ be reclaimed and re-used. </para>
+ <para>JBoss Messaging also has a compaction algorithm which removes dead space from the journal
+ and compresses up the data so it takes up less files on disk.</para>
+ <para>The journal is also fully local and XA transaction capable.</para>
+ <para>The majority of the journal is written as common code in Java, and we abstract out the
+ interaction with the actual file system in a thin abstraction layer. We ship JBoss Messaging
+ with two implementations of that abstraction layer:</para>
+ <itemizedlist>
+ <listitem>
+ <para>Java NIO.</para>
+ <para>The first implementation uses standard Java NIO to interface with the file system.
+ This provides very good performance and runs on any platform for which there is a
+ JDK 5+ JVM.</para>
+ </listitem>
+ <listitem>
+ <para>Linux Asynchronous IO (AIO).</para>
+ <para>The second implementation uses a thin JNI wrapper to talk to the Linux
+ asynchronous IO library from Java. In a highly concurrent environment, AIO can
+ provide better overall persistent throughput than is available with Java NIO since
+ it does not require each individual transaction boundary to be synced to disk. Most
+ disks can only support a limited number of syncs per second, so a syncing approach
+ does not scale well with the number of concurrent transactions that need to commit.
+ With AIO, JBoss Messaging will be called back when the data has made it to disk,
+ allowing us to avoid explicit syncs altogether and simply send back confirmation of
+ completion when AIO informs us that the data has been persisted.</para>
+ <para>The AIO journal is only available when running Linux kernel 2.6 or later and after
+ having installed libaio (if it's not already installed). For instructions on how to
+ install libaio please see [LINK]</para>
+ </listitem>
+ </itemizedlist>
+ <para>The standard JBoss Messaging core server uses two instances of the journal:</para>
+ <itemizedlist>
+ <listitem>
+ <para>Bindings journal.</para>
+ <para>This journal is used to store bindings related data. That includes the set of
+ queues that are deployed on the server and their attributes. It also stores data
+ such as id sequence counters. </para>
+ <para>The bindings journal is always a NIO journal as it is typically low throughput
+ compared to the message journal.</para>
+ </listitem>
+ <listitem>
+ <para>Message journal.</para>
+ <para>This journal instance stores all message related data, including the message
+ themselves and also duplicate id caches.</para>
+ <para>By default JBoss Messaging will try and use an AIO journal. If AIO is not
+ available, e.g. the platform is not Linux with the correct kernel version or AIO has
+ not been installed then it will automatically fall back to using Java NIO which is
+ available on any Java platform.</para>
+ </listitem>
+ </itemizedlist>
+ <para>For large messages, JBoss Messaging persists them outside the message journal. This is
+ discussed in the chapter on large messages [LINK]</para>
+ <para>JBoss Messaging also pages messages to disk in low memory situations. This is discussed in
+ the chapter on paging [LINK]</para>
+ <para>If no persistence is required at all, JBoss Messaging can also be configured not to
+ persist any data at all to storage.</para>
+ <section>
+ <title>Configuring the bindings journal</title>
+ <para>The bindings journal is configured using the following attributes in <literal
+ >jbm-configuration.xml</literal></para>
+ <itemizedlist>
+ <listitem>
+ <para><literal>bindings-directory</literal></para>
+ <para>This is the directory in which the bindings journal lives. The default value
+ is <literal>data/bindings</literal>.</para>
+ </listitem>
+ <listitem>
+ <para><literal>create-bindings-dir</literal></para>
+ <para>If this is set to <literal>true</literal> then the bindings directory will be
+ automatically created at the location specified in <literal
+ >bindings-directory</literal> if it does not already exist. The default
+ value is <literal>true</literal></para>
+ </listitem>
+ </itemizedlist>
+ </section>
+ <section>
+ <title>Configuring the message journal</title>
+ <para>The message journal is configured using the following attributes in <literal
+ >jbm-configuration.xml</literal></para>
+ <itemizedlist>
+ <listitem>
+ <para><literal>journal-directory</literal></para>
+ <para>This is the directory in which the message journal lives. The default value is
+ <literal>data/journal</literal>.</para>
+ <para>For the best performance, we recommend the journal is located on its own
+ volume in order to minimise disk head movement. If the journal is on a volume
+ which is shared with other processes which might be writing other files (e.g.
+ bindings journal, database, or transaction co-ordinator) then the disk head may
+ well be moving rapidly between these files as it writes them, thus reducing
+ performance.</para>
+ <para>When the message journal is stored on a SAN we recommend each journal instance
+ that is stored on the SAN is given its own LUN (logical unit).</para>
+ </listitem>
+ <listitem>
+ <para><literal>create-journal-dir</literal></para>
+ <para>If this is set to <literal>true</literal> then the journal directory will be
+ automatically created at the location specified in <literal
+ >journal-directory</literal> if it does not already exist. The default value
+ is <literal>true</literal></para>
+ </listitem>
+ <listitem>
+ <para><literal>journal-type</literal></para>
+ <para>Valid values are <literal>NIO</literal> or <literal>AIO</literal>.</para>
+ <para>Choosing <literal>NIO</literal> chooses the Java NIO journal. Choosing
+ <literal>AIO</literal> chooses the Linux asynchronous IO journal. If you
+ choose <literal>AIO</literal> but are not running Linux or you you do not have
+ libaio installed then JBoss Messaging will detect this and automatically fall
+ back to using <literal>NIO</literal>.</para>
+ </listitem>
+ <listitem>
+ <para><literal>journal-sync-transactional</literal></para>
+ <para>If this is set to true then JBoss Messaging will wait for all transaction data
+ to be persisted to disk on a commit before sending a commit response OK back to
+ the client. The default value is <literal>true</literal>.</para>
+ </listitem>
+ <listitem>
+ <para><literal>journal-sync-non-transactional</literal></para>
+ <para>If this is set to true then JBoss Messaging will wait for any non
+ transactional data to be persisted to disk on a send before sending the response
+ back to the client. The default value for this is <literal
+ >false</literal>.</para>
+ </listitem>
+ <listitem>
+ <para><literal>journal-file-size</literal></para>
+ <para>The size of each journal file in bytes. The default value for this is 10485760
+ bytes (10MiB).</para>
+ </listitem>
+ <listitem>
+ <para><literal>journal-min-files</literal></para>
+ <para>The minimum number of files the journal will maintain. When JBoss Messaging
+ starts and there is no initial message data, JBoss Messaging will pre-create
+ <literal>journal-min-files</literal> number of files.</para>
+ <para>Creating journal files and filling them with padding is a fairly expensive
+ operation and we want to minimise doing this at run-time as files get filled. By
+ precreating files, as one is filled the journal can immediately resume with the
+ next one without pausing to create it.</para>
+ <para>Depending on how much data you expect your queues to contain at steady state
+ you should tune this number of files to match that total amount of data.</para>
+ </listitem>
+ <listitem>
+ <para><literal>journal-max-aio</literal></para>
+ <para>When using an AIO journal, write requests are queued up before being submitted
+ to AIO for execution. Then when AIO has completed them it calls JBoss Messaging
+ back. This parameter controls the maximum number of write requests that can be
+ in the AIO queue at any one time. If the queue becomes full then writes will
+ block until space is freed up. This parameter has no meaning when using the NIO
+ journal.</para>
+ </listitem>
+ <listitem>
+ <para><literal>journal-buffer-reuse-size</literal></para>
+ <para>Creaing direct byte buffers is an expensive operation, so the journal will
+ attempt to re-use any buffers with a size less than this setting, in bytes. If
+ this value is set to <literal>-1</literal> then the journal will not attempt to
+ re-use any buffers. This setting only takes effect if the journal is <literal
+ >AIO</literal>. The default value for this setting is <literal
+ >1024</literal> bytes.</para>
+ </listitem>
+ </itemizedlist>
+ </section>
+ <section>
+ <title>Installing AIO</title>
+ <para>If you are running JBoss Messaging using Linux Kernel 2.6 or later, we highly
+ recommend you use the <literal>AIO</literal> journal for the best persistence
+ performance especially under high concurrency.</para>
+ <para>It's not possible to use the AIO journal under other operating systems or earlier
+ versions of the Linux kernel.</para>
+ <para>If you are running Linux kernel 2.6 or later and don't already have <literal
+ >libaio</literal> installed, you can easily install it using the following
+ steps:</para>
+ <para>Using yum, (e.g. on Fedora or Red Hat Enterprise Linux):
+ <programlisting>sudo yum install libaio1</programlisting></para>
+ <para>Using aptitude, (e.g. on Ubuntu or Debian system):
+ <programlisting>sudo apt-get install libaio1</programlisting></para>
+ </section>
+ <section>
+ <title>Configuring JBoss Messaging for zero persistence</title>
+ <para> In some situations, zero persistence is sometimes required for a messaging system.
+ Configuring JBoss Messaging to perform zero persistence is straightforward. Simply set
+ the parameter <literal>enable-persistence</literal> in <literal
+ >jbm-configuration.xml</literal> to <literal>false</literal>. </para>
+ <para>Please note that if you set this parameter to false, then <emphasis>zero</emphasis>
+ persistence will occur. That means no bindings data, message data, large message data,
+ duplicate id caches or paging data will be persisted.</para>
+ </section>
</chapter>
Modified: trunk/docs/user-manual/en/modules/using-core.xml
===================================================================
--- trunk/docs/user-manual/en/modules/using-core.xml 2009-05-12 10:54:14 UTC (rev 6739)
+++ trunk/docs/user-manual/en/modules/using-core.xml 2009-05-12 12:59:24 UTC (rev 6740)
@@ -30,12 +30,18 @@
and asynchronous message consumption semantics. <literal>ClientConsumer</literal> instances can be configured with an optional
filter expression and will only consume messages which match that expression.</para>
<para>Core Messaging also fully supports both local and XA transactional semantics.</para>
+ <para>TODO insert diagram showing core routing queue and addresses</para>
</section>
<section>
- <title>A simpe example of using Core</title>
+ <title>A simple example of using Core</title>
<para></para>
</section>
+ <section>
+ <title>Core transactions</title>
+ <para></para>
+ </section>
+
</chapter>
More information about the jboss-cvs-commits
mailing list