ChangeLogTag:Mon Oct 14 10:12:31 2002 Steve Huston <shuston@riverace.com>

7 files changed, 61 insertions, 31 deletions

diff --git a/ChangeLog b/ChangeLog
index 3d026fa2fca..a814b38023c 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -43,6 +43,11 @@ Sun Oct 13 19:38:35 2002  Krishnakumar B  <kitty@cse.wustl.edu>
           originally. This should fix all the build breakage. Thanks to
           Bala for pointing out the errors in the build.
 
+Sun Oct 13 18:50:53 2002  Douglas C. Schmidt  <schmidt@tango.doc.wustl.edu>
+
+	* ace/SPIPE_Stream.h: Enhanced the documentation of ACE_SPIPE_Stream.
+	  Thanks to Pat McNerthney <ace@mcnerthney.com> for motivating
+ 	  this.
 
 Sun Oct 13 15:57:04 2002  Balachandran Natarajan  <bala@isis-server.isis.vanderbilt.edu>
 
diff --git a/ChangeLogs/ChangeLog-03a b/ChangeLogs/ChangeLog-03a
index 3d026fa2fca..a814b38023c 100644
--- a/ChangeLogs/ChangeLog-03a
+++ b/ChangeLogs/ChangeLog-03a
@@ -43,6 +43,11 @@ Sun Oct 13 19:38:35 2002  Krishnakumar B  <kitty@cse.wustl.edu>
           originally. This should fix all the build breakage. Thanks to
           Bala for pointing out the errors in the build.
 
+Sun Oct 13 18:50:53 2002  Douglas C. Schmidt  <schmidt@tango.doc.wustl.edu>
+
+	* ace/SPIPE_Stream.h: Enhanced the documentation of ACE_SPIPE_Stream.
+	  Thanks to Pat McNerthney <ace@mcnerthney.com> for motivating
+ 	  this.
 
 Sun Oct 13 15:57:04 2002  Balachandran Natarajan  <bala@isis-server.isis.vanderbilt.edu>
 
diff --git a/THANKS b/THANKS
index 694adb32e11..06bcd6514c1 100644
--- a/THANKS
+++ b/THANKS
@@ -317,7 +317,7 @@ John Lindal <jafl@cheshire-cat.caltech.edu>
 Dustin Laurence <laurence@alice.wonderland.caltech.edu>
 Ernie Makris <emakris@ziplink.net>
 Timothy A. Brown <tabrown@montana.com>
-Patrick J. McNerthney <pat@cartia.com>
+Pat McNerthney <ace@mcnerthney.com>
 Lori Anderson <lori@probita.com>
 Erik Margraf <erik@asgard.gud.siemens.co.at>
 Bryan Doerr <Bryan.S.Doerr@boeing.com>
@@ -1586,6 +1586,7 @@ Erich Hochmuth <erich_hochmuth@hotmail.com>
 Nick S. Petrov <nicksp@ci.nnov.ru>
 Dmitry Botcharnikov <dimab@garant.ru>
 Philippe Haussy <p.haussy@xpedite.com>
+k2@biogate.com
 Eric Frias <efrias@syncad.com>
 
 I would particularly like to thank Paul Stephenson, who worked with me
diff --git a/ace/Pipe.cpp b/ace/Pipe.cpp
index 85f84575717..63979297e4b 100644
--- a/ace/Pipe.cpp
+++ b/ace/Pipe.cpp
@@ -102,7 +102,7 @@ ACE_Pipe::open (int buffer_size)
     }
 # endif /* ! ACE_LACKS_SOCKET_BUFSIZ */
 
-#elif defined (ACE_HAS_STREAM_PIPES) || defined(__QNX__)
+#elif defined (ACE_HAS_STREAM_PIPES) || defined (__QNX__)
   ACE_UNUSED_ARG (buffer_size);
   if (ACE_OS::pipe (this->handles_) == -1)
     ACE_ERROR_RETURN ((LM_ERROR,
diff --git a/ace/SPIPE_Acceptor.h b/ace/SPIPE_Acceptor.h
index 9a739a3e646..91b83173706 100644
--- a/ace/SPIPE_Acceptor.h
+++ b/ace/SPIPE_Acceptor.h
@@ -6,8 +6,8 @@
  *
  *  $Id$
  *
- *  @author Doug Schmidt
- *  @author Prashant Jain
+ *  @author Douglas C. Schmidt <schmidt@cs.wustl.edu>
+ *  @author Prashant Jain <pjain@cs.wustl.edu>
  */
 //=============================================================================
 
diff --git a/ace/SPIPE_Connector.h b/ace/SPIPE_Connector.h
index 83fadc40904..c84fd5151ea 100644
--- a/ace/SPIPE_Connector.h
+++ b/ace/SPIPE_Connector.h
@@ -24,8 +24,9 @@
 /**
  * @class ACE_SPIPE_Connector
  *
- * @brief Defines an active connection factory for the STREAM pipe
- * wrappers.
+ * @brief Defines an active connection factory for <ACE_SPIPE_Stream>.
+ * On Windows this is mapped to Named Pipes, whereas on UNIX it is
+ * mapped to STREAM pipes.  
  */
 class ACE_Export ACE_SPIPE_Connector
 {
diff --git a/ace/SPIPE_Stream.h b/ace/SPIPE_Stream.h
index ad778fda45d..340a0dccc4c 100644
--- a/ace/SPIPE_Stream.h
+++ b/ace/SPIPE_Stream.h
@@ -6,11 +6,10 @@
  *
  *  $Id$
  *
- *  @author Doug Schmidt
+ *  @author Douglas C. Schmidt <schmidt@cs.wustl.edu>
  */
 //=============================================================================
 
-
 #ifndef ACE_SPIPE_STREAM_H
 #define ACE_SPIPE_STREAM_H
 #include "ace/pre.h"
@@ -27,7 +26,26 @@
 /**
  * @class ACE_SPIPE_Stream
  *
- * @brief Define an ACE_SPIPE_Stream.
+ * @brief Defines the methods in the <ACE_SPIPE_Stream> abstraction.
+ *
+ * <buf> is the buffer to write from or receive into.
+ * <len> is the number of bytes to transfer.
+ *
+ * The "_n()" I/O methods keep looping until all the data has been
+ * transferred.  These methods also work for sockets in non-blocking
+ * mode i.e., they keep looping on EWOULDBLOCK.
+ *
+ * The return values for the "*_n()" methods match the return values
+ * from the non "_n()" methods and are specified as follows:
+ * - The number of bytes transferred is returned.
+ * - On error, -1 is returned, errno is set to appropriate error.
+ * - On EOF, 0 is returned, errno is irrelevant.
+ *
+ * Methods with <iovec> parameter are I/O vector variants of the I/O
+ * operations.
+ * 
+ * The <send> and <revc> operations use "message" semantics rather
+ * than "bytestream" semantics.  
  */
 class ACE_Export ACE_SPIPE_Stream : public ACE_SPIPE
 {
@@ -51,17 +69,17 @@ public:
   /// Recv an open FD from another process.
   int recv_handle (strrecvfd &recvfd) const;
 
-  /// Send n bytes, keep trying until n are sent.
-  ssize_t send_n (const void *buf, size_t n) const;
+  /// Send <len> bytes, keep trying until <len> are sent.
+  ssize_t send_n (const void *buf, size_t len) const;
 
-  /// Recv n bytes, keep trying until n are received.
-  ssize_t recv_n (void *buf, size_t n) const;
+  /// Recv <len> bytes, keep trying until <len> are received.
+  ssize_t recv_n (void *buf, size_t len) const;
 
   /// Send bytes via STREAM pipes using "band" mode.
-  ssize_t send (const void *buf, size_t n) const;
+  ssize_t send (const void *buf, size_t len) const;
 
   /// Recv bytes via STREAM pipes using "band" mode.
-  ssize_t recv (void *buf, size_t n) const;
+  ssize_t recv (void *buf, size_t len) const;
 
   /// Send <cntl> and <data> via STREAM pipes.
   ssize_t send (const ACE_Str_Buf *cntl,
@@ -85,11 +103,11 @@ public:
                 int *band,
                 int *flags) const;
 
-  /// Send iovecs via <::writev>.
-  ssize_t send (const iovec iov[], int n) const;
+  /// Send iovecs via the OS "gather-write" operation.
+  ssize_t send (const iovec iov[], int len) const;
 
-  /// Recv iovecs via <::readv>.
-  ssize_t recv (iovec iov[], int n) const;
+  /// Recv iovecs via the OS "scatter-read" operation.
+  ssize_t recv (iovec iov[], int len) const;
 
   /**
    * Send N char *ptrs and int lengths.  Note that the char *'s
@@ -97,7 +115,7 @@ public:
    * count N is the *total* number of trailing arguments, *not* a
    * couple of the number of tuple pairs!
    */
-  ssize_t send (size_t n, ...) const;
+  ssize_t send (size_t len, ...) const;
 
   /**
    * This is an interface to ::readv, that doesn't use the struct
@@ -106,26 +124,26 @@ public:
    * *total* number of trailing arguments, *not* a couple of the
    * number of tuple pairs!
    */
-  ssize_t recv (size_t n, ...) const;
+  ssize_t recv (size_t len, ...) const;
 
-  /// Send <n> bytes via Win32 WriteFile using overlapped I/O.
-  ssize_t send (const void *buf, size_t n, ACE_OVERLAPPED *overlapped) const;
+  /// Send <len> bytes via Win32 <WriteFile> using overlapped I/O.
+  ssize_t send (const void *buf, size_t len, ACE_OVERLAPPED *overlapped) const;
 
-  /// Recv <n> bytes via Win32 ReadFile using overlapped I/O.
-  ssize_t recv (void *buf, size_t n, ACE_OVERLAPPED *overlapped) const;
+  /// Recv <len> bytes via Win32 <ReadFile> using overlapped I/O.
+  ssize_t recv (void *buf, size_t len, ACE_OVERLAPPED *overlapped) const;
 
-  /// Send an <iovec> of size <n> to the stream.
+  /// Send an <iovec> of size <len> to the stream.
   ssize_t sendv (const iovec iov[],
-                 int n) const;
+                 int len) const;
 
-  /// Send an <iovec> of size <n> to the stream.  Will block until all
+  /// Send an <iovec> of size <len> to the stream.  Will block until all
   /// bytes are sent or an error occurs.
   ssize_t sendv_n (const iovec iov[],
-                   int n) const;
+                   int len) const;
 
-  /// Receive an <iovec> of size <n> to the stream.
+  /// Receive an <iovec> of size <len> to the stream.
   ssize_t recvv_n (iovec iov[],
-                   int n) const;
+                   int len) const;
 
   // = Meta-type info
   typedef ACE_SPIPE_Addr PEER_ADDR;