diff options
author | Steve Huston <shuston@riverace.com> | 2007-01-11 22:17:31 +0000 |
---|---|---|
committer | Steve Huston <shuston@riverace.com> | 2007-01-11 22:17:31 +0000 |
commit | 3eb798f1ecc5b5a11dd0b077d6896f1371e501bc (patch) | |
tree | 2f2265e1b87ac7c80cdd9b0ed592ffb046cbe8e8 /ACE/ace/SOCK_Stream.h | |
parent | bac33110244aa0170b0e7b9ee6563d22ea6a6ab7 (diff) | |
download | ATCD-3eb798f1ecc5b5a11dd0b077d6896f1371e501bc.tar.gz |
ChangeLogTag:Thu Jan 11 21:42:47 UTC 2007 Steve Huston <shuston@riverace.com>
Diffstat (limited to 'ACE/ace/SOCK_Stream.h')
-rw-r--r-- | ACE/ace/SOCK_Stream.h | 73 |
1 files changed, 35 insertions, 38 deletions
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, |