Index access depreciated

[AndyGauge]

Fixes #697

[ahmedcharles]

It should be possible to provide an impl of ExactSizeIterator which would retain access to the len function.

[carllerche]

Ah, specifically I do not want the exact size to be exposed. This allows the iterator to skip or insert events during iteration.

[AndyGauge]

Should we not return the number of polled events since we do not know the exact number?

[carllerche]

Yeah, we should definitely not return the number... We have to leave it for now, but that return value should be deprecated.

[AndyGauge]

What about a 0 or 1? Return 0 for no events (like a timeout) and 1 if there is at least one?

[carllerche]

Yeah, I think some return value like that could be good, but it will have to be punted until 0.7. We can open an issue to track that change. The ret value today will have to stay the same :(

[carllerche]

Thanks! Looks good. Would you mind also updating the documentation for Poll::poll to indicate that the usize return variable is deprecated and will be removed in 0.7?

[AndyGauge]

Sure, once the tests finish I'll get that done. I meant to ask how to deprecate the return value!

[carllerche]

@AndyGauge I think it has to just be part of the fn docs as well as do a pass of the rest of the docs / tests to ensure it isn't being used.

Maybe @alexcrichton has a better idea?

[alexcrichton]

Nah yeah there's no way I know of to deprecate just the return value, but you could temporarily switch it to a bool and that'd flag every location that needs to be fixed up internally at least

[AndyGauge]

Found an example that needs to be reworked. Poll::deregister example (poll.rs#892)

    /// // Set a timeout because this poll should never receive any events.
    /// let n = poll.poll(&mut events, Some(Duration::from_secs(1)))?;
    /// assert_eq!(0, n);

Looking for high level guidance how this should be addressed.

[carllerche]

I think checking for zero right now is OK. It's the only way to test if poll returned due to event OR due to timeout. When the return value is changed, it will have some equivalent API to check if n == 0.

[AndyGauge]

That's why I wanted to bring it to your attention. We likely need to create a convenience for this case like .empty or whatever makes sense for your API

[carllerche]

Ah, so basically add a test fn on the Events instead of rely on the return value. I think that might be an interesting idea.

[carllerche]

Ok, I think the answer will be to add Events::is_empty().

This PR is good as is, so I'll create a tracking issue for this.