[vietj]

Motivation

WriteStream flow control relies on writeQueueFull/drainHandler methods, only its usage in a context is race free, there can be several types of races depending on the implementation of the stream, the thread doing the operation, the concurrency, etc...

This aims to improve and replace this API by providing an atomic view of a write operation. A WriteResult API result extending Future<Void> provides an atomic view of the write operation:

• a writable field signaling whether the channel remains writable (replaces WriteStream#writeQueueFull)
• a drainHandler signaling when the channel becomes writable again (replaces WriteStream#drainHandler)
• extends Future providing the outcome of the result operation

Sample usage pattern, implementing a pipe:

void pipe(ReadStream<Buffer> src, WriteStream<Buffer> dst) {
  src.handler(chunk -> {
    WriteResult result = dst.write(chunk);
    if (!result.isWritable()) {
      src.pause();
      result.drainHandler(v -> {
        src.resume();
      });
    }
  });
}

It looks very similar to the actual pipe implementation but is actually race free.

Goals

• provide a base implementation in vertx-core and gradually to the stack.
• WriteStream#write returns a WriteResult, so do other write operations like HttpServerResponse#end(Buffer), this is a breaking change and will likely occur in Vert.x 6
• deprecate WriteStream#drainHandler and `WriteStream#writeQueueFull
• reimplement flow controlled write using the new API, ReadStream#pipe, RxJava WriteStream support, Reactive Streams bridge.

Todo

• provide support for correct implementation OutboundWriteQueue
  • signal queue close to write result
  • improve handle drained signal, it should be triggered by element depth crossing the low watermark during drain
• WriteStream flow control emulation using WriteResult
• WriteResult API
• Implementations
  • HTTP/1.1
  • HTTP/2
  • HTTP/3
  • TCP
  • QUIC
  • File system
  • ...