[jboss-cvs] JBossRemoting/docs/Multiplex/en ...
Ron Sigal
ron_sigal at yahoo.com
Sun Jul 30 03:11:09 EDT 2006
User: rsigal
Date: 06/07/30 03:11:09
Modified: docs/Multiplex/en multiplex.xml
Log:
JBREM-390: Added section about internal configuration parameters.
Revision Changes Path
1.2 +358 -2 JBossRemoting/docs/Multiplex/en/multiplex.xml
(In the diff below, changes in quantity of whitespace are not shown.)
Index: multiplex.xml
===================================================================
RCS file: /cvsroot/jboss/JBossRemoting/docs/Multiplex/en/multiplex.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -b -r1.1 -r1.2
--- multiplex.xml 27 Jan 2006 01:13:37 -0000 1.1
+++ multiplex.xml 30 Jul 2006 07:11:09 -0000 1.2
@@ -12,9 +12,9 @@
<title>The Multiplex Subsystem of the JBoss Remoting Project</title>
- <author><personname><firstname>Ron</firstname><surname>Sigal</surname></personname></author>
+ <author><personname><firstname>Ron</firstname> <surname>Sigal</surname></personname></author>
- <releaseinfo>November 5, 2005</releaseinfo>
+ <releaseinfo>July 4, 2006</releaseinfo>
<copyright><year>2005</year><holder>Ron Sigal</holder></copyright>
</articleinfo>
@@ -854,6 +854,362 @@
</section>
<section>
+ <title>Configuration.</title>
+
+ <para>The Multiplex system may be used without any external configuration, but it
+ exposes several parameters which may be set to adjust its behavior, and possibly
+ performance. They affect the following classes:</para>
+
+ <informaltable frame="all">
+ <tgroup cols="2">
+ <tbody>
+ <row>
+ <entry>
+ <para><emphasis role="bold">MultiplexingManager: </emphasis></para>
+ </entry>
+ <entry>
+ <para>The central Multiplex class, <classname>MultiplexingManager</classname>
+ wraps a real socket. It is responsible for creating an environment,
+ including multiple threads, which allow a single socket to be shared by
+ multiple streams of communication. Note that the
+ <classname>MultiplexingManager</classname> is the implementation of
+ the concept of "virtual socket group." A virtual socket group is
+ supported by exactly one <classname>MultiplexingManager</classname>,
+ and each <classname>MultiplexingManager</classname> supports exactly
+ one virtual socket group.
+ </para>
+ </entry>
+ </row>
+
+ <row>
+ <entry>
+ <para><emphasis role="bold">OutputMultiplexor: </emphasis></para>
+ </entry>
+ <entry>
+ <para><classname>OutputMultiplexor</classname> has two roles. (1) It
+ is called by <classname>MultiplexingOutputStream</classname> to queue an
+ array of bytes to be sent to a virtual socket at the other end of a
+ connection. (2) It contains the inner class <classname>OutputThread,
+ </classname> which takes byte arrays from the queue and writes them,
+ along with appropriate header information, to the actual socket.</para>
+ </entry>
+ </row>
+
+ <row>
+ <entry>
+ <para><emphasis role="bold">InputMultiplexor: </emphasis></para>
+ </entry>
+ <entry>
+ <para><classname>InputMultiplexor</classname> contains two inner
+ classes, <classname>MultiGroupInputThread</classname> and <classname>
+ SingleGroupInputThread</classname>, which are responsible for
+ demultiplexing the virtual streams on the actual connection and
+ directing the bytes to the appropriate
+ <classname>MultiplexingInputStream</classname>s.
+ <classname>MultiGroupInputThread</classname> can
+ process all NIO sockets in its JVM. Since some socket factories,
+ notably SSL socket factories, do not create NIO sockets,
+ <classname>SingleGroupInputThread</classname> exists to process a single
+ non-NIO socket.</para>
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+
+ <para>These parameters may be passed to the appropriate classes by putting them in a
+ configuration <classname>HashMap</classname>, using the keys given in
+ <classname>org.jboss.remoting.transport.multiplex.Multiplex</classname>,
+ and passing the map to a
+ <classname>VirtualSocket</classname>, a <classname>MasterServerSocket</classname>,
+ or a <classname>VirtualServerSocket</classname>.
+ It may be passed either through a constructor or a call to
+ <methodname>setConfiguration()</methodname>.
+ <emphasis role="bold">Note</emphasis>, however, that the parameters
+ have an effect <emphasis role="bold">only</emphasis> when a
+ <classname>MultiplexingManager</classname> is first created, or to say the
+ same thing differently, when a binding or connecting action leads to the
+ creation of a virtual socket group. When a socket or server socket joins an
+ existing socket group, or if <methodname>setConfiguration()</methodname> is called
+ after a binding or connection action creates a new
+ <classname>MultiplexingManager</classname>, the configuration
+ map will have no effect.</para>
+
+ <section>
+ <title>Configuring MultiplexingManager.</title>
+
+ <para>Two aspects of the behavior of <classname>MultiplexingManager</classname> may be
+ configured.</para>
+
+ <orderedlist>
+ <listitem>
+ <para>When a <classname>MultiplexingManager</classname> is created and it finds
+ no other <classname>MultiplexingManager</classname>s in the JVM,
+ it starts up several static threads. One of these threads periodically
+ wakes up and monitors the existence of <classname>MultiplexingManager</classname>s
+ in the JVM. If it wakes up two times in a row and finds no
+ <classname>MultiplexingManager</classname>s in the JVM, it shuts down the other
+ static threads.</para>
+ </listitem>
+
+ <listitem>
+ <para>When the last virtual socket supported by a particular
+ <classname>MultiplexingManager</classname> closes, the
+ <classname>MultiplexingManager</classname> will negotiate with its
+ peer at the other end of the connection for permission to shut down, which
+ will be withheld only if a virtual socket is being opened at the other
+ end.</para>
+ </listitem>
+ </orderedlist>
+
+ <para>The following parameters affect the behavior of <classname>MultiplexingManager</classname>:
+ </para>
+
+ <informaltable frame="all">
+ <tgroup cols="3">
+ <tbody>
+ <row>
+ <entry>
+ <para><emphasis role="bold">Name</emphasis>
+ (in org.jboss.remoting.transport.multiplex.Multiplex)</para>
+ </entry>
+ <entry>
+ <para><emphasis role="bold">Default value</emphasis></para>
+ </entry>
+ <entry>
+ <para><emphasis role="bold">Description</emphasis></para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para><emphasis role="bold">STATIC_THREADS_MONITOR_PERIOD: </emphasis></para>
+ </entry>
+ <entry>
+ 5000 msec
+ </entry>
+ <entry>
+ <para>Determines how often the monitor thread wakes up to look for
+ the existence of <classname>MultiplexingManager</classname>s in the
+ JVM.</para>
+ </entry>
+ </row>
+
+ <row>
+ <entry>
+ <para><emphasis role="bold">SHUTDOWN_REQUEST_TIMEOUT: </emphasis></para>
+ </entry>
+ <entry>
+ 5000 msec
+ </entry>
+ <entry>
+ <para>When a <classname>MultiplexingManager</classname> requests
+ permission from its remote peer to shut down, it will time out if it
+ does not receive a reply within this period of time.</para>
+ </entry>
+ </row>
+
+ <row>
+ <entry>
+ <para><emphasis role="bold">SHUTDOWN_REFUSALS_MAXIMUM: </emphasis></para>
+ </entry>
+ <entry>
+ 5
+ </entry>
+ <entry>
+ <para>When a <classname>MultiplexingManager</classname> requests
+ permission from its remote peer to shut down, it will take "no" for
+ an answer this many times before it assumes something is wrong and
+ goes ahead and shuts down.</para>
+ </entry>
+ </row>
+
+ <row>
+ <entry>
+ <para><emphasis role="bold">SHUTDOWN_MONITOR_PERIOD: </emphasis></para>
+ </entry>
+ <entry>
+ 1000 msec
+ </entry>
+ <entry>
+ <para>When a <classname>MultiplexingManager</classname> requests
+ permission from its remote peer to shut down, it creates a
+ <classname>TimerTask</classname> which periodically wakes up
+ to see if and how the remote peer has responded. This parameter
+ determines the period.</para>
+ </entry>
+ </row>
+
+ </tbody>
+ </tgroup>
+ </informaltable>
+ </section>
+
+ <section>
+ <title>Configuring OutputMultiplexor</title>
+
+ <para>When <classname>OutputMultiplexor</classname> is passed some bytes by
+ a <classname>MultiplexingOutputStream</classname>, it stores them in a
+ <classname>Message</classname> data structure drawn from a pool of
+ unused <classname>Message</classname>s and puts the <classname>Message</classname> on
+ a queue. When the <classname>OutputThread</classname> gets the
+ <classname>Message</classname> from the queue, it transmits some or all of its
+ content, according to a set of fairness constraints. If the entire contents are
+ not exhausted, the <classname>Message</classname> is returned to the queue.</para>
+
+ <para>The following parameters affect the behavior of
+ <classname>OutputMultiplexor</classname>: </para>
+
+ <informaltable frame="all">
+ <tgroup cols="3">
+ <tbody>
+ <row>
+ <entry>
+ <para><emphasis role="bold">Name</emphasis>
+ (in org.jboss.remoting.transport.multiplex.Multiplex)</para>
+ </entry>
+ <entry>
+ <para><emphasis role="bold">Default value</emphasis></para>
+ </entry>
+ <entry>
+ <para><emphasis role="bold">Description</emphasis></para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para><emphasis role="bold">OUTPUT_MESSAGE_POOL_SIZE: </emphasis></para>
+ </entry>
+ <entry>
+ 1024
+ </entry>
+ <entry>
+ <para>This determines the maximum size of the pool of
+ <classname>Message</classname>s. If the pool is empty when
+ a transmission request is received, a new <classname>Message</classname>
+ will be created, but when a <classname>Message</classname> has been
+ emptied, it will be returned to the pool only if the pool has fewer than
+ the maximum number of elements. Otherwise, the <classname>Message</classname>
+ will be discarded.</para>
+ </entry>
+ </row>
+
+ <row>
+ <entry>
+ <para><emphasis role="bold">OUTPUT_MESSAGE_SIZE: </emphasis></para>
+ </entry>
+ <entry>
+ 256 bytes
+ </entry>
+ <entry>
+ <para>This is the initial capacity of the
+ <classname>ByteArrayOutputStream</classname> that holds the contents
+ of a <classname>Message</classname>.</para>
+ </entry>
+ </row>
+
+ <row>
+ <entry>
+ <para><emphasis role="bold">OUTPUT_MAX_CHUNK_SIZE: </emphasis></para>
+ </entry>
+ <entry>
+ 2048 bytes
+ </entry>
+ <entry>
+ <para>This determines the number of bytes transmitted by the
+ <classname>OutputThread</classname> with a single
+ <methodname>write()</methodname> call.</para>
+ </entry>
+ </row>
+
+ <row>
+ <entry>
+ <para><emphasis role="bold">OUTPUT_MAX_TIME_SLICE: </emphasis></para>
+ </entry>
+ <entry>
+ 500 msec
+ </entry>
+ <entry>
+ <para><classname>OutputThread</classname> will process a single virtual
+ stream for this long before moving on to another stream.</para>
+ </entry>
+ </row>
+
+ <row>
+ <entry>
+ <para><emphasis role="bold">OUTPUT_MAX_DATA_SLICE: </emphasis></para>
+ </entry>
+ <entry>
+ 2048 * 8 bytes
+ </entry>
+ <entry>
+ <para><classname>OutputThread</classname> will transmit this many bytes
+ for a single virtual stream before moving on to another stream.</para>
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ </section>
+
+ <section>
+ <title>Configuring InputMultiplexor.</title>
+
+ <para>The following parameters affect the behavior of <classname>InputMultiplexor</classname>:
+ </para>
+
+ <informaltable frame="all">
+ <tgroup cols="3">
+ <tbody>
+ <row>
+ <entry>
+ <para><emphasis role="bold">Name</emphasis>
+ (in org.jboss.remoting.transport.multiplex.Multiplex)</para>
+ </entry>
+ <entry>
+ <para><emphasis role="bold">Default value</emphasis></para>
+ </entry>
+ <entry>
+ <para><emphasis role="bold">Description</emphasis></para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para><emphasis role="bold">INPUT_BUFFER_SIZE: </emphasis></para>
+ </entry>
+ <entry>
+ 4096 bytes
+ </entry>
+ <entry>
+ <para>Determines the size of the structure that holds bytes read
+ from the real socket. The structure is a <classname>ByteBuffer</classname>
+ for NIO sockets and a byte array for non-NIO sockets.</para>
+ </entry>
+ </row>
+
+ <row>
+ <entry>
+ <para><emphasis role="bold">INPUT_MAX_ERRORS: </emphasis></para>
+ </entry>
+ <entry>
+ 3
+ </entry>
+ <entry>
+ <para>Both <classname>MultiGroupInputThread</classname> and
+ <classname>SingleGroupInputThread</classname> count the number of
+ non-fatal errors experienced on the socket(s) they manage. When
+ this limit has been exceeded for a given socket, they will close
+ the socket and throw an exception.</para>
+ </entry>
+ </row>
+
+ </tbody>
+ </tgroup>
+ </informaltable>
+ </section>
+
+ </section>
+
+
+ <section>
<title>Performance.</title>
<para>It should come as no surprise that the classes in Muliplex
More information about the jboss-cvs-commits
mailing list