Question about Sink's poll_flush and channels: mpsc senders don't fully flush the buffer before returning Poll::Ready

[FSMaxB]

Maybe this is just a misunderstanding of what poll_flush actually means, but from the documentation I would expect poll_flush of the Sink trait to only return Poll::Ready once all buffered messages have been received by the Receiver of the channel, meaning the buffer is empty.

futures-rs/futures-sink/src/lib.rs

Lines 93 to 95 in 939614b

	/// Returns `Poll::Ready(Ok(()))` when no buffered items remain. If this
	/// value is returned then it is guaranteed that all previous values sent
	/// via `start_send` have been flushed.

Currently the Sink implementation for Sender and UnboundedSender don't do that though, making poll_flush almost equivalent to poll_ready. See:

futures-rs/futures-channel/src/mpsc/sink_impl.rs

Lines 17 to 25 in 939614b

	fn poll_flush(mut self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Result<(), Self::Error>> {
	match (*self).poll_ready(cx) {
	Poll::Ready(Err(ref e)) if e.is_disconnected() => {
	// If the receiver disconnected, we consider the sink to be flushed.
	Poll::Ready(Ok(()))
	}
	x => x,
	}
	}

In the Unbounded case, it doesn't flush anything at all:

futures-rs/futures-channel/src/mpsc/sink_impl.rs

Lines 44 to 46 in 939614b

	fn poll_flush(self: Pin<&mut Self>, _: &mut Context<'_>) -> Poll<Result<(), Self::Error>> {
	Poll::Ready(Ok(()))
	}

Is this intentional? And if so, how does this relate to the documentation of the Sink trait? Maybe the documentation can be updated to clarify this?

[e00E]

I wanted to create the same issue. Sender should document what it considers flushed in terms of Sink. The current behavior is that it is flushed when there is space to receive more messages. When the the capacity is 0 this is equivalent to the item having been read but it isn't at higher capacity. Since this is undocumented users might confuse the behavior.

[qutesy]

Same here: from the documentation for Sink::poll_flush(), I thought that poll_flush() indicated that all the data had been consumed.

Seeing that mpsc::{Sender,UnboundedSender} can return Poll::Ready when there is data still in the channel was surprising and confusing.