diff options
Diffstat (limited to '3rdparty/asio/src/doc/overview/streams.qbk')
-rw-r--r-- | 3rdparty/asio/src/doc/overview/streams.qbk | 62 |
1 files changed, 62 insertions, 0 deletions
diff --git a/3rdparty/asio/src/doc/overview/streams.qbk b/3rdparty/asio/src/doc/overview/streams.qbk new file mode 100644 index 00000000000..ea89e8b5d62 --- /dev/null +++ b/3rdparty/asio/src/doc/overview/streams.qbk @@ -0,0 +1,62 @@ +[/ + / Copyright (c) 2003-2016 Christopher M. Kohlhoff (chris at kohlhoff dot com) + / + / Distributed under the Boost Software License, Version 1.0. (See accompanying + / file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) + /] + +[section:streams Streams, Short Reads and Short Writes] + +Many I/O objects in Asio are stream-oriented. This means that: + +* There are no message boundaries. The data being transferred is a continuous + sequence of bytes. + +* Read or write operations may transfer fewer bytes than requested. This is + referred to as a short read or short write. + +Objects that provide stream-oriented I/O model one or more of the following +type requirements: + +* `SyncReadStream`, where synchronous read operations are performed using a + member function called `read_some()`. + +* `AsyncReadStream`, where asynchronous read operations are performed using a + member function called `async_read_some()`. + +* `SyncWriteStream`, where synchronous write operations are performed using a + member function called `write_some()`. + +* `AsyncWriteStream`, where synchronous write operations are performed using a + member function called `async_write_some()`. + +Examples of stream-oriented I/O objects include `ip::tcp::socket`, +`ssl::stream<>`, `posix::stream_descriptor`, `windows::stream_handle`, etc. + +Programs typically want to transfer an exact number of bytes. When a short read +or short write occurs the program must restart the operation, and continue to +do so until the required number of bytes has been transferred. Asio provides +generic functions that do this automatically: `read()`, `async_read()`, +`write()` and `async_write()`. + +[heading Why EOF is an Error] + +* The end of a stream can cause `read`, `async_read`, `read_until` or + `async_read_until` functions to violate their contract. E.g. + a read of N bytes may finish early due to EOF. + +* An EOF error may be used to distinguish the end of a stream from a successful + read of size 0. + +[heading See Also] + +[link asio.reference.async_read async_read()], +[link asio.reference.async_write async_write()], +[link asio.reference.read read()], +[link asio.reference.write write()], +[link asio.reference.AsyncReadStream AsyncReadStream], +[link asio.reference.AsyncWriteStream AsyncWriteStream], +[link asio.reference.SyncReadStream SyncReadStream], +[link asio.reference.SyncWriteStream SyncWriteStream]. + +[endsect] |