[asio] read_until -- possibly misleading documentation?
The documentation for Boost.ASIO (which is otherwise very comprehensive) says of the boost::asio::read_until set of overloads: | Read data into a streambuf until a delimiter is | encountered. <http://www.boost.org/doc/libs/1_35_0/doc/html/boost_asio/reference/read_until.html> What the function actually does is to read blocks of data into the streambuf, and stop when the delimiter is found. This means that frequently data beyond the delimiter will be read into the streambuf. (And this is elaborated in more detail on the individual function's pages, if a reader looks there.) I appreciate that this behaviour is compatible with the documentation, but someone less familiar with ASIO could easily assume that the function will read as far as the delimiter and no further. (And I have just spent a fair amount of time debugging a piece of code where the author had made this assumption.) Could we change the summary documentation to read something like: | Read data into a streambuf at least until a delimiter is | encountered. The implementation may read beyond the | delimiter, but will not block when doing so. While I'm on the subject of ASIO documentation, I can't see any documentation on whether the service_name parameters to the basic_resolver_query constructors are allowed to be port numbers (e.g. "80") or whether they have to be symbolic names (e.g. "http"). Port numbers work, at least on Linux, but it's not clear whether this is something that I should be relying on. Similarly for IPv4 and IPv6 addresses in the host_name parameter. Richard Smith
Richard Smith wrote:
Could we change the summary documentation to read something like:
| Read data into a streambuf at least until a delimiter is | encountered. The implementation may read beyond the | delimiter, but will not block when doing so.
That's a bit on the long side for a brief description, but I've made some tweaks along those lines. Hopefully they will make the behaviour clearer.
While I'm on the subject of ASIO documentation, I can't see any documentation on whether the service_name parameters to the basic_resolver_query constructors are allowed to be port numbers (e.g. "80") or whether they have to be symbolic names (e.g. "http"). Port numbers work, at least on Linux, but it's not clear whether this is something that I should be relying on. Similarly for IPv4 and IPv6 addresses in the host_name parameter.
The behaviour is intended to be as-if getaddrinfo was used, and that function supports numbers as strings. So yes, you can rely on this behaviour. Cheers, Chris
Christopher Kohlhoff <chris <at> kohlhoff.com> writes:
Richard Smith wrote:
Could we change the summary documentation to read something like:
| Read data into a streambuf at least until a delimiter is | encountered. The implementation may read beyond the | delimiter, but will not block when doing so.
That's a bit on the long side for a brief description, but I've made some tweaks along those lines. Hopefully they will make the behaviour clearer.
While I'm on the subject of ASIO documentation, I can't see any documentation on whether the service_name parameters to the basic_resolver_query constructors are allowed to be port numbers (e.g. "80") or whether they have to be symbolic names (e.g. "http"). Port numbers work, at least on Linux, but it's not clear whether this is something that I should be relying on. Similarly for IPv4 and IPv6 addresses in the host_name parameter.
The behaviour is intended to be as-if getaddrinfo was used, and that function supports numbers as strings. So yes, you can rely on this behaviour.
Cheers, Chris
_______________________________________________ Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
----------------------------------------------------------------- ----------------------------------------------------------------- As a side note - it seems the read_until documentation is still confusing. The sample HTTP client is using read_until incorrectly and (from some actual testing) will over-read in certain cases and cause exceptions to be thrown due to end-of-file issues. The sample is here: http://www.boost.org/doc/libs/1_42_0/doc/html/boost_asio/examples.html#boost... o.examples.http_client and I think it will likely mislead a lot of people as to the usage. I'd fix it, but I ended up not using read_until at all since it really rather confusing.
participants (3)
-
Bijan -
Christopher Kohlhoff -
Richard Smith