bloritsch 2002/09/27 13:27:16
Modified: event/src/xdocs menu.xml
Added: event/src/xdocs command-howto.xml
Log:
Add documentation for CommandManager
Revision Changes Path
1.9 +2 -0 jakarta-avalon-excalibur/event/src/xdocs/menu.xml
Index: menu.xml
===================================================================
RCS file: /home/cvs/jakarta-avalon-excalibur/event/src/xdocs/menu.xml,v
retrieving revision 1.8
retrieving revision 1.9
diff -u -r1.8 -r1.9
--- menu.xml 26 Sep 2002 18:34:12 -0000 1.8
+++ menu.xml 27 Sep 2002 20:27:16 -0000 1.9
@@ -21,7 +21,9 @@
<menu name="How To">
<!--
<item href="event-howto.html" name="Use Event Queues"/>
+-->
<item href="command-howto.html" name="Use the Command Manager"/>
+<!--
<item href="mpool-howto.html" name="Use MPool"/>
<item href="thread-howto.html" name="Use Thread Pools"/>
-->
1.1
jakarta-avalon-excalibur/event/src/xdocs/command-howto.xml
Index: command-howto.xml
===================================================================
<?xml version="1.0"?>
<document>
<header>
<title>Excalibur Event - How To Use Command</title>
<authors>
<person name="Berin Loritsch" email="[EMAIL PROTECTED]"/>
</authors>
</header>
<body>
<s1 title="Setting Up The Command Manager">
<p>
Using Command is a two step process. You have to set it up,
and then you can send Commands to it. Because Command uses
an Event Pipeline to move the Commands through the Queue to
the EventHandler, we need to set up a ThreadManager. Currently
the only ThreadManager that works as advertized is the
TPCThreadManager.
TPC stands for "Thread Per CPU". The TPCThreadManager allows
you to customize its behaviour by passing in some parameters.
The code snippet below is fairly typical:
</p>
<source>
<![CDATA[
ThreadManager threadManager = new TPCThreadManager();
threadManager.enableLogging( getLogger().getChildLogger("threadmanager") );
Parameters params = new Parameters();
params.setParameter( "threads-per-processor", "2" );
params.setParameter( "sleep-time", "1000" );
params.setParameter( "block-timeout", "250" );
threadManager.parameterize( params );
threadManager.initialize();
]]>
</source>
<p>
We create a Threadmanager, pass in the Logger, pass in the Parameters,
and then initialize it. The table below provides all the parameter
names
that TPCThreadManager recognizes:
</p>
<table>
<tr>
<th>Name</th> <th>Description</th> <th>Default Value</th>
</tr>
<tr>
<td>processors</td>
<td>Number of processors (autodetected if less than one)</td>
<td>Results from SystemUtil.numProcessors()</td>
</tr>
<tr>
<td>threads-per-processor</td>
<td>Threads per processor to use (Rewritten to 1 if less than
one)</td>
<td>1</td>
</tr>
<tr>
<td>sleep-time</td>
<td>Time (in milliseconds) to wait between queue pipeline
processing runs</td>
<td>1000</td>
</tr>
<tr>
<td>block-timeout</td>
<td>Time (in milliseconds) to wait for a thread to process a
pipeline</td>
<td>1000</td>
</tr>
</table>
<p>
Once the ThreadManager is set up and used, we can set up the
CommandManager.
We do this by instantiating the CommandManager, and registering it
with the
ThreadManager. Below is a code snippet showing how that is done:
</p>
<source>
<![CDATA[
// Create the CommandManager
CommandManager commandManager = new CommandManager();
// Register it with the ThreadManager
threadManager.register( commandManager );
]]>
</source>
</s1>
<s1 title="Running Commands">
<p>
There are three Command interfaces: Command, DelayedCommand, and
RepeatedCommand.
Each one of those has a special purpose. The Command interface
exposes the method
that the CommandManager will execute named, oddly enough,
"execute()". The
Delayed Command is used to specify a number of milliseconds to wait
before the
command is run. That delay is based on when the CommandManager
receives the
DelayedCommand, not on when the object was created. Lastly the
RepeatedCommand
interface is used to determine how long and how many times the
Command will
be executed. Below is a code snippet showing how to send Commands to
the
CommandManager:
</p>
<source>
<![CDATA[
Sink commandSink = commandManager.getCommandSink();
commandSink.enqueu( new MySpecialCommand() );
]]>
</source>
<p>
It's not that hard to use the CommandManager. Writing a Command is
as easy as
implementing the java.lang.Runnable interface. There are two
distinct advantages
to using the Command infrastructure: your Command can throw
exceptions and it
won't cause anything to break, and you have the ability to
automatically have
your Command run again. Just keep in mind that the Command
infrastructure was
meant for short lived management functions happening in the
background, not
a long lived thread. If you want to give the illusion that your
Command is
running a long time without tying up system resources the whole time,
then
write a RepeatedCommand. Below is an example RepeatedCommand that is
used
for the DefaultPoolManager in MPool:
</p>
<source>
<![CDATA[
/**
* This is run every 10 seconds, starting after a 10 second delay.
* It gives the appearance of being a long running thread, but it
* does not consume a Thread for the times it would otherwise be
* asleep.
*/
private static final class PoolManagerCommand
implements RepeatedCommand
{
private final BucketMap m_map;
private final int m_min = 4;
private final int m_max = 256;
private final int m_grow = 4;
protected PoolManagerCommand( BucketMap map )
{
m_map = map;
}
public long getDelayInterval()
{
return 10 * 1000L;
}
public long getRepeatInterval()
{
return 10 * 1000L;
}
public int getNumberOfRepeats()
{
return 0;
}
public void execute()
throws Exception
{
Iterator i = m_map.keySet().iterator();
while( i.hasNext() )
{
ManagablePool pool = (ManagablePool)i.next();
long key = ( (Long)m_map.get( pool ) ).longValue();
int size = pool.size( key );
if( size < m_min )
{
pool.grow( m_grow, key );
}
if( size > m_max )
{
pool.shrink( m_grow, key );
}
}
}
}
]]>
</source>
</s1>
</body>
<footer>
<legal>
Copyright (c) @year@ The Jakarta Apache Project All rights reserved.
$Revision: 1.1 $ $Date: 2002/09/27 20:27:16 $
</legal>
</footer>
</document>
--
To unsubscribe, e-mail: <mailto:[EMAIL PROTECTED]>
For additional commands, e-mail: <mailto:[EMAIL PROTECTED]>
