Description
For Future
, poll
should not be called again after it returns Poll::Ready
(terminating the future).
For Stream
, poll_next
should not be called again after it returns Poll::Ready(None)
(terminating the stream).
I would like clarification on the equivalent contract for Sink
, when one of its methods emits an error.
The documentation blurbs for poll_ready
, start_send
, and poll_flush
state:
In most cases, if the sink encounters an error, the sink will permanently be unable to receive items.
Whereas the blurb for poll_close
states:
If this function encounters an error, the sink should be considered to have failed permanently, and no more Sink methods should be called.
I'm interpreting this to mean that if any of poll_ready
, start_send
, and poll_flush
emit an error, than none of poll_ready
, start_send
, or poll_flush
can be called again on the same sink; however, poll_close
can still be called. Whereas if poll_close
emits an error, than none of poll_ready
, start_send
, poll_flush
, or poll_close
can be called again on the same sink.
Do I have that right? The phrase "unable to receive items" is not totally clear. For example, I could understand interpreting it to mean that poll_flush
may be called again after poll_ready
emits an error, as poll_flush
is not about "receiving items", only processing ones that have already been submitted. However, that would imply that poll_flush
can be called again after poll_flush
emits an error, which I find strange.