avalon-cvs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From blorit...@apache.org
Subject cvs commit: jakarta-avalon-excalibur/event/src/xdocs command-howto.xml menu.xml
Date Fri, 27 Sep 2002 20:27:16 GMT
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="bloritsch@apache.org"/>
      </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:avalon-cvs-unsubscribe@jakarta.apache.org>
For additional commands, e-mail: <mailto:avalon-cvs-help@jakarta.apache.org>


Mime
View raw message