Repository navigation
Conversation
|
|
||
| ## Unresolved Questions | ||
|
|
||
| ### Clarify `Poll::Pending` vs. `Poll::Ready(())` |
There was a problem hiding this comment.
this remains the largest open question to me. in hyperium/http-body#90, the question was raised about why we model this as a Poll<Result<(), E>>. one alternative was suggested:
It's done purely so you can
?-propagate errors in the implementation. MaybePoll<Result<!, E>>would be better?
to me this indicates that there is not a meaningful distinction between these. the error is the interesting value, otherwise we are indicating whether or not progress was made by the body.
There was a problem hiding this comment.
tokio::net::TcpStream::poll_peek() may be a useful comparison to make here:
Note that on multiple calls to
poll_peek,poll_readorpoll_read_ready, only theWakerfrom theContextpassed to the most recent call is scheduled to receive a wakeup.
perhaps the relationship between poll_frame and poll_progress could be described in similar terms. they are both mechanisms to poll a body, one of which does not expose the possibility of yielding a frame, and the Waker from the most recent call will receive a wakeup.
There was a problem hiding this comment.
Yeah, IMO the only reason to use Poll here is so that it works more cleanly with ready!() etc. Now that ! is a real type in 1.100, the Poll<Result<!, E>> option may be reasonable?
There was a problem hiding this comment.
@sfackler, i agree. there's a section below this that describes the alternative approach of representing this using the ! type, since it came up in previous discussions about this. as i've looked at this proposal more, it seems like the ideal solution to me as well.
using ! means that we end up with a signature that is clearer about the intended use of poll_progress(), and also means that we do not need to document as many rules about it being fused, for example. eliminating the Poll::Ready(()) case altogether seems like the right choice if it does not have a meaningful distinction from Poll::Pending.
the cost of using ! would be a step forward in our MSRV. since this is a foundational trait that isn't often subject to change, getting this right feels worth the cost of a minor delay in shipping this until 1.100 is within bounds of our MSRV policy.
i'd be happy to rework this draft to instead recommend using Poll<Result<!, E>>, if we agree that it's the right direction. what do you think, @seanmonstar?
There was a problem hiding this comment.
Haven't thought too much about the greater question. But, just noting that std::convert::Infallible is a type alias to ! in 1.100. 🤓
There was a problem hiding this comment.
Haven't thought too much about the greater question. But, just noting that
std::convert::Infallibleis a type alias to!in 1.100. 🤓
that's a very useful observation. in that case, Poll<Result<Infallible, E>> sounds like the ideal return type. i will rework the "Recommendation" section of this document to reflect this. i will update the "Rules" section as well, which should be dramatically simplified by this change.
thank you both for your input!
| ## User Experience | ||
|
|
||
| ## Implementation | ||
|
|
||
| ## Testing Plan | ||
|
|
||
| (Optional: are there any special considerations for testing required?) | ||
|
|
||
| ## Security Considerations | ||
|
|
||
| (What security risks might exist for the recommendation? Can we reduce them? | ||
| What should users consider when using it?) |
There was a problem hiding this comment.
todo: these still need to be filled out. i don't see much unknown here, compared to the Pending question above.
There was a problem hiding this comment.
It's OK if there aren't any, we can just say so. But here's some questions I have off the top of my head:
- Could a wrong implementation result in truncated messages?
- Could combinators that forward to a wrapped body incorrectly?
- Could a default implementation that one forgets to override lost data?
- Could this be used as a solution to what some may feel are security issues, like stalled streams?
| consumers that a stream should be aborted. | ||
|
|
||
| <!-- markdownlint-disable-next-line heading-increment --> | ||
| #### The Rules of `poll_progress()` |
There was a problem hiding this comment.
i've tried to outline "the rules" of this method here, in part to seed discussion about guarantees and edge cases.
to briefly summarize: (1) poll_progress() is always optional. (2) an error from poll_progress() should be treated as cause to discard the body, just like an error returned from poll_frame(). (3) poll_progress() may be called repeatedly.
b1ede02 to
e6a5fd0
Compare
Signed-off-by: katelyn martin <git@katelyn.world>
e6a5fd0 to
3355ea1
Compare
|
Thanks for writing this up! Excited to see this start to move forward :) |
Rendered
note: this is still a working draft, but i wanted to open this up as i continue to flesh this proposal out.
Important
Please make line comments, instead of comments on the PR as a whole. It makes discussion much easier to keep untangled.