ReadHint in the readable callback of Handler

[wycats]

In #3, @rrichardson suggested that it would be useful for handlers to know when the remote side of a socket hangs up.

The epoll backend can support this via the EPOLLHUP and EPOLLRDHUP, but other backends do not expose this directly (and instead require the user to attempt to read from the fd to discover that the other side hung up). If this information is directly available, it can be useful as an optimization, even in portable code.

Since we want mio to make it easy to write portable code, it would be better not to expose this as an additional callback on Handler. If we did that, people who wanted to write portable code would have to write duplicate code in backend-specific handlers.

Instead, I suggest that we add a new parameter to the readable callback that provides backend-specific information if it's available. Since its goal is to make it easy to optimize portable code, in general, and cannot be generally relied on, I suggest calling an enum called ReadableHint.

enum ReadableHint {
    Data, // data is available
    Hup, // the other side of the socket hung up
    Error, // there was an error
    Unknown // the backend does not provide the hint
}

[wycats]

Just as a follow-up, I expect three usage patterns:

• The totally portable consumer, which will just ignore the hint totally. It will discover a hangup in a portable way, by reading and getting 0. This consumer will ignore the hint.
• The totally OS-specific consumer, which will expect a certain hint to be present if it is available. This consumer will expect one of the non-Unknown hints to be present (and fail if the value is Unknown).
• The optimizing portable consumer, which will use the hint if it's present, but do the portable behavior if the hint is Unknown.