From 48caaf751fa68907da9eb3b4e0980f3076316ac7 Mon Sep 17 00:00:00 2001 From: quininer Date: Fri, 15 Oct 2021 02:15:39 +0800 Subject: [PATCH] Add poll_write docs (#73) --- tokio-rustls/src/lib.rs | 36 ++++++++++++++++++++++++++++++++++++ 1 file changed, 36 insertions(+) diff --git a/tokio-rustls/src/lib.rs b/tokio-rustls/src/lib.rs index 1e3caf7..d849cb2 100644 --- a/tokio-rustls/src/lib.rs +++ b/tokio-rustls/src/lib.rs @@ -1,4 +1,40 @@ //! Asynchronous TLS/SSL streams for Tokio using [Rustls](https://github.com/ctz/rustls). +//! +//! # Why do I need to call `poll_flush`? +//! +//! Most TLS implementations will have an internal buffer to improve throughput, +//! and rustls is no exception. +//! +//! When we write data to `TlsStream`, we always write rustls buffer first, +//! then take out rustls encrypted data packet, and write it to data channel (like TcpStream). +//! When data channel is pending, some data may remain in rustls buffer. +//! +//! `tokio-rustls` To keep it simple and correct, [TlsStream] will behave like `BufWriter`. +//! For `TlsStream`, this means that data written by `poll_write` is not guaranteed to be written to `TcpStream`. +//! You must call `poll_flush` to ensure that it is written to `TcpStream`. +//! +//! You should call `poll_flush` at the appropriate time, +//! such as when a period of `poll_write` write is complete and there is no more data to write. +//! +//! ## Why don't we write during `poll_read`? +//! +//! We did this in the early days of `tokio-rustls`, but it caused some bugs. +//! We can solve these bugs through some solutions, but this will cause performance degradation (reverse false wakeup). +//! +//! And reverse write will also prevent us implement full duplex in the future. +//! +//! see +//! +//! ## Why can't we handle it like `native-tls`? +//! +//! When data channel returns to pending, `native-tls` will falsely report the number of bytes it consumes. +//! This means that if data written by `poll_write` is not actually written to data channel, it will not return `Ready`. +//! Thus avoiding the call of `poll_flush`. +//! +//! but which does not conform to convention of `AsyncWrite` trait. +//! This means that if you give inconsistent data in two `poll_write`, it may cause unexpected behavior. +//! +//! see macro_rules! ready { ( $e:expr ) => {