ChangeLogTag:Fri Aug 2 22:00:26 UTC 2002 Craig Rodrigues <crodrigu@bbn.com>

9 files changed, 169 insertions, 74 deletions

diff --git a/TAO/ChangeLog b/TAO/ChangeLog
index 9bcdc83ea43..f65be912beb 100644
--- a/TAO/ChangeLog
+++ b/TAO/ChangeLog
@@ -1,3 +1,8 @@
+Fri Aug  2 15:13:28 2002  Douglas C. Schmidt  <schmidt@macarena.cs.wustl.edu>
+
+	* docs/configurations.html: Added a documentation entry for the
+	  Real-time CORBA thread pool model.
+
 Fri Aug  2 16:17:34 2002  Balachandran Natarajan  <bala@cs.wustl.edu>
 
 	* orbsvcs/orbsvcs/PortableGroup/Portable_Group_Map.cpp: Added a
diff --git a/TAO/docs/configurations.html b/TAO/docs/configurations.html
index 2cc9368feaf..0b30e76c278 100644
--- a/TAO/docs/configurations.html
+++ b/TAO/docs/configurations.html
@@ -72,7 +72,9 @@ Roadmap</h3>
         <li><a href="#multiorb-tpc">Multiple threads, multiple ORBs,
             thread-per-connection model.</a></li>
 
-        <li><a href="#tpool">Multiple threads, single ORB, thread-pool model.</a></li>
+        <li><a href="#tpool">Multiple threads, single ORB, TAO thread-pool model.</a></li>
+
+        <li><a href="#rtpool">Multiple threads, single ORB, Real-time CORBA thread-pool model.</a></li>
 
         <li><a href="#multiorb-tpool">Multiple threads,
             ORB-per-thread, thread-pool reactive model.</a></li>
@@ -274,7 +276,7 @@ The following are common ORB configurations used by TAO applications.<P>
 
 <ul>
   <li>
-      <a NAME="reactive"></a>Single-threaded, reactive model.</li> <P>
+      <a NAME="reactive"></a><B>Single-threaded, reactive model.</B></li> <P>
 
       <table BORDER=2 CELLSPACING=2 CELLPADDING=0 WIDTH="90%" >
         <tr>
@@ -284,7 +286,7 @@ The following are common ORB configurations used by TAO applications.<P>
               thread handles requests from multiple clients via a
               single Reactor. It is appropriate when the requests (1)
               take a fixed, relatively uniform amount of time and (2)
-              are largely compute bound.&nbsp;</td>
+              are largely compute bound.</td>
         </tr>
 
         <tr>
@@ -307,6 +309,14 @@ The following are common ORB configurations used by TAO applications.<P>
         </tr>
 
         <tr>
+          <th align=left>Synchronization considerations</th>
+
+          <td>Application servants needn't
+              be concerned with synchronizing their interactions since
+              there's only one thread active with this model.</td>
+        </tr>
+
+        <tr>
           <th align=left>Options</th>
 
           <td>The default settings should work just fine.  However,
@@ -325,8 +335,8 @@ The following are common ORB configurations used by TAO applications.<P>
       <P>Check out the <tt><a href="../examples/Simple/grid/">Grid</a></tt>
       for an example of this configuration. <P>
 
-  <li> <a NAME="tpc"></a>Multiple threads, single ORB, thread-per-connection
-      model.</li> <P>
+  <li> <a NAME="tpc"></a><B>Multiple threads, single ORB, thread-per-connection
+      model.</B></li> <P>
 
       <table BORDER=2 CELLSPACING=2 CELLPADDING=0 WIDTH="90%" >
         <tr ALIGN="LEFT">
@@ -363,6 +373,14 @@ The following are common ORB configurations used by TAO applications.<P>
             established connections.</td>
       </tr>
 
+        <tr>
+          <th align=left>Synchronization considerations</th>
+
+          <td> To avoid race conditions, application servants may need to
+            synchronize their methods if multiple clients can access
+            them concurrently.</td>
+        </tr>
+
       <tr>
         <th align=left>Options</th>
 
@@ -375,7 +393,7 @@ The following are common ORB configurations used by TAO applications.<P>
     is a good example on using <i>multiple threads, thread-per-connection</i>
     configuration.<P>
 <li>
-    <P>Multiple threads, multiple ORB, reactive model.<a NAME="multiorb"></a></li><P>
+    <P><B>Multiple threads, multiple ORB, reactive model.</B><a NAME="multiorb"></a></li><P>
 
     <table BORDER=2 CELLSPACING=2 CELLPADDING=0 WIDTH="90%">
       <tr>
@@ -383,7 +401,7 @@ The following are common ORB configurations used by TAO applications.<P>
 
         <td>In this configuration, there are multiple ORBs in a
             process with multiple threads. Each thread handles requests
-            reactively. It's good for hard real-time applications that
+            reactively.  This model is good for hard real-time applications that
             require different thread priorities for the various
             ORBs.</td>
       </tr>
@@ -406,6 +424,14 @@ The following are common ORB configurations used by TAO applications.<P>
         <td>Service the requests from associating ORB.</td>
       </tr>
 
+        <tr>
+          <th align=left>Synchronization considerations</th>
+
+          <td>Application servants needn't
+              be concerned with synchronizing their interactions if
+              there's no cross ORB/thread access.</td>
+        </tr>
+
       <tr>
         <th align=left>Options</th>
 
@@ -417,7 +443,7 @@ The following are common ORB configurations used by TAO applications.<P>
 </table>
 <P>
 
-<li>Multiple threads, multiple ORBs, thread-per-connection model.<a
+<li><B>Multiple threads, multiple ORBs, thread-per-connection model.</B><a
     NAME="multiorb-tpc"></a></li><P>
 
     <table BORDER=2 CELLSPACING=2 CELLPADDING=0 WIDTH="90%">
@@ -450,6 +476,14 @@ The following are common ORB configurations used by TAO applications.<P>
           requests from established connections.</td>
     </tr>
 
+        <tr>
+          <th align=left>Synchronization considerations</th>
+
+          <td> To avoid race conditions, application servants may need to
+            synchronize their methods if multiple clients can access
+            them concurrently.</td>
+        </tr>
+
     <tr>
       <th align=left>Options</th>
 
@@ -462,18 +496,19 @@ The following are common ORB configurations used by TAO applications.<P>
 <tt><a href="../performance-tests/Cubit/TAO/MT_Cubit/">MT_Cubit</a>
 </tt> is a good example on using <i>multiple threads,
 multiple ORBs, and thread-per-connection</i> configuration.<P>
+
 <li>
-    <a NAME="tpool"></a>Multiple threads, single ORB, thread-pool model.</li><P>
+    <a NAME="tpool"></a><B>Multiple threads, single ORB, TAO thread-pool model.</B></li><P>
 
     <table BORDER=2 CELLSPACING=2 CELLPADDING=0 WIDTH="90%" >
       <tr>
         <th align=left>Typical Use</th>
 
-        <td>This model implements a highly optimized thread pool that leverages
-            context switching, and thread creation costs.  In this
+        <td>This model implements a highly optimized, TAO-specific thread pool that minimizes
+            context switching and thread creation costs.  In this
             model, the programmer is responsible of spawning a group
-            of threads, start up the ORB and then instruct all the threads
-            to run the ORB event loop.  When a request comes in, one
+            of threads, start up the ORB and then instruct all the
+            threads to run the ORB event loop.  When a request comes in, one
             of these waiting threads in the pool will handle the
             request.</td>
       </tr>
@@ -496,6 +531,15 @@ multiple ORBs, and thread-per-connection</i> configuration.<P>
         <td>Blocking on the reactor to wait for its turn to handle a request.</td>
       </tr>
 
+        <tr>
+          <th align=left>Synchronization considerations</th>
+
+          <td> To avoid race conditions, application servants may need to
+            synchronize their methods if multiple clients or multiple
+              thread from the same client can access
+            them concurrently.</td>
+        </tr>
+
       <tr>
         <th align=left>Options</th>
 
@@ -504,10 +548,71 @@ multiple ORBs, and thread-per-connection</i> configuration.<P>
     </table>
     <P>
     <tt><a href="../tests/MT_Server">MT_Server</a></tt> is a good
-    example on using <i>multiple threads, single ORB, thread-pool</i>
+    example on using <i>multiple threads, single ORB, TAO thread-pool</i>
     configuration.<P>
-<P><li>
-    Multiple threads, multiple ORBs, thread-pool model.<a NAME="multiorb-tpool"></a>
+<P>
+
+<li>
+    <a NAME="rtpool"></a><B>Multiple threads, single ORB, Real-time
+    CORBA thread-pool model.</B></li><P>
+
+    <table BORDER=2 CELLSPACING=2 CELLPADDING=0 WIDTH="90%" >
+      <tr>
+        <th align=left>Typical Use</th>
+
+        <td>This model implements a highly optimized <A HREF="rtcorba/">Real-time CORBA</A> thread pool that minimizes
+            context switching, and thread creation costs.  In this
+            model, the application is responsible for starting up the ORB and then 
+            calling the Real-time CORBA thread pool factory methods that
+            internally spawn a pool of threads.  When a request comes in, one
+            of these waiting threads in the pool will handle the
+            request in accordance with the various CORBA policies.</td>
+      </tr>
+
+      <tr>
+        <th align=left>Number of Threads</th>
+
+        <td>Thread for the ORB, plus the number of threads used by the thread pool.</td>
+      </tr>
+
+      <tr>
+        <th align=left>Thread Creator</th>
+
+        <td>Static threads are pre-spawned by the ORB, which also
+            spawns any dynamic threads on-demand.</td>
+      </tr>
+
+      <tr>
+        <th align=left>Thread task</th>
+
+        <td>Blocking on the reactor to wait for its turn to handle a request.</td>
+      </tr>
+
+        <tr>
+          <th align=left>Synchronization considerations</th>
+
+          <td> To avoid race conditions, application servants may need to
+            synchronize their methods if multiple clients or multiple
+              thread from the same client can access
+            them concurrently.</td>
+        </tr>
+
+      <tr>
+        <th align=left>Options</th>
+
+        <td> The ORB must be configured to work with <A
+            HREF="rtcorba">Real-time CORBA</A>, at which point the
+            default settings work fine.</td>
+      </tr>
+    </table>
+    <P>
+    <tt><a href="../tests/RTCORBA/Thread_Pool">Thread_Pool</a></tt> is a good
+    example on using <i>multiple threads, single ORB, Real-time CORBA thread-pool</i>
+    configuration.<P>
+<P>
+
+<li>
+    <B>Multiple threads, multiple ORBs, thread-pool model.</B><a NAME="multiorb-tpool"></a>
 </li><P>
 
     <table BORDER=2 CELLSPACING=2 CELLPADDING=0 WIDTH="90%" >
@@ -537,6 +642,15 @@ multiple ORBs, and thread-per-connection</i> configuration.<P>
         <td>Handle incoming request for the ORB event loop it is
             waiting on.</td>
       </tr>
+
+        <tr>
+          <th align=left>Synchronization considerations</th>
+
+          <td>Application servants needn't
+              be concerned with synchronizing their interactions if
+              there's no cross ORB/thread access.</td>
+        </tr>
+
       <tr>
         <th align=left>Options</th>
 
diff --git a/TAO/docs/rtcorba/architecture.html b/TAO/docs/rtcorba/architecture.html
index 1824409bed1..b06460a079d 100644
--- a/TAO/docs/rtcorba/architecture.html
+++ b/TAO/docs/rtcorba/architecture.html
@@ -9,7 +9,7 @@
 
 <body>
 
-<h2 align="center">TAO Real-Time Architecture&nbsp;</h2>
+<h3 align="center">TAO Real-Time Architecture&nbsp;</h3>
 <p>This page describes and compares the two main ORB designs we considered for
 supporting Real-Time CORBA 1.0 in TAO.&nbsp; The first design, codenamed <i>reactor-per-lane</i>
 and shown in Figure 1, was chosen for our initial implementation.&nbsp; The
diff --git a/TAO/docs/rtcorba/content.html b/TAO/docs/rtcorba/content.html
index 737738528ef..2b631e4174c 100644
--- a/TAO/docs/rtcorba/content.html
+++ b/TAO/docs/rtcorba/content.html
@@ -9,13 +9,11 @@
 
 <body>
 
-<h2 align="center">TAO Real-Time CORBA Documentation </h2>
+<h3 align="center">TAO Real-Time CORBA Documentation </h3>
 
 <ol>
   <li><a href="status.html#intro">Intro</a></li>
-  <li><a href="status.html#status">Current Status</a><ul>
-      <li><a href="status.html#completed">Recently Completed</a> </li>
-      <li><a href="status.html#in progress">In Progress</a></li>
+  <ul>
       <li><a href="status.html#supported">Supported Features</a></li>
       <li><a href="status.html#unsupported">Unsupported Features</a></li>
       <li><a href="status.html#future">Future Work</a></li>
@@ -36,8 +34,8 @@
     </ul>
   </li>
   <li><a href="issues.html">Known Bugs and Issues</a></li>
-  <li>Performance</li>
-  <li>Papers</li>
+  <li><A
+      HREF="http://www.cs.wustl.edu/~schmidt/corba-research-realtime.html">Performance and Papers</A></li>
   <li><a href="faq.html">FAQ</a>&nbsp;&nbsp;&nbsp; </li>
 </ol>
 
diff --git a/TAO/docs/rtcorba/faq.html b/TAO/docs/rtcorba/faq.html
index 02314bc6f4c..ab446b2620b 100644
--- a/TAO/docs/rtcorba/faq.html
+++ b/TAO/docs/rtcorba/faq.html
@@ -9,7 +9,7 @@
 
 <body>
 
-<h2><a name="top">Frequently Asked Questions</a></h2>
+<h3><a name="top">Frequently Asked Questions</a></h3>
 
 <p><strong><a href="#Q1">1. Question</a><br>
 <a href="#Q2">2. Question</a></strong></p>
diff --git a/TAO/docs/rtcorba/features.html b/TAO/docs/rtcorba/features.html
index b93c52d1a50..8dd62a442fe 100644
--- a/TAO/docs/rtcorba/features.html
+++ b/TAO/docs/rtcorba/features.html
@@ -9,7 +9,7 @@
 
 <body>
 
-<h2 align="center">Features Documentation</h2>
+<h3 align="center">Features Documentation</h3>
 
 <p>This page is not a tutorial on Real-Time CORBA, but is rather a
 supplement to the specification, covering all implementation-specific
diff --git a/TAO/docs/rtcorba/issues.html b/TAO/docs/rtcorba/issues.html
index b25841bf1dd..9a8584da8c3 100644
--- a/TAO/docs/rtcorba/issues.html
+++ b/TAO/docs/rtcorba/issues.html
@@ -9,7 +9,7 @@
 
 <body>
 
-<h2><a name="top">Known Issues and TO-DO Items</a></h2>
+<h3><a name="top">Known Issues and TO-DO Items</a></h3>
 <p>This page contains a list of known RTCORBA-related issues and to-do
 items. The list does not include any of the reports from the bug tracking
 system, so be sureto <a href="http://ace.cs.wustl.edu/bugzilla/query.cgi">query
diff --git a/TAO/docs/rtcorba/omg_issues.html b/TAO/docs/rtcorba/omg_issues.html
index 357df5f92bc..bb49722b205 100644
--- a/TAO/docs/rtcorba/omg_issues.html
+++ b/TAO/docs/rtcorba/omg_issues.html
@@ -9,7 +9,7 @@
 
 <body>
 
-<h2>Issues with Real-Time CORBA 1.0 Specification</h2>
+<h3>Issues with Real-Time CORBA 1.0 Specification</h3>
 
 This document lists what we believe to be the shortcomings of the
 Real-Time CORBA 1.0 specification, which we uncovered while implementing it in TAO.&nbsp;
diff --git a/TAO/docs/rtcorba/status.html b/TAO/docs/rtcorba/status.html
index ef3518b7a36..d29518cd6de 100644
--- a/TAO/docs/rtcorba/status.html
+++ b/TAO/docs/rtcorba/status.html
@@ -9,21 +9,33 @@
 
 <body>
 
-<h1><a name="intro">Real-Time CORBA Support in TAO</a> </h1>
+<h3><a name="intro">Real-Time CORBA Support in TAO</a> </h3>
+<a name="status">
 
 <p>Support for <a href="http://www.omg.org">OMG</a> <a
-href="http://cgi.omg.org/cgi-bin/doc?ptc/99-05-03">Real-Time CORBA 1.0 specification</a>
-is currently being added to TAO. The implementation effort is in full gear, so
-please check back often - these pages are updated frequently. For a list of recently
-added features and work in progress see the <a href="#status">Current Status</a> section
-below.</p>
-
-<p>As usual, questions, comments, and contributions should be posted to the <a
-href="news:comp.soft-sys.ace">comp.soft-sys.ace</a> newsgroup, and bug reports can be
-submitted either through our web-based <a
-href="http://ace.cs.wustl.edu/bugzilla/index.cgi">bug-tracking system</a> (best) or by
-filling out the TAO/PROBLEM-REPORT-FORM and posting it to the newsgroup. Please
-indicate &quot;RTCORBA&quot; in the component field when submitting a bug report. </p>
+href="http://cgi.omg.org/cgi-bin/doc?ptc/99-05-03">Real-Time CORBA 1.0
+specification</a> has been added to TAO.  For an overview of Real-time
+CORBA features, please see the <A
+HREF="http://www.cs.wustl.edu/~schmidt/report-doc.html#rt">C/C++ Users
+Journal columns</A> written by <A
+HREF="http://www.cs.wustl.edu/~schmidt/">Douglas Schmidt</A> and <A
+HREF="http://www.iona.com/hyplan/vinoski/">Steve Vinoski</a>.  For a
+detailed design discussions and results of empirical performance
+analyzes of TAO's Real-time CORBA implementation, please see the <A
+HREF="http://www.cs.wustl.edu/~schmidt/doc-group.html">DOC group's</a>
+<A
+HREF="http://www.cs.wustl.edu/~schmidt/corba-research-realtime.html">Real-time
+CORBA research page</A>. 
+
+<p>As usual, questions, comments, and contributions should be posted
+to the <a href="news:comp.soft-sys.ace">comp.soft-sys.ace</a>
+newsgroup, and bug reports can be submitted either through our
+web-based <a
+href="http://ace.cs.wustl.edu/bugzilla/index.cgi">bug-tracking
+system</a> (best) or by filling out the <A
+HREF="../../PROBLEM-REPORT-FORM">TAO_ROOT/PROBLEM-REPORT-FORM</A>
+and posting it to the newsgroup. Please indicate &quot;RTCORBA&quot;
+in the component field when submitting a bug report. </p>
 
 <p>Points of contact for the project are: 
 
@@ -35,40 +47,6 @@ indicate &quot;RTCORBA&quot; in the component field when submitting a bug report
     documentation </li>
 </ul>
 
-<h2><a name="status">Current Status</a> </h2>
-
-<p>Status last updated on: $Date$ </p>
-
-<h3><a name="completed">Recently Completed</a></h3>
-
-<p>Items completed recently. (For a complete list of supported
-features see <a href="#supported">this section</a>). 
-
-<ul>
-  <li>POA Threadpools</li>
-  <li>Online Documentation</li>
-  <li>New tests</li>
-  <li>New collocation scheme</li>
-  <li>Private Connections</li>
-  <li>Explicit Binding</li>
-  <li>RT Mutex</li>
-</ul>
-
-<h3><a name="in progress">In Progress</a></h3>
-
-<table border="1" width="100%">
-  <tr>
-    <td width="33%" align="center"><strong>Feature</strong></td>
-    <td width="33%" align="center"><strong>Due Date</strong></td>
-    <td width="34%" align="center"><strong>Contact</strong></td>
-  </tr>
-  <tr>
-    <td width="33%" align="left"></td>
-    <td width="33%" align="center"></td>
-    <td width="34%" align="center"></td>
-  </tr>
-</table>
-
 <h3><a name="supported">Supported Features</a></h3>
 
 <p>Following is the complete list of features from the Real-Time CORBA 1.0 specification