square
Update docs for readTimeout and writeTimeout with more detail
I'm trying to understand the behavior of OkHttpClient/Builder/readTimeout and .../writeTimeout.
I'm finding that the current docs omit significant details. So I'm "falling back" on third-party docs that I'm not sure I can trust.
For example, from the Baeldung page "A Quick Guide to Timeouts in OkHttp":
A read timeout is applied from the moment the connection between a client and a target host has been successfully established. It defines a maximum time of inactivity between two data packets when waiting for the server's response.
Whoa. The read timeout clock starts ticking from the moment the connection is established?!
That seems odd to me, and also seems to contradict the answer by @swankjesse to my recent question on Stack Overflow, "OkHttp readTimeout start and stop events?".
OkHttp can reuse existing connections. If the read timeout for a call "is applied" (starts?) from "the moment the connection [is] established", then that might have been a long time, many calls, ago.
I acknowledge that I could be misinterpreting the Baeldung page, Jesse's answer, or both. A clearer description of readTimeout in the official OkHttp docs would help here.
Similarly, for writeTimeout: does Okio PR 196 apply here; is the OkHttp write timeout applied per 64 KB chunk of the request? Should the OkHttp docs mention this? Or are those docs deliberately non-specific in this regard? If so, how is an OkHttp user supposed to "join the dots" between writeTimeout and this Okio behavior?
The readTimeout and writeTimeout settings apply to individual calls.
Each time OkHttp attempts to read a byte from the server, that starts the clock on the readTimeout. If that particular read doesn’t complete within the timeout, that particular read will fail. The setting doesn’t care when the connection was initially established; it only cares on each read attempt.
Symmetrically the writeTimeout applies when flushing data from your application’s memory into the TCP socket’s outbound buffer. This will trigger if that buffer fills up and stays filled before the peer sends an ACK.
Closing as not planned.
It's a reasonable request, but hasn't been prioritised. As discussion shows there are existing external documentation also.
