ChangeLogTag:Mon Oct 5 22:12:07 1998 Carlos O'Ryan <coryan@cs.wustl.edu>

3 files changed, 79 insertions, 0 deletions

diff --git a/TAO/ChangeLog-98c b/TAO/ChangeLog-98c
index 4e9ce50be1d..3570d82fb49 100644
--- a/TAO/ChangeLog-98c
+++ b/TAO/ChangeLog-98c
@@ -1,3 +1,9 @@
+Mon Oct  5 22:12:07 1998  Carlos O'Ryan  <coryan@cs.wustl.edu>
+
+	* docs/Options.html: 
+	* docs/configurations.html: 
+	  Added a few comments for the latest options.
+
 Mon Oct 05 21:43:26 1998  Douglas C. Schmidt  <schmidt@cs.wustl.edu>
 
         * TAO version 0.2.17 released.
diff --git a/TAO/docs/Options.html b/TAO/docs/Options.html
index ddf6692c985..845a0887bd9 100644
--- a/TAO/docs/Options.html
+++ b/TAO/docs/Options.html
@@ -214,6 +214,18 @@ copied instead of appended to the CDR stream.</TD></TR>
 <TD><a name="-ORBcoltable"></a>Specify whether each ORB uses a global
 (<em>which</em> = <code>global</code>) or a per-ORB
 (<em>which</em> = <code>orb</code>) collocation table.</TD></TR>
+<TR>
+<TD><CODE>-ORBinputcdrallocator</CODE> <EM>which</EM></TD>
+<TD><a name="-ORBinputcdrallocator"></a>
+	      Specify whether the ORB uses a global
+	      (<em>which</em> = <code>global</code>)
+	      or a per-thread (<em>which</em> = <code>tss</code>)
+	      allocator for the incoming CDR buffers.
+	      The default is <CODE>tss</CODE> and should give the
+	      optimal performance;
+	      unless the user takes advantage of the features in TAO
+	      to keep the CDR stream buffer after the upcall.
+	    </TD></TR>
 </TABLE>
 </P>
 </blockquote>
diff --git a/TAO/docs/configurations.html b/TAO/docs/configurations.html
index 310f39f3151..7649a3f547f 100644
--- a/TAO/docs/configurations.html
+++ b/TAO/docs/configurations.html
@@ -560,6 +560,67 @@ NAME="multiorb-tpool"></A> (Not yet implemented.)
 	(because calls would run at the priority of the client).
 	<P></P>
       </LI>
+      <LI><B>Single-threaded vs. Multi-threaded Connection Handlers</B>
+
+	The <CODE>Client_Connection_Handler</CODE> is the component in
+	TAO that writes the requests to the underlying transport
+	socket;
+	this is also the component that reads the response back from
+	the server.
+	<P>While waiting for this response new requests to the local
+	  ORB can arrive, this is the so-called nested upcall support.
+	  TAO supports two mechanisms for handling nested upcalls,
+	  the default uses the leader-follower model to allow multiple
+	  threads to wait on a single reactor for several concurrent
+	  requests;
+	  sometimes this configuration can be an overkill,
+	  if only one thread is using a reactor at the same time a
+	  lighter weight implementation can be used.
+	</P>
+	<P>This configuration is controled by the
+	  <CODE>-ORBclientconnectionhandler</CODE> option,
+	  good opportunities to use this option are:
+	</P>
+	<UL>
+	  <LI>Single threaded servers</LI>
+	  <LI>Servers running in ORB-per-thread mode</LI>
+	  <LI>Pure clients that will never receive a request</LI>
+	</UL>
+	<P></P>
+      </LI>
+      <LI><B>Allocator for input CDR streams</B>
+	Normally the application has no access to this buffer, and it
+	is only used on the demarshaling of arguments (or results).
+	It is almost always better to use the
+	"<CODE>-ORBinputcdrallocator tss</CODE>" option since it will
+	allocate memory from a thread specific allocator and it will
+	not need locks to manage that memory.
+	
+	<P>In some cases the user <I>may</I> gain access to the CDR
+	  stream buffer:
+	  TAO makes no copies when demarshaling octet sequences,
+	  instead the octet sequence simply points to the CDR buffer,
+	  since the octet sequence does not own this buffer a copy must
+	  be made if the user wants to keep the buffer after the
+	  upcall.
+	</P>
+	
+	<P>The user can, however, increase the reference count on the
+	  CDR stream buffer, thus allowing her to extend the lifetime
+	  of this buffer.
+	  Still passing this buffer to another thread and attempting
+	  to release it in that thread will result in some memory leak
+	  or corruption.
+	  Users willing to use this feature of TAO can still do so,
+	  <B>if</B> they use a global allocator for their input CDR
+	  stream, but that will introduce extra locking on the
+	  critical path.
+	</P>
+
+	<P>As the reader can see this is an option that has limited
+	  applicability and requires careful consideration of the
+	  tradeoffs involved.</P>
+      </LI>
 
     </UL>