Document the current Poll::poll timeout behaviour

[Thomasdezeeuw]

/cc @danielparks

Closes #1600

[Thomasdezeeuw]

What do you think @danielparks?

[danielparks]

Looks good. Thanks!

[jkarneges]

Hmm. My interpretation of the updated documentation is that mio's poll is free to return something other than Ok(()) if the call times out. Is that intentional? This would mean all apps would need to be very defensive and swallow all errors. Else apps risk crashing if a future version of mio decides to return Err on timeout.

Based on the discussion in #1600, I suspect the documentation was meant to say something like: "timeouts always return Ok(()), and a return value of Ok(()) with zero events likely indicates a timeout but is not guaranteed to be a timeout". This is quite a different claim, and would not require apps to swallow all errors.

[Thomasdezeeuw]

Hmm. My interpretation of the updated documentation is that mio's poll is free to return something other than Ok(()) if the call times out. Is that intentional? This would mean all apps would need to be very defensive and swallow all errors. Else apps risk crashing if a future version of mio decides to return Err on timeout.

Based on the discussion in #1600, I suspect the documentation was meant to say something like: "timeouts always return Ok(()), and a return value of Ok(()) with zero events likely indicates a timeout but is not guaranteed to be a timeout". This is quite a different claim, and would not require apps to swallow all errors.

This documentation intends to document that we follow whatever the OS does, we have no special handling for timeouts. At the moment that means it return Ok(()). However a new implementation might return an error on timeout, we'll have consider it when it comes up.