[rust] Clarify whether StreamResult::Dropped should have a count

[wingo]

Background

I wrote this version of pread the other day:

async fn pread(fd: &Descriptor, size: usize, offset: u64) -> Result<Vec<u8>, ErrorCode> {
    let (mut rx, future) = fd.read_via_stream(offset);
    let data = Vec::<u8>::with_capacity(size);
    let mut bytes_read = 0;
    let (mut result, mut data) = rx.read(data).await;
    loop {
        match result {
            StreamResult::Complete(n) => {
                assert!(n <= size - bytes_read);
                bytes_read += n;
                assert_eq!(data.len(), bytes_read);
                if bytes_read == size {
                    break;
                }
                (result, data) = rx.read(data).await;
            }
            StreamResult::Dropped => {
                assert_eq!(data.len(), bytes_read);
                break;
            }
            StreamResult::Cancelled => {
                panic!("who cancelled the stream?");
            }
        }
    };
    drop(rx);
    match future.await {
        Ok(()) => Ok(data),
        Err(err) => Err(err),
    }
}

Based on the signature of StreamResult::Dropped, I assumed that no bytes would have been transferred. But @alexcrichton kindly pointed out that in fact, the assertion here is actually incorrect:

            StreamResult::Dropped => {
                assert_eq!(data.len(), bytes_read);
                break;
            }

That is to say, Dropped can also be accompanied by data, and you can detect that via data.len() being larger than it was before the previous write / write_buf.

The issue

I would like for Dropped to have an items-transferred argument, like Complete. Strictly speaking it duplicates what is happening to data.len(), so another consistent option would be to remove items-transferred from Complete.

WDYT?

[wingo]

(If I misunderstood and Dropped will never be accompanied by data, please correct my misunderstanding!)

[alexcrichton]

Agreed, yes, Dropped (and Cancelled) should carry an integral payload of items transferred.