[PATCH 1/3] httpd: document pi-httpd.async as totally unstable

[Eric Wong <e@80x24.org>]

We'll have to use it some more before deciding it is a public
interface.  I do hope for it to be a usable public interface
one day for other users.
---
 lib/PublicInbox/GitHTTPBackend.pm | 2 +-
 script/public-inbox-httpd         | 4 ++++
 2 files changed, 5 insertions(+), 1 deletion(-)

diff --git a/lib/PublicInbox/GitHTTPBackend.pm b/lib/PublicInbox/GitHTTPBackend.pm
index 56bf24f..c84eefc 100644
--- a/lib/PublicInbox/GitHTTPBackend.pm
+++ b/lib/PublicInbox/GitHTTPBackend.pm
@@ -224,7 +224,7 @@ sub serve_smart {
 	if (my $async = $env->{'pi-httpd.async'}) {
 		$rpipe = $async->($rpipe, $cb);
 		sub { ($res) = @_ } # let Danga::Socket handle the rest.
-	} else { # synchronous loop
+	} else { # synchronous loop for other PSGI servers
 		$vin = '';
 		vec($vin, fileno($rpipe), 1) = 1;
 		sub {
diff --git a/script/public-inbox-httpd b/script/public-inbox-httpd
index f1a5d79..d407059 100755
--- a/script/public-inbox-httpd
+++ b/script/public-inbox-httpd
@@ -59,6 +59,10 @@ daemon_run('0.0.0.0:8080', $refresh,
 
 1;
 
+# XXX This is a totally unstable API for public-inbox internal use only
+# This is exposed via the 'pi-httpd.async' key in the PSGI env hash.
+# The name of this key is not even stable!
+# Currently is is intended for use with read-only pipes.
 package PublicInbox::HTTPD::Async;
 use strict;
 use warnings;
-- 
EW