[jboss-cvs] JBoss Messaging SVN: r7051 - in trunk: docs/user-manual/en and 1 other directory.
jboss-cvs-commits at lists.jboss.org
jboss-cvs-commits at lists.jboss.org
Tue May 26 23:12:44 EDT 2009
Author: clebert.suconic at jboss.com
Date: 2009-05-26 23:12:44 -0400 (Tue, 26 May 2009)
New Revision: 7051
Added:
trunk/docs/user-manual/en/libaio.xml
Modified:
trunk/build-messaging.xml
trunk/docs/user-manual/en/master.xml
trunk/docs/user-manual/en/perf-tuning.xml
trunk/docs/user-manual/en/persistence.xml
trunk/docs/user-manual/en/thread-pooling.xml
trunk/docs/user-manual/en/using-server.xml
Log:
libaio compilation chapter + some tweaks on docs
Modified: trunk/build-messaging.xml
===================================================================
--- trunk/build-messaging.xml 2009-05-27 03:08:21 UTC (rev 7050)
+++ trunk/build-messaging.xml 2009-05-27 03:12:44 UTC (rev 7051)
@@ -106,6 +106,7 @@
<property name="build.distro.dir"
value="${build.dir}/${build.artifact}"/>
<property name="build.distro.lib.dir" value="${build.distro.dir}/lib"/>
+ <property name="build.distro.native.dir" value="${build.distro.dir}/native-src"/>
<property name="build.distro.client.dir" value="${build.distro.dir}/client"/>
<property name="build.distro.config.dir" value="${build.distro.dir}/config"/>
<property name="build.distro.schema.dir" value="${build.distro.dir}/schemas"/>
@@ -778,64 +779,6 @@
<include name="${ra.rar.name}"/>
<include name="${jms.api.jar.name}"/>
</fileset>
- <!--
- <fileset dir="${jboss.microcontainer.lib}">
- <include name="jboss-container.jar"/>
- <include name="jboss-kernel.jar"/>
- <include name="jboss-dependency.jar"/>
- <include name="jboss-aop-mc-int.jar"/>
- </fileset>
- <fileset dir="${jboss.jboss.javaee.lib}">
- <include name="jboss-javaee.jar"/>
- </fileset>
- <fileset dir="${jboss.jboss.common.logging.spi.lib}">
- <include name="jboss-common-logging-spi.jar"/>
- </fileset>
- <fileset dir="${jboss.jbossxb.lib}">
- <include name="jboss-xml-binding.jar"/>
- </fileset>
- <fileset dir="${jboss.integration.lib}">
- <include name="jboss-transaction-spi.jar"/>
- </fileset>
- <fileset dir="${jboss.jboss.security.spi.lib}">
- <include name="jboss-security-spi.jar"/>
- </fileset>
- <fileset dir="${jboss.jboss.jaspi.api.lib}">
- <include name="jboss-jaspi-api.jar"/>
- </fileset>
- <fileset dir="${jboss.jbosssx.client.lib}">
- <include name="jbosssx-client.jar"/>
- </fileset>
- <fileset dir="${jboss.common.core.lib}">
- <include name="jboss-common-core.jar"/>
- </fileset>
- <fileset dir="${apache.xerces.lib}">
- <include name="xercesImpl.jar"/>
- </fileset>
- <fileset dir="${apache.logging.lib}">
- <include name="commons-logging.jar"/>
- </fileset>
- <fileset dir="${sun.jaxb.lib}">
- <include name="jaxb-api.jar"/>
- </fileset>
- <fileset dir="${jboss.jboss.common.logging.spi.lib}">
- <include name="jboss-common-logging-spi.jar"/>
- </fileset>
- <fileset dir="${apache.log4j.lib}">
- <include name="log4j.jar"/>
- </fileset>
- <fileset dir="${jboss.jbossts.lib}">
- <include name="jbossjta.jar"/>
- <include name="jbossts-common.jar"/>
- <include name="jbossjta-integration.jar"/>
- </fileset>
- <fileset dir="${trove.lib}">
- <include name="trove.jar"/>
- </fileset>
- <fileset dir="${javassist.lib}">
- <include name="javassist.jar"/>
- </fileset>
- -->
<fileset dir="${jboss.jnpserver.lib}">
<include name="jnpserver.jar"/>
</fileset>
@@ -862,6 +805,9 @@
<include name="messaging.truststore"/>
</fileset>
</copy>
+ <copy todir="${build.distro.native.dir}">
+ <fileset dir="./native" includes="**/*" excludes="**/*.so"/>
+ </copy>
<copy todir="${build.distro.schema.dir}">
<fileset dir="${src.schema.dir}">
<include name="*.xsd"/>
Added: trunk/docs/user-manual/en/libaio.xml
===================================================================
--- trunk/docs/user-manual/en/libaio.xml (rev 0)
+++ trunk/docs/user-manual/en/libaio.xml 2009-05-27 03:12:44 UTC (rev 7051)
@@ -0,0 +1,101 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<chapter id="libaio">
+ <title>Libaio Native Libraries</title>
+ <para>JBoss Messaging distributes a native library, used as a bridge between JBoss Messaging and
+ linux libaio.</para>
+ <para>libaio is a library, developed as part of the linux kernel project. With libaio we perform
+ writes directly on the operation system, and the kernel will sends a callback event on which
+ we use to determine the transaction state. With this we can perform transactions at much
+ faster rates.</para>
+ <para>The native library is distributed in two flavors:</para>
+ <itemizedlist>
+ <listitem>
+ <para>libJBMLibAIO32.so - x86 32 bits</para>
+ </listitem>
+ <listitem>
+ <para>libJBMLibAIO64.so - x86 64 bits</para>
+ </listitem>
+ </itemizedlist>
+ <para>JBoss Messaging will aways try loading these files, as long as they are on the <link
+ linkend="using-server.library.path">library path</link>.</para>
+ <section>
+ <title>Compiling the native libraries</title>
+ <para>Case you are using Linux on a platform other than x86_32 and x86_64 you may need to
+ compile the native library.</para>
+ <section>
+ <title>Install requirements</title>
+ <para>The native library uses <ulink url="http://en.wikipedia.org/wiki/Autoconf"
+ >autoconf</ulink> what makes the compilation process easy, however you need to
+ install extra packages as a requirement for compilation:</para>
+ <itemizedlist>
+ <listitem>
+ <para>gcc - C Compiler</para>
+ </listitem>
+ <listitem>
+ <para>gcc-c++ or g++ - Extension to gcc with support for C++</para>
+ </listitem>
+ <listitem>
+ <para>autoconf - Tool for automating native build process</para>
+ </listitem>
+ <listitem>
+ <para>make - Plain old make</para>
+ </listitem>
+ <listitem>
+ <para>automake - Tool for automating make generation</para>
+ </listitem>
+ <listitem>
+ <para>libtool - Tool for link editing native libraries</para>
+ </listitem>
+ <listitem>
+ <para>libaio - library to disk asynchronous IO kernel functions</para>
+ </listitem>
+ <listitem>
+ <para>libaio-dev - Compilation support for libaio</para>
+ </listitem>
+ <listitem>
+ <para>A full JDK installed with the environment variable JAVA_HOME set to its
+ location</para>
+ </listitem>
+ </itemizedlist>
+ <para>To perform this installation on RHEL or Fedora, you can simply type this at a
+ command line:</para>
+ <programlisting>sudo yum install automake libtool autoconf gcc-g++ gcc libaio libaio-dev make</programlisting>
+ <para>Or on debian systems:</para>
+ <programlisting>sudo apt-get install automake libtool autoconf gcc-g++ gcc libaio libaio-dev make</programlisting>
+ <note>
+ <para>You could find a slight variation of the package names depending on the
+ version and linux distribution. (for example gcc-c++ on Fedora versus g++ on
+ Debian systems)</para>
+ </note>
+ </section>
+ <section>
+ <title>Invoking the compilation</title>
+ <para>In the distribution, in the <literal>native-src</literal> directory, execute the
+ shell script <literal>bootstrap</literal>. This script will invoke <literal
+ >automake</literal> and <literal>make</literal> what will create all the make
+ files and the native library.</para>
+ <programlisting>someUser at someBox:/messaging-distribution/native-src$ ./bootstrap
+checking for a BSD-compatible install... /usr/bin/install -c
+checking whether build environment is sane... yes
+checking for a thread-safe mkdir -p... /bin/mkdir -p
+
+...
+
+configure: creating ./config.status
+config.status: creating Makefile
+config.status: creating ./src/Makefile
+config.status: creating config.h
+config.status: config.h is unchanged
+config.status: executing depfiles commands
+config.status: executing libtool commands
+
+...</programlisting>
+ <para>The produced library will be at <literal
+ >./native-src/src/.libs/libJBMLibAIO.so</literal>. Simply move that file over
+ <literal>bin</literal> on the distribution or the place you have chosen on the
+ <link linkend="using-server.library.path">library path</link>.</para>
+ <para>If you want to perform changes on the JBoss Messaging libaio code, you could just
+ call make directly at the <literal>native</literal> directory.</para>
+ </section>
+ </section>
+</chapter>
Modified: trunk/docs/user-manual/en/master.xml
===================================================================
--- trunk/docs/user-manual/en/master.xml 2009-05-27 03:08:21 UTC (rev 7050)
+++ trunk/docs/user-manual/en/master.xml 2009-05-27 03:12:44 UTC (rev 7051)
@@ -46,6 +46,7 @@
<!ENTITY using-server SYSTEM "using-server.xml">
<!ENTITY wildcard-syntax SYSTEM "wildcard-syntax.xml">
<!ENTITY wildcard-routing SYSTEM "wildcard-routing.xml">
+ <!ENTITY libaio SYSTEM "libaio.xml">
]>
<book lang="en">
<bookinfo>
@@ -99,6 +100,7 @@
&interoperability;
&perf-tuning;
&configuration-index;
+ &libaio;
&project-info;
</book>
Modified: trunk/docs/user-manual/en/perf-tuning.xml
===================================================================
--- trunk/docs/user-manual/en/perf-tuning.xml 2009-05-27 03:08:21 UTC (rev 7050)
+++ trunk/docs/user-manual/en/perf-tuning.xml 2009-05-27 03:12:44 UTC (rev 7051)
@@ -6,17 +6,31 @@
<title>Tuning the journal</title>
<itemizedlist>
<listitem>
- <para>Tune minimum number of journal files. TODO</para>
+ <para>Minimum number of journal files. Set <literal>journal-min-files</literal> to a
+ number of files that would fit your average sustainable rate. If you see new
+ files being created on the journal data directory too oftenly you need to
+ increase the minimal number of files, this way the journal would reuse more
+ files instead of create new data files.</para>
</listitem>
<listitem>
- <para>Tune journal file size. TODO</para>
+ <para>Journal file size. The journal file size should be aligned to the capacity of
+ a cylinder on the disk. The default value 10MiB should be enough on most
+ systems.</para>
</listitem>
<listitem>
- <para>Use AIO journal. TODO</para>
+ <para>Use AIO journal. If using Linux, try to keep your journal type as AIO.</para>
</listitem>
<listitem>
- <para>Tune AIO re-use cache. TODO</para>
+ <para>AIO re-use cache. Keep <literal>journal-buffer-reuse-size</literal> to an
+ average size of your records on the journal. The record is composed by the
+ message body, properties and about 100 bytes per message.</para>
</listitem>
+ <listitem>
+ <para>Max IO. If using AIO, keep <literal>journal-max-aio</literal> accordingly to
+ your disk capacity. If in a thread dump you see too many write requests waiting
+ on <literal>AsynchronousFile.write</literal> you may be out of space on the
+ Asynchronous IO queue. Increase the value on that case.</para>
+ </listitem>
</itemizedlist>
</section>
<section>
@@ -68,18 +82,19 @@
<para>There are various other places in JBoss Messaging where we can perform some
tuning:</para>
<itemizedlist>
- <listitem><para>Use Asynchronous Send Acknowledgements. If you need to send persistent
+ <listitem>
+ <para>Use Asynchronous Send Acknowledgements. If you need to send persistent
messages non transactionally and you need a guarantee that they have reached the
server by the time the call to send() returns, don't set persistent messages to
be sent blocking, instead use asynchronous send acknowledgements to get your
acknowledgements of send back in a separate stream, see <xref
- linkend="send-guarantees" /> for more information on
- this.</para></listitem>
+ linkend="send-guarantees"/> for more information on this.</para>
+ </listitem>
<listitem>
<para>Use pre-acknowledge mode. With pre-acknowledge mode, messages are acknowledged
<literal>before</literal> they are sent to the client. This reduces the
amount of acknowledgment traffic on the wire. For more information on this, see
- <xref linkend="pre-acknowledge" />.</para>
+ <xref linkend="pre-acknowledge"/>.</para>
</listitem>
<listitem>
<para>Disabled security. You may get a small performance boost by disabling security
@@ -96,7 +111,8 @@
>journal-sync-transactional</literal> to <literal>false</literal> in
<literal>jbm-configuration.xml</literal> can give you better transactional
persistent performance at the expense of some possibility of loss of
- transactions on failure. See <xref linkend="send-guarantees"/> for more information.</para>
+ transactions on failure. See <xref linkend="send-guarantees"/> for more
+ information.</para>
</listitem>
<listitem>
<para>Use the core API not JMS. Using the JMS API you will have slightly lower
@@ -114,13 +130,14 @@
than one can fit in a single IP packet. Then you may get a significant
performance boost by enabling Nagle's algorithm. This is done by setting
<literal>jbm.remoting.netty.tcpnodelay</literal> to false with the Netty
- transports. See <xref linkend="configuring-transports" /> for more information on this. </para>
+ transports. See <xref linkend="configuring-transports"/> for more information on
+ this. </para>
</listitem>
<listitem>
<para>TCP buffer sizes. If you have a fast network and fast machines you may get a
performance boost by increasing the TCP send and receive buffer sizes. See the
- <xref linkend="configuring-transports" />
- for more information on this. </para>
+ <xref linkend="configuring-transports"/> for more information on this.
+ </para>
</listitem>
</itemizedlist>
</section>
@@ -138,13 +155,12 @@
</listitem>
<listitem>
<para>Memory settings. Give as much memory as you can to the server. JBoss Messaging
- can run in low memory by using paging (described in <xref linkend="paging" />)
- but if it can run
- with all queues in RAM this will improve performance. The amount of memory you
- require will depend on the size and number of your queues and the size and
- number of your messages. Use the JVM arguments <literal>-Xms</literal> and
- <literal>-Xmx</literal> to set server available RAM. We recommend setting
- them to the same high value.</para>
+ can run in low memory by using paging (described in <xref linkend="paging"/>)
+ but if it can run with all queues in RAM this will improve performance. The
+ amount of memory you require will depend on the size and number of your queues
+ and the size and number of your messages. Use the JVM arguments <literal
+ >-Xms</literal> and <literal>-Xmx</literal> to set server available RAM. We
+ recommend setting them to the same high value.</para>
</listitem>
<listitem>
<para>Aggressive options. Different JVMs provide different sets of JVM tuning
Modified: trunk/docs/user-manual/en/persistence.xml
===================================================================
--- trunk/docs/user-manual/en/persistence.xml 2009-05-27 03:08:21 UTC (rev 7050)
+++ trunk/docs/user-manual/en/persistence.xml 2009-05-27 03:12:44 UTC (rev 7051)
@@ -39,9 +39,8 @@
This provides very good performance and runs on any platform where there's a
JDK.</para>
</listitem>
- <listitem>
- <para id="aio-journal">Linux Asynchronous IO (<ulink url="http://lse.sourceforge.net/io/aio.html"
- >AIO</ulink>).</para>
+ <listitem id="aio-journal">
+ <para>Linux Asynchronous IO</para>
<para>The second implementation uses a thin native code wrapper to talk to the Linux
asynchronous IO library (AIO). In a highly concurrent environment, AIO can provide
better overall persistent throughput since it does not require each individual
@@ -53,7 +52,8 @@
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 <xref linkend="installing-aio" />.</para>
+ install libaio please see <xref linkend="installing-aio"/>.</para>
+ <para>libaio is part of the kernel project.</para>
</listitem>
</itemizedlist>
<para>The standard JBoss Messaging core server uses two instances of the journal:</para>
@@ -77,11 +77,12 @@
</listitem>
</itemizedlist>
<para>For large messages, JBoss Messaging persists them outside the message journal. This is
- discussed in <xref linkend="large-messages" />.</para>
+ discussed in <xref linkend="large-messages"/>.</para>
<para>JBoss Messaging also pages messages to disk in low memory situations. This is discussed in
- <xref linkend="paging" />.</para>
+ <xref linkend="paging"/>.</para>
<para>If no persistence is required at all, JBoss Messaging can also be configured not to
- persist any data at all to storage as discussed in <xref linkend="persistence.enabled" />.</para>
+ persist any data at all to storage as discussed in <xref linkend="persistence.enabled"
+ />.</para>
<section id="configuring.bindings.journal">
<title>Configuring the bindings journal</title>
<para>The bindings journal is configured using the following attributes in <literal
@@ -128,7 +129,7 @@
</listitem>
<listitem>
<para><literal>journal-type</literal></para>
- <para>Valid values are <literal>NIO</literal> or <literal>AIO</literal>.</para>
+ <para>Valid values are <literal>NIO</literal> or <literal>ASYNCIO</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 do not have
Modified: trunk/docs/user-manual/en/thread-pooling.xml
===================================================================
--- trunk/docs/user-manual/en/thread-pooling.xml 2009-05-27 03:08:21 UTC (rev 7050)
+++ trunk/docs/user-manual/en/thread-pooling.xml 2009-05-27 03:12:44 UTC (rev 7051)
@@ -59,13 +59,11 @@
</section>
<section>
<title>Asychronous IO</title>
- <para>Two threads are used on asynchronous IO files. One for polling events, and one for
- writing data. </para>
- <para>The thread poller is used by the native layer to receive and dispatch events. You
- will find it on a thread dump with the prefix JBM-AIO-poller-pool. JBoss Messaging
- uses one poller per opened file on the journal. (there is usually one) and they are
- always distributed through a pool.</para>
- <para>The writing thread is a single thread used to invoke libaio. We do that to avoid
+ <para>Asynchronous IO has a thread pool for receiving and dispatching events out of the
+ native layer. You will find it on a thread dump with the prefix JBM-AIO-poller-pool.
+ JBoss Messaging uses one one thread per opened file on the journal (there is usually
+ one).</para>
+ <para>There is also a single thread used to invoke writes on libaio. We do that to avoid
context switching on libaio what would cause performance issues. You will find this
thread on a thread dump with the prefix JBM-AIO-writer-pool.</para>
</section>
@@ -84,25 +82,20 @@
<para>To configure a <literal>ClientSessionFactory</literal> instance to use its own pools,
simply use the appropriate setter methods immediately after creation, for
example:</para>
- <programlisting>
-ClientSessionFactory myFactory = new ClientSessionFactory(...);
+ <programlisting>ClientSessionFactory myFactory = new ClientSessionFactory(...);
myFactory.setUseGlobalPools(false);
myFactory.setScheduledThreadPoolMaxSize(10);
-myFactory.setThreadPoolMaxSize(-1);
- </programlisting>
+myFactory.setThreadPoolMaxSize(-1); </programlisting>
<para>If you're using the JMS API, you can set the same parameters directly on the <literal
>JBossConnectionFactory</literal> instance, for example:</para>
- <programlisting>
-JBossConnectionFactory myFactory = new JBossConnectionFactory(...);
+ <programlisting>JBossConnectionFactory myFactory = new JBossConnectionFactory(...);
myFactory.setUseGlobalPools(false);
myFactory.setScheduledThreadPoolMaxSize(10);
-myFactory.setThreadPoolMaxSize(-1);
- </programlisting>
+myFactory.setThreadPoolMaxSize(-1); </programlisting>
<para>If you're using JNDI to instantiate <literal>JBossConnectionFactory</literal>
instances, you can also set these parameters in the <literal>jbm-jms.xml</literal> file
where you describe your connection factory, for example:</para>
- <programlisting>
-<connection-factory name="ConnectionFactory">
+ <programlisting><connection-factory name="ConnectionFactory">
<connector-ref connector-name="netty"/>
<entries>
<entry name="ConnectionFactory"/>
@@ -111,7 +104,6 @@
<use-global-pools>false</use-global-pools>
<scheduled-thread-pool-max-size>10</scheduled-thread-pool-max-size>
<thread-pool-max-size>-1</thread-pool-max-size>
-</connection-factory>
- </programlisting>
+</connection-factory></programlisting>
</section>
</chapter>
Modified: trunk/docs/user-manual/en/using-server.xml
===================================================================
--- trunk/docs/user-manual/en/using-server.xml 2009-05-27 03:08:21 UTC (rev 7050)
+++ trunk/docs/user-manual/en/using-server.xml 2009-05-27 03:12:44 UTC (rev 7051)
@@ -69,13 +69,13 @@
<para>Just make sure the directory is on the classpath and JBoss Messaging will search there
when starting up.</para>
</section>
- <section>
- <title>LD_LIBRARY_PATH</title>
- <para>If you're using the <xref linkend="aio-journal">Asynchronous IO Journal</xref> on
- Linux, then the environment variable <literal>LD_LIBRARY_PATH</literal> needs to be set
- to the path that contains the shared library file that contains the native code for the
- AIO abstraction layer. This is done automatically in the <literal>run.sh</literal>
- script.</para>
+ <section id="using-server.library.path">
+ <title>Library Path</title>
+ <para>If you're using the <link linkend="aio-journal">Asynchronous IO Journal</link> on
+ Linux, you need to specify <literal>java.library.path</literal> as a property on your
+ Java options. This is done automatically in the <literal>run.sh</literal> script.</para>
+ <para>If you don't specify <literal>java.library.path</literal> at your Java options then
+ the JVM will use the environment variable <literal>LD_LIBRARY_PATH</literal>.</para>
</section>
<section>
<title>System properties</title>
@@ -108,15 +108,15 @@
linkend="configuration-index"/>.</para>
</listitem>
<listitem>
- <para><literal>jbm-queues.xml</literal>. This file contains pre-defined queues,
- queue settings and security settings. The file is optional - all this
- configuration can also live in <literal>jbm-configuration.xml</literal>. In
- fact, the default configuration sets do not have a <literal
- >jbm.queues.xml</literal> file. The purpose of allowing queues to be
- configured in these files is to allow you to manage your queue configuration
- over many files instead of being forced to maintain it in a single file. There
- can be many <literal>jbm-queues.xml</literal> files on the classpath. All will
- be loaded if found.</para>
+ <para><literal>jbm-queues.xml</literal>. This file contains predefined queues, queue
+ settings and security settings. The file is optional - all this configuration
+ can also live in <literal>jbm-configuration.xml</literal>. In fact, the default
+ configuration sets do not have a <literal>jbm.queues.xml</literal> file. The
+ purpose of allowing queues to be configured in these files is to allow you to
+ manage your queue configuration over many files instead of being forced to
+ maintain it in a single file. There can be many <literal
+ >jbm-queues.xml</literal> files on the classpath. All will be loaded if
+ found.</para>
</listitem>
<listitem>
<para><literal>jbm-users.xml</literal> JBoss Messaging ships with a security manager
More information about the jboss-cvs-commits
mailing list