Author: timfox
Date: 2010-01-07 11:24:23 -0500 (Thu, 07 Jan 2010)
New Revision: 8770
Modified:
trunk/docs/quickstart-guide/en/introduction.xml
trunk/docs/user-manual/en/configuring-transports.xml
trunk/docs/user-manual/en/connection-ttl.xml
trunk/docs/user-manual/en/examples.xml
trunk/docs/user-manual/en/flow-control.xml
trunk/docs/user-manual/en/persistence.xml
trunk/docs/user-manual/en/transaction-config.xml
Log:
docs edits part 3
Modified: trunk/docs/quickstart-guide/en/introduction.xml
===================================================================
--- trunk/docs/quickstart-guide/en/introduction.xml 2010-01-07 14:48:27 UTC (rev 8769)
+++ trunk/docs/quickstart-guide/en/introduction.xml 2010-01-07 16:24:23 UTC (rev 8770)
@@ -21,7 +21,7 @@
<para>This short guide explains how to download, install and quickly get
started with
HornetQ.</para>
<para>After downloading and installing we highly recommend you run the examples
to get
- acquainted with HornetQ. We ship with over 65 examples demonstrating most of the
+ acquainted with HornetQ. We ship with over 70 examples demonstrating most of the
features.</para>
<para>This guide is not intended to be a replacement for the user manual. The
user manual goes
into much more depth, so please consult that for further
information.</para>
Modified: trunk/docs/user-manual/en/configuring-transports.xml
===================================================================
--- trunk/docs/user-manual/en/configuring-transports.xml 2010-01-07 14:48:27 UTC (rev
8769)
+++ trunk/docs/user-manual/en/configuring-transports.xml 2010-01-07 16:24:23 UTC (rev
8770)
@@ -176,7 +176,10 @@
<title>Configuring Netty TCP</title>
<para>Netty TCP is a simple unencrypted TCP sockets based transport.
Netty TCP can be
configured to use old blocking Java IO or non blocking Java NIO. We
recommend you
- use the default Java NIO for better scalability. </para>
+ use the Java NIO on the server side for better scalability with many
concurrent
+ connections. However using Java old IO can sometimes give you better
latency than
+ NIO when you're not so worried about supporting many thousands of
concurrent
+ connections. </para>
<para>If you're running connections across an untrusted network
please bear in mind this
transport is unencrypted. You may want to look at the SSL or HTTPS
configurations.</para>
@@ -190,25 +193,26 @@
can be used to configure Netty for simple TCP:</para>
<itemizedlist>
<listitem>
- <para><literal>usenio</literal>. If this is
<literal
- >true</literal> then Java non blocking NIO will be
used. If set to
- <literal>false</literal> than old blocking Java
IO will be used.</para>
+ <para><literal>usenio</literal>. If this is
<literal>true</literal> then Java
+ non blocking NIO will be used. If set to
<literal>false</literal> than old
+ blocking Java IO will be used.</para>
<para>We highly recommend that you use non blocking Java NIO.
Java NIO does not
maintain a thread per connection so can scale to many more
concurrent
connections than with old blocking IO. We recommend the usage of
Java 6 for
NIO and the best scalability. The default value for this property
is
- <literal>true</literal>.</para>
+ <literal>true</literal> on the server side and
<literal>false</literal>
+ on the client side.</para>
</listitem>
<listitem>
- <para><literal>host</literal>. This specified the
host
- name or IP address to connect to (when configuring a connector)
or to listen
- on (when configuring an acceptor). The default value for this
property is
- <literal>localhost</literal>. When configuring
acceptors, multiple hosts
- or IP addresses can be specified by separating them with commas.
It is also
- possible to specify <code>0.0.0.0</code> to accept
connection from all
- the host network interfaces. It's not
- valid to specify multiple addresses when specifying the host for
a
- connector; a connector makes a connection to one specific
address.</para>
+ <para><literal>host</literal>. This specifies the
host name or IP address to
+ connect to (when configuring a connector) or to listen on (when
configuring
+ an acceptor). The default value for this property is <literal
+ >localhost</literal>. When configuring acceptors,
multiple hosts or IP
+ addresses can be specified by separating them with commas. It is
also
+ possible to specify <code>0.0.0.0</code> to accept
connection from all the
+ host's network interfaces. It's not valid to specify
multiple addresses when
+ specifying the host for a connector; a connector makes a
connection to one
+ specific address.</para>
<note>
<para>Don't forget to specify a host name or ip
address! If you want your
server able to accept connections from other nodes you must
specify a
@@ -218,22 +222,20 @@
</note>
</listitem>
<listitem>
- <para><literal>port</literal>. This specified the
port to
- connect to (when configuring a connector) or to listen on (when
configuring
- an acceptor). The default value for this property is <literal
- >5445</literal>.</para>
+ <para><literal>port</literal>. This specified the
port to connect to (when
+ configuring a connector) or to listen on (when configuring an
acceptor). The
+ default value for this property is
<literal>5445</literal>.</para>
</listitem>
<listitem>
- <para><literal>tcpnodelay</literal>. If this is
<literal
- >true</literal> then <ulink
-
url="http://en.wikipedia.org/wiki/Nagle's_algorithm">Nag...
+ <para><literal>tcpnodelay</literal>. If this is
<literal>true</literal> then
+ <ulink
url="http://en.wikipedia.org/wiki/Nagle's_algorithm">Nag...
algorithm</ulink> will be enabled. The default value
for this property
is <literal>true</literal>.</para>
</listitem>
<listitem>
- <para><literal>tcpsendbuffersize</literal>. This
- parameter determines the size of the TCP send buffer in bytes.
The default
- value for this property is <literal>32768</literal>
bytes (32KiB).</para>
+ <para><literal>tcpsendbuffersize</literal>. This
parameter determines the size
+ of the TCP send buffer in bytes. The default value for this
property is
+ <literal>32768</literal> bytes
(32KiB).</para>
<para>TCP buffer sizes should be tuned according to the
bandwidth and latency of
your network. Here's a good link that explains the theory
behind <ulink
url="http://www-didc.lbl.gov/TCP-tuning/">this</ulink>...
@@ -248,10 +250,9 @@
defaults.</para>
</listitem>
<listitem>
- <para><literal>tcpreceivebuffersize</literal>.
This
- parameter determines the size of the TCP receive buffer in bytes.
The
- default value for this property is
<literal>32768</literal> bytes
- (32KiB).</para>
+ <para><literal>tcpreceivebuffersize</literal>. This
parameter determines the
+ size of the TCP receive buffer in bytes. The default value for
this property
+ is <literal>32768</literal> bytes
(32KiB).</para>
</listitem>
</itemizedlist>
</section>
@@ -264,25 +265,24 @@
additional properties:</para>
<itemizedlist>
<listitem>
- <para><literal>sslenabled</literal>. Must be
<literal
- >true</literal> to enable SSL.</para>
+ <para><literal>sslenabled</literal>. Must be
<literal>true</literal> to enable
+ SSL.</para>
</listitem>
<listitem>
- <para><literal>keystorepath</literal>. This is the
path
- to the SSL key store on the client which holds the client
- certificates.</para>
+ <para><literal>keystorepath</literal>. This is the
path to the SSL key store on
+ the client which holds the client certificates.</para>
</listitem>
<listitem>
- <para><literal>keystorepassword</literal>. This is
the
- password for the client certificate key store on the
client.</para>
+ <para><literal>keystorepassword</literal>. This is
the password for the client
+ certificate key store on the client.</para>
</listitem>
<listitem>
- <para><literal>truststorepath</literal>. This is
the path
- to the trusted client certificate store on the
server.</para>
+ <para><literal>truststorepath</literal>. This is
the path to the trusted client
+ certificate store on the server.</para>
</listitem>
<listitem>
- <para><literal>truststorepassword</literal>. This
is the
- password to the trusted client certificate store on the
server.</para>
+ <para><literal>truststorepassword</literal>. This
is the password to the trusted
+ client certificate store on the server.</para>
</listitem>
</itemizedlist>
</section>
@@ -295,31 +295,29 @@
properties:</para>
<itemizedlist>
<listitem>
- <para><literal>httpenabled</literal>. Must be
<literal
- >true</literal> to enable HTTP.</para>
+ <para><literal>httpenabled</literal>. Must be
<literal>true</literal> to enable
+ HTTP.</para>
</listitem>
<listitem>
- <para><literal>httpclientidletime</literal>. How
long a
- client can be idle before sending an empty http request to keep
the
- connection alive</para>
+ <para><literal>httpclientidletime</literal>. How
long a client can be idle
+ before sending an empty http request to keep the connection
alive</para>
</listitem>
<listitem>
- <para><literal>httpclientidlescanperiod</literal>.
How
- often, in milliseconds, to scan for idle clients</para>
+ <para><literal>httpclientidlescanperiod</literal>.
How often, in milliseconds,
+ to scan for idle clients</para>
</listitem>
<listitem>
- <para><literal>httpresponsetime</literal>. How long
the
- server can wait before sending an empty http response to keep the
connection
- alive</para>
+ <para><literal>httpresponsetime</literal>. How long
the server can wait before
+ sending an empty http response to keep the connection
alive</para>
</listitem>
<listitem>
- <para><literal>httpserverscanperiod</literal>. How
often,
- in milliseconds, to scan for clients needing
responses</para>
+ <para><literal>httpserverscanperiod</literal>. How
often, in milliseconds, to
+ scan for clients needing responses</para>
</listitem>
<listitem>
- <para><literal>httprequiressessionid</literal>. If
true
- the client will wait after the first call to receive a session
id. Used the
- http connector is connecting to servlet acceptor (not
recommended) </para>
+ <para><literal>httprequiressessionid</literal>. If
true the client will wait
+ after the first call to receive a session id. Used the http
connector is
+ connecting to servlet acceptor (not recommended) </para>
</listitem>
</itemizedlist>
</section>
@@ -411,9 +409,9 @@
</listitem>
</itemizedlist>
<para>The servlet pattern configured in the
<literal>web.xml</literal> is the path of
- the URL that is used. The connector param <literal
- >servletpath</literal> on the connector config must match
- this using the application context of the web app if there is
one.</para>
+ the URL that is used. The connector param
<literal>servletpath</literal> on the
+ connector config must match this using the application context of the web
app if
+ there is one.</para>
<para>Its also possible to use the servlet transport over SSL. simply
add the following
configuration to the
connector:<programlisting> <connector
name="netty-servlet">
Modified: trunk/docs/user-manual/en/connection-ttl.xml
===================================================================
--- trunk/docs/user-manual/en/connection-ttl.xml 2010-01-07 14:48:27 UTC (rev 8769)
+++ trunk/docs/user-manual/en/connection-ttl.xml 2010-01-07 16:24:23 UTC (rev 8770)
@@ -150,20 +150,20 @@
deploying JMS connection factory instances direct into JNDI on the server
side, you can
specify it in the <literal>hornetq-jms.xml </literal>
configuration file, using the
parameter
<literal>client-failure-check-period</literal>.</para>
- <para>The default value for client failure check period is
<literal>30000</literal>ms, i.e. 30
- seconds. A value of <literal>-1</literal> means the client will
never fail the
+ <para>The default value for client failure check period is
<literal>30000</literal>ms, i.e.
+ 30 seconds. A value of <literal>-1</literal> means the client
will never fail the
connection on the client side if no data is received from the server.
Typically this is
much lower than connection TTL to allow clients to reconnect in case of
transitory
failure.</para>
</section>
<section id="connection-ttl.async-connection-execution">
<title>Configuring Asynchronous Connection Execution</title>
- <para>By default, packets received on the server side are handed off by the
remoting thread
- for processing.</para>
+ <para>By default, packets received on the server side are executed on the
remoting
+ thread.</para>
<para>It is possible instead to use a thread from a thread pool to handle
the packents so
- that the remoting thread is not tied up for too long. However, please note
that processing
- operations asynchronously on another thread adds a little more
- latency. To enable asynchronous connection execution, set the parameter
<literal
+ that the remoting thread is not tied up for too long. However, please note
that
+ processing operations asynchronously on another thread adds a little more
latency. To
+ enable asynchronous connection execution, set the parameter <literal
async-connection-execution-enabled</literal> in <literal
hornetq-configuration.xml</literal> to <literal>true</literal> (default
value is
<literal>false</literal>).</para>
Modified: trunk/docs/user-manual/en/examples.xml
===================================================================
--- trunk/docs/user-manual/en/examples.xml 2010-01-07 14:48:27 UTC (rev 8769)
+++ trunk/docs/user-manual/en/examples.xml 2010-01-07 16:24:23 UTC (rev 8770)
@@ -18,7 +18,7 @@
<!-- =============================================================================
-->
<chapter id="examples">
<title>Examples</title>
- <para>The HornetQ distribution comes with over 65 run out-of-the-box examples
demonstrating many
+ <para>The HornetQ distribution comes with over 70 run out-of-the-box examples
demonstrating many
of the features.</para>
<para>The examples are available in the distribution, in the
<literal>examples</literal>
directory. Examples are split into JMS and core examples. JMS examples show how a
particular
Modified: trunk/docs/user-manual/en/flow-control.xml
===================================================================
--- trunk/docs/user-manual/en/flow-control.xml 2010-01-07 14:48:27 UTC (rev 8769)
+++ trunk/docs/user-manual/en/flow-control.xml 2010-01-07 16:24:23 UTC (rev 8770)
@@ -19,7 +19,7 @@
<chapter id="flow-control">
<title>Flow Control</title>
<para>Flow control is used to limit the flow of data between a client and
server, or a server and
- a server in order to prevent the client or server being overwhelmed with
data.</para>
+ another server in order to prevent the client or server being overwhelmed with
data.</para>
<section>
<title>Consumer Flow Control</title>
<para>This controls the flow of data between the server and the client as the
client consumes
@@ -79,16 +79,18 @@
<para>Slow consumers takes significant time to process each
message and it is
desirable to prevent buffering messages on the client side so that
they can be
delivered to another consumer instead.</para>
- <para>Consider a situation where a queue has 2 consumers 1 of
which is very slow.
+ <para>Consider a situation where a queue has 2 consumers; 1 of
which is very slow.
Messages are delivered in a round robin fashion to both consumers,
the fast
consumer processes all of its messages very quickly until its buffer
is empty.
- At this point there are still messages awaiting to be processed by
the slow
- consumer which could be being consumed by the other
consumer.</para>
+ At this point there are still messages awaiting to be processed in
the buffer
+ of the slow consumer thus preventing them being processed by the
fast consumer.
+ The fast consumer is therefore sitting idle when it could be
processing the
+ other messages. </para>
<para>To allow slow consumers, set the
<literal>consumer-window-size</literal> to
0 (for no buffer at all). This will prevent the slow consumer from
buffering
any messages on the client side. Messages will remain on the server
side ready
to be consumed by other consumers.</para>
- <para>Setting this to -1 can give deterministic distribution
between multiple
+ <para>Setting this to 0 can give deterministic distribution
between multiple
consumers on a queue.</para>
</listitem>
</varlistentry>
@@ -130,13 +132,13 @@
</section>
<section>
<title>Rate limited flow control</title>
- <para>It is also possible to control the rate at which a consumer can
consumer messages.
- This is a form of throttling and can be used to make sure that a consumer
never consumes
- messages at a rate faster than the rate specified. </para>
- <para>The rate must be a positive integer to enable and is the maximum
desired message
- consumption rate specified in units of messages per second. Setting this to
<literal
- >-1</literal> disables rate limited flow control. The default
value is <literal
- >-1</literal>.</para>
+ <para>It is also possible to control the
<emphasis>rate</emphasis> at which a consumer can
+ consume messages. This is a form of throttling and can be used to make sure
that a
+ consumer never consumes messages at a rate faster than the rate specified.
</para>
+ <para>The rate must be a positive integer to enable this functionality and
is the maximum
+ desired message consumption rate specified in units of messages per second.
Setting this
+ to <literal>-1</literal> disables rate limited flow control. The
default value is
+ <literal>-1</literal>.</para>
<para>Please see <xref
linkend="examples.consumer-rate-limit"/> for a working example of
limiting consumer rate.</para>
<section id="flow-control.rate.core.api">
@@ -192,12 +194,12 @@
sends them more credits they can send more messages.</para>
<para>The amount of credits a producer requests in one go is known as the
<emphasis
role="italic">window size</emphasis>.</para>
- <para>The window size therefore determines the amount of bytes that can be
inflight at any
+ <para>The window size therefore determines the amount of bytes that can be
in-flight at any
one time before more need to be requested - this prevents the remoting
connection from
getting overloaded.</para>
<section>
<title>Using Core API</title>
- <para>If the HornetQ core API is being window size can be set via the
<literal
+ <para>If the HornetQ core API is being used, window size can be set via
the <literal
ClientSessionFactory.setProducerWindowSize(int
producerWindowSize)</literal>
method.</para>
</section>
@@ -258,6 +260,8 @@
<para>The above example would set the max size of the JMS queue
"exampleQueue" to be
100000 bytes and would block any producers sending to that address to
prevent that
max size being exceeded.</para>
+ <para>Note the policy must be set to
<literal>DROP</literal> to enable blocking producer
+ flow control.</para>
<para>Please note the default value for
<literal>address-full-policy</literal> is to
<literal>PAGE</literal>. Please see the chapter on paging
for more information on
paging.</para>
@@ -268,10 +272,10 @@
<para>HornetQ also allows the rate a producer can emit message to be
limited, in units of
messages per second. By specifying such a rate, HornetQ will ensure that
producer never
produces messages at a rate higher than that specified.</para>
- <para>The rate must be a positive integer to enable and is the maximum
desired message
- consumption rate specified in units of messages per second. Setting this to
<literal
- >-1</literal> disables rate limited flow control. The default
value is <literal
- >-1</literal>.</para>
+ <para>The rate must be a positive integer to enable this functionality and
is the maximum
+ desired message consumption rate specified in units of messages per second.
Setting this
+ to <literal>-1</literal> disables rate limited flow control. The
default value is
+ <literal>-1</literal>.</para>
<para>Please see the <xref
linkend="producer-rate-limiting-example"/> for a working example
of limiting producer rate.</para>
<section id="flow-control.producer.rate.core.api">
Modified: trunk/docs/user-manual/en/persistence.xml
===================================================================
--- trunk/docs/user-manual/en/persistence.xml 2010-01-07 14:48:27 UTC (rev 8769)
+++ trunk/docs/user-manual/en/persistence.xml 2010-01-07 16:24:23 UTC (rev 8770)
@@ -21,9 +21,8 @@
<para>In this chapter we will describe how persistence works with HornetQ and
how to configure
it.</para>
<para>HornetQ ships with a high performance journal. Since HornetQ handles its
own persistence,
- rather than relying on a database or other 3rd party persistence engine, we have
been able
- to tune the journal to gain optimal performance for the persistence of messages
and
- transactions.</para>
+ rather than relying on a database or other 3rd party persistence engine it is
very highly
+ optimised for the specific messaging use cases.</para>
<para>A HornetQ journal is an <emphasis>append only</emphasis>
journal. It consists of a set of
files on disk. Each file is pre-created to a fixed size and initially filled with
padding.
As operations are performed on the server, e.g. add message, update message,
delete message,
@@ -53,20 +52,18 @@
<listitem>
<para>Java <ulink
url="http://en.wikipedia.org/wiki/New_I/O">NIO</ulink>...
<para>The first implementation uses standard Java NIO to interface with
the file system.
- This provides very good performance and runs on any platform where
there's a Java 5+
- runtime.</para>
+ This provides extremely good performance and runs on any platform where
there's a
+ Java 5+ runtime.</para>
</listitem>
<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 explicit
syncs to
- flush operating system buffers to disk. Most disks can only support a
limited number
- of syncs per second, so a syncing approach does not scale well when the
number of
- concurrent transactions needed to be committed grows too large. With AIO,
HornetQ
- 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>
+ asynchronous IO library (AIO). With AIO, HornetQ 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>Using AIO will typically provide even better performance than
using Java
+ NIO.</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>
@@ -87,7 +84,7 @@
<listitem>
<para>Message journal.</para>
<para>This journal instance stores all message related data, including
the message
- themselves and also duplicate id caches.</para>
+ themselves and also duplicate-id caches.</para>
<para>By default HornetQ 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
@@ -96,8 +93,8 @@
</itemizedlist>
<para>For large messages, HornetQ persists them outside the message journal.
This is discussed
in <xref linkend="large-messages"/>.</para>
- <para>HornetQ also pages messages to disk in low memory situations. This is
discussed in <xref
- linkend="paging"/>.</para>
+ <para>HornetQ can also be configured to page messages to disk in low memory
situations. This is
+ discussed in <xref linkend="paging"/>.</para>
<para>If no persistence is required at all, HornetQ can also be configured not
to persist any
data at all to storage as discussed in <xref
linkend="persistence.enabled"/>.</para>
<section id="configuring.bindings.journal">
@@ -132,8 +129,8 @@
physical 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 coordinator) then
the disk head
- may well be moving rapidly between these files as it writes them,
thus reducing
- performance.</para>
+ may well be moving rapidly between these files as it writes them,
thus
+ drastically 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>
@@ -184,10 +181,10 @@
</listitem>
<listitem id="configuring.message.journal.journal-max-io">
<para><literal>journal-max-io</literal></para>
- <para>Write requests are queued up before being submitted to the
system execution.
- This parameter controls the maximum number of write requests that can
be in the
- IO queue at any one time. If the queue becomes full then writes will
block until
- space is freed up. </para>
+ <para>Write requests are queued up before being submitted to the
system for
+ execution. This parameter controls the maximum number of write
requests that can
+ be in the IO queue at any one time. If the queue becomes full then
writes will
+ block until space is freed up. </para>
<para>When using NIO, this value should always be equal to
<literal
1</literal></para>
<para>When
using AIO, the default should be <literal>500</literal>.</para>
@@ -208,9 +205,11 @@
so the system maintains different defaults for both NIO and AIO
(default for NIO
is 3333333 nanoseconds - 300 times per second, default for AIO is
500000
nanoseconds - ie. 2000 times per second).</para>
- <para>By increasing the timeout, you may be able to increase system
throughput at
- the expense of latency, the default parameters are chosen to give a
reasonable
- balance between throughput and latency.</para>
+ <note>
+ <para>By increasing the timeout, you may be able to increase
system throughput
+ at the expense of latency, the default parameters are chosen to
give a
+ reasonable balance between throughput and latency.</para>
+ </note>
</listitem>
<listitem
id="configuring.message.journal.journal-buffer-size">
<para><literal>journal-buffer-size</literal></para>
@@ -237,44 +236,45 @@
<section id="disk-write-cache">
<title>An important note on disabling disk write cache.</title>
<warning>
- <para>Most disks contain hardware write caches. A write cache can increase
the apparent
- performance of the disk because writes just go into the cache and are then
lazily
- written to the disk later. </para>
- <para>This happens irrespective of whether you have executed a fsync() from
the operating
- system or correctly synced data from inside a Java program!</para>
- <para>By default many systems ship with disk write cache enabled. This
means that even after
- syncing from the operating system there is no guarantee the data has actually
made it to
- disk, so if a failure occurs, critical data can be lost.</para>
- <para>Some more expensive disks have non volatile or battery backed write
caches which won't
- necessarily lose data on event of failure, but you need to test
them!</para>
- <para>If your disk does not have an expensive non volatile or battery
backed cache and it's
- not part of some kind of redundant array, and you value your data integrity
you need to
- make sure disk write cache is disabled.</para>
- <para>Be aware that disabling disk write cache can give you a nasty shock
performance wise.
- If you've been used to using disks with write cache enabled in their
default setting,
- unaware that your data integrity could be compromised, then disabling it will
give you
- an idea of how fast your disk can perform when acting really
reliably.</para>
- <para>On Linux you can inspect and/or change your disk's write cache
settings using the
- tools <literal>hdparm</literal> (for IDE disks) or
<literal>sdparm</literal> or <literal
- >sginfo</literal> (for SDSI/SATA disks)</para>
- <para>On Windows you can check / change the setting by right clicking on
the disk and
- clicking properties.</para>
+ <para>Most disks contain hardware write caches. A write cache can
increase the apparent
+ performance of the disk because writes just go into the cache and are
then lazily
+ written to the disk later. </para>
+ <para>This happens irrespective of whether you have executed a fsync()
from the
+ operating system or correctly synced data from inside a Java
program!</para>
+ <para>By default many systems ship with disk write cache enabled. This
means that even
+ after syncing from the operating system there is no guarantee the data
has actually
+ made it to disk, so if a failure occurs, critical data can be
lost.</para>
+ <para>Some more expensive disks have non volatile or battery backed
write caches which
+ won't necessarily lose data on event of failure, but you need to test
them!</para>
+ <para>If your disk does not have an expensive non volatile or battery
backed cache and
+ it's not part of some kind of redundant array (e.g. RAID), and you
value your data
+ integrity you need to make sure disk write cache is
disabled.</para>
+ <para>Be aware that disabling disk write cache can give you a nasty
shock performance
+ wise. If you've been used to using disks with write cache enabled in
their default
+ setting, unaware that your data integrity could be compromised, then
disabling it
+ will give you an idea of how fast your disk can perform when acting
really
+ reliably.</para>
+ <para>On Linux you can inspect and/or change your disk's write
cache settings using the
+ tools <literal>hdparm</literal> (for IDE disks) or
<literal>sdparm</literal> or
+ <literal>sginfo</literal> (for SDSI/SATA
disks)</para>
+ <para>On Windows you can check / change the setting by right clicking
on the disk and
+ clicking properties.</para>
</warning>
</section>
<section id="installing-aio">
<title>Installing AIO</title>
<para>The Java NIO journal gives great performance, but If you are running
HornetQ 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>
+ journal for the very best persistence performance.</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
libaio</programlisting></para>
+ <programlisting>yum install libaio</programlisting></para>
<para>Using aptitude, (e.g. on Ubuntu or Debian system):
- <programlisting>sudo apt-get install
libaio</programlisting></para>
+ <programlisting>apt-get install
libaio</programlisting></para>
</section>
<section id="persistence.enabled">
<title>Configuring HornetQ for Zero Persistence</title>
Modified: trunk/docs/user-manual/en/transaction-config.xml
===================================================================
--- trunk/docs/user-manual/en/transaction-config.xml 2010-01-07 14:48:27 UTC (rev 8769)
+++ trunk/docs/user-manual/en/transaction-config.xml 2010-01-07 16:24:23 UTC (rev 8770)
@@ -29,4 +29,6 @@
transaction-timeout</literal> property in
<literal>hornetq-configuration.xml</literal> (value must be in milliseconds).
The property <literal>transaction-timeout-scan-period</literal>
configures how often, in
milliseconds, to scan for old transactions.</para>
+ <para>Please note that HornetQ will not unilaterally rollback any XA
transactions in a prepared state - this must be heuristically rolled
+ back via the management API if you are sure they will never be resolved by the
transaction manager.</para>
</chapter>