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]>
