Fix futures_util::io::copy & copy_buf to allow aborting operation in the middle

[kazuki0824]

Summary

When transferring data from one place to another using the copy_buf function, you may want to abort the operation in the middle of the transfer. Since the transfer is divided into small increments by internal buffers and probably must not be done at a time, the interruption logic can be implemented by checking for the aborting request flag at every poll_fill_buf().

This patch has

• a bunch of modification that introduces a new behaviour, similar to what futures::abortable::Abortable does, into CopyBuf.
• changes of return values coming from copy_buf(...) & copy(...), which can break backward compatibility a little.
• changes of visibility of some Abortable-related private members, such as AbortInner and its children.

How to use

Unlike before, copy() & copy_buf() returns the combination of Future and AbortHandle. If you want to abort the operation, you should extract the tuple and trigger the inner AbortHandle.

Backward compatibility

If you want to fit the existing code to this change, all you have to do is simply adding ".0" after every copy_buf() or copy().

[taiki-e]

Thanks for the PR!

• copy is a very common function, and most of its use cases do not require this feature. If you want to add this feature, I would prefer to add it as a separate function.

• Is it possible to do this same thing by implementing AsyncRead/AsyncWrite for Abortable? If so, that would be more generic and preferable.

[kazuki0824]

Thanks for your reply! I understood your ideas.

Workaround

Implementing this as a separate module function sounds fine to me, so I re-implemented it as another module.

Suggestion

* Is it possible to do this same thing by implementing AsyncRead/AsyncWrite for Abortable? If so, that would be more generic and preferable.

IMHO, I think it is a bit hard to realize copy() by simply adding AsyncRead/AsyncWrite to Abortable.

What is the problem?

If we read file and make it abortable, we have to

1. open File by futures::io::BufReader
2. make it abortable by Abortable::new(file)

In addition, if we want to perform copying, then we have to
3. into_async_read()
4. futures::io::copy().
(Here, we have to use AsyncRead instead of stream::Abortable. if you deal with character devices or sockets, There is no guarantee that the size of the file will be limited. Since forward() in futures::stream reads all, and then write all, that cannot be used.)

Conclusion

I also think that for more convenience, something like AsyncRead / AsyncWrite 'd abortable is necessary. I agree to you at this point. (also mentioned in #2156)

But simply implementing Async io with existing stream::Abortable may cause inconvenience in the case such as copying, mentioned above.

[kazuki0824]

I fetched upstream into my branch accidentally and the history went dirty, so I force-pushed and the pr got closed. I'll create another one.