From 5a84875c2d13c357ef5f0b252bce57410bb54223 Mon Sep 17 00:00:00 2001
From: Anna Henningsen <anna@addaleax.net>
Date: Tue, 12 Apr 2016 21:50:05 +0200
Subject: [PATCH 1/2] doc: Note that zlib.flush acts after pending writes

Describe that `zlib.flush()` may wait for pending writes and
until output is being read from the stream.
---
 doc/api/zlib.markdown | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/doc/api/zlib.markdown b/doc/api/zlib.markdown
index da20024ca2109f..7493cf15c893ba 100644
--- a/doc/api/zlib.markdown
+++ b/doc/api/zlib.markdown
@@ -282,6 +282,11 @@ class of the compressor/decompressor classes.
 Flush pending data. Don't call this frivolously, premature flushes negatively
 impact the effectiveness of the compression algorithm.
 
+Calling this only flushes data from the internal zlib state, and does not
+perform flushing of any kind on the streams level. Rather, it behaves like a
+normal call to `.write()`, i.e. it will be queued up behind other pending
+writes and will only produce output when data is being read from the stream.
+
 ### zlib.params(level, strategy, callback)
 
 Dynamically update the compression level and compression strategy.

From b81e3e2b365a867ca097ec60ef919e9e23d94fc7 Mon Sep 17 00:00:00 2001
From: Anna Henningsen <anna@addaleax.net>
Date: Tue, 19 Apr 2016 10:04:07 +0200
Subject: [PATCH 2/2] doc: add full example for zlib.flush()

Add a full example using `zlib.flush()` for the common use
case of writing partial compressed HTTP output to the client.
---
 doc/api/zlib.markdown | 31 +++++++++++++++++++++++++++++++
 1 file changed, 31 insertions(+)

diff --git a/doc/api/zlib.markdown b/doc/api/zlib.markdown
index 7493cf15c893ba..537b39efe268e3 100644
--- a/doc/api/zlib.markdown
+++ b/doc/api/zlib.markdown
@@ -155,6 +155,36 @@ fewer calls to zlib, since it'll be able to process more data in a
 single `write` operation.  So, this is another factor that affects the
 speed, at the cost of memory usage.
 
+## Flushing
+
+Calling [`.flush()`][] on a compression stream will make zlib return as much
+output as currently possible. This may come at the cost of degraded compression
+quality, but can be useful when data needs to be available as soon as possible.
+
+In the following example, `flush()` is used to write a compressed partial
+HTTP response to the client:
+```js
+const zlib = require('zlib');
+const http = require('http');
+
+http.createServer((request, response) => {
+  // For the sake of simplicity, the Accept-Encoding checks are omitted.
+  response.writeHead(200, { 'content-encoding': 'gzip' });
+  const output = zlib.createGzip();
+  output.pipe(response);
+
+  setInterval(() => {
+    output.write(`The current time is ${Date()}\n`, () => {
+      // The data has been passed to zlib, but the compression algorithm may
+      // have decided to buffer the data for more efficient compression.
+      // Calling .flush() will make the data available as soon as the client
+      // is ready to receive it.
+      output.flush();
+    });
+  }, 1000);
+}).listen(1337);
+```
+
 ## Constants
 
 <!--type=misc-->
@@ -383,4 +413,5 @@ Decompress a Buffer or string with Unzip.
 [Inflate]: #zlib_class_zlib_inflate
 [InflateRaw]: #zlib_class_zlib_inflateraw
 [Unzip]: #zlib_class_zlib_unzip
+[`.flush()`]: #zlib_zlib_flush_kind_callback
 [Buffer]: buffer.html