63 lines
2.4 KiB
Plaintext
63 lines
2.4 KiB
Plaintext
[/
|
|
/ Copyright (c) 2003-2019 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 Boost.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 asynchronous 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. Boost.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 boost_asio.reference.async_read async_read()],
|
|
[link boost_asio.reference.async_write async_write()],
|
|
[link boost_asio.reference.read read()],
|
|
[link boost_asio.reference.write write()],
|
|
[link boost_asio.reference.AsyncReadStream AsyncReadStream],
|
|
[link boost_asio.reference.AsyncWriteStream AsyncWriteStream],
|
|
[link boost_asio.reference.SyncReadStream SyncReadStream],
|
|
[link boost_asio.reference.SyncWriteStream SyncWriteStream].
|
|
|
|
[endsect]
|