ChangeLogTag:Thu Jan 11 21:42:47 UTC 2007 Steve Huston <shuston@riverace.com>

3 files changed, 42 insertions, 39 deletions

diff --git a/ACE/ChangeLog b/ACE/ChangeLog
index 8ef4ea94313..4dcfe920c50 100644
--- a/ACE/ChangeLog
+++ b/ACE/ChangeLog
@@ -1,3 +1,9 @@
+Thu Jan 11 21:42:47 UTC 2007  Steve Huston  <shuston@riverace.com>
+
+        * ace/Message_Block.h: Comment typos.
+        * ace/SOCK_Stream.h: Corrected documentation for what the
+          _n() variants do with timeouts.
+
 Thu Jan 11 15:27:27 UTC 2007  Phil Mesnier  <mesnier_p@ociweb.com>
 
         * docs/ACE-guidelines.html:
diff --git a/ACE/ace/Message_Block.h b/ACE/ace/Message_Block.h
index 0c343b266fe..1588e16dd3a 100644
--- a/ACE/ace/Message_Block.h
+++ b/ACE/ace/Message_Block.h
@@ -395,7 +395,7 @@ public:
 
   /// Normalizes data in the top-level <Message_Block> to align with the base,
   /// i.e., it "shifts" the data pointed to by <rd_ptr> down to the <base> and
-  /// then readjusts <rt_ptr> to point to <base> and <wr_ptr> to point
+  /// then readjusts <rd_ptr> to point to <base> and <wr_ptr> to point
   /// to <base> + the length of the moved data.  Returns -1 and does
   /// nothing if the <rd_ptr> is > <wr_ptr>, else 0 on success.
   int crunch (void);
diff --git a/ACE/ace/SOCK_Stream.h b/ACE/ace/SOCK_Stream.h
index 9537162a4d3..aa69b8ba596 100644
--- a/ACE/ace/SOCK_Stream.h
+++ b/ACE/ace/SOCK_Stream.h
@@ -35,38 +35,7 @@ class ACE_Message_Block;
  * This adds additional wrapper methods atop the ACE_SOCK_IO
  * class.
  *
- * <buf> is the buffer to write from or receive into.
- * <len> is the number of bytes to transfer.
- * The <timeout> parameter in the following methods indicates how
- * long to blocking trying to transfer data.  If <timeout> == 0,
- * then the call behaves as a normal send/recv call, i.e., for
- * blocking sockets, the call will block until action is possible;
- * for non-blocking sockets, EWOULDBLOCK will be returned if no
- * action is immediately possible.
- * If <timeout> != 0, the call will wait for data to arrive no longer
- * than the relative time specified in *<timeout>.
- * 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.  <timeout> is used
- * to make sure we keep making progress, i.e., the same timeout
- * value is used for every I/O operation in the loop and the timeout
- * is not counted down.
- * The return values for the "*_n()" methods match the return values
- * from the non "_n()" methods and are specified as follows:
- * - On complete transfer, the number of bytes transferred is returned.
- * - On timeout, -1 is returned, errno == ETIME.
- * - On error, -1 is returned, errno is set to appropriate error.
- * - On EOF, 0 is returned, errno is irrelevant.
- *
- * On partial transfers, i.e., if any data is transferred before
- * timeout/error/EOF, <bytes_transferred> will contain the number of
- * bytes transferred.
- * Methods with <iovec> parameter are I/O vector variants of the I/O
- * operations.
- * Methods with the extra <flags> argument will always result in
- * <send> getting called. Methods without the extra <flags> argument
- * will result in <send> getting called on Win32 platforms, and
- * <write> getting called on non-Win32 platforms.
+ * @sa ACE_SOCK_IO
  */
 class ACE_Export ACE_SOCK_Stream : public ACE_SOCK_IO
 {
@@ -83,18 +52,46 @@ public:
 
   /** @name Counted send/receive methods
    *
-   * The counted send/receive methods attempt to send a specified number of
-   * bytes even if they must block and retry the operation in order to
+   * The counted send/receive methods attempt to transfer a specified number
+   * of bytes even if they must block and retry the operation in order to
    * transfer the entire amount. The time spent blocking for the entire
    * transfer can be limited by a specified ACE_Time_Value object which is
    * a relative time (i.e., a fixed amount of time, not an absolute time
    * of day). These methods return the count of transferred bytes, or -1
-   * if an error occurs or the operation times out. In error or timeout
-   * situations it's possible that some data was transferred before the error
+   * if an error occurs or the operation times out before the entire requested
+   * amount of data has been transferred. In error or timeout situations it's
+   * possible that some data was transferred before the error
    * or timeout. The @c bytes_transferred parameter is used to obtain the
    * count of bytes transferred before the error or timeout occurred. If the
    * total specified number of bytes is transferred without error, the
    * method return value should equal the value of @c bytes_transferred.
+   *
+   * @param buf      The buffer to write from or receive into.
+   * @param iov      An I/O vector containing a specified number of
+   *                 count/pointer pairs directing the data to be transferred.
+   * @param iovcnt   The number of I/O vectors to be used from @arg iov.
+   * @param len      The number of bytes to transfer.
+   * @param flags    Flags that will be passed through to the @c recv()
+   *                 system call.
+   * @param timeout  Indicates how long to blocking trying to transfer data.
+   *                 If no timeout is supplied (timeout == 0) the method will
+   *                 wait indefinitely or until an error occurs for the
+   *                 specified number of bytes to be transferred.
+   *                 To avoid any waiting, specify a timeout value with
+   *                 0 seconds.
+   * @param bytes_transferred If non-0, points to a location which receives
+   *                 the total number of bytes transferred before the method
+   *                 returns, even if it's less than the number requested.
+   *
+   * @retval      len, the complete number of bytes transferred.
+   * @retval      0  EOF, i.e., the peer closed the connection.
+   * @retval      -1 an error occurred before the entire amount was
+   *                 transferred. Check @c errno for more information.
+   *                 If the @arg timeout period is reached, errno is ETIME.
+   *
+   * On partial transfers, i.e., if any data is transferred before
+   * timeout/error/EOF, *@arg bytes_transferred will contain the number of
+   * bytes transferred.
    */
   //@{
   /// Try to recv exactly @a len bytes into @a buf from the connected socket.
@@ -116,7 +113,7 @@ public:
                    const ACE_Time_Value *timeout = 0,
                    size_t *bytes_transferred = 0) const;
 
-  /// Try to send exactly @a len bytes from @a buf>to the connection socket.
+  /// Try to send exactly @a len bytes from @a buf to the connection socket.
   ssize_t send_n (const void *buf,
                   size_t len,
                   int flags,
@@ -129,7 +126,7 @@ public:
                   const ACE_Time_Value *timeout = 0,
                   size_t *bytes_transferred = 0) const;
 
-  /// Send all the @c message_block's chained through their @c next and
+  /// Send all the message blocks chained through their @c next and
   /// @c cont pointers.  This call uses the underlying OS gather-write
   /// operation to reduce the domain-crossing penalty.
   ssize_t send_n (const ACE_Message_Block *message_block,