[PATCH] doc: various comments on async handling

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

Notes for future developers (myself included) since we
can't assume people can read my mind.
---
 lib/PublicInbox/GitHTTPBackend.pm | 2 +-
 lib/PublicInbox/HTTPD.pm          | 2 ++
 lib/PublicInbox/Listener.pm       | 6 +++++-
 3 files changed, 8 insertions(+), 2 deletions(-)

diff --git a/lib/PublicInbox/GitHTTPBackend.pm b/lib/PublicInbox/GitHTTPBackend.pm
index 1987a01..a069fd9 100644
--- a/lib/PublicInbox/GitHTTPBackend.pm
+++ b/lib/PublicInbox/GitHTTPBackend.pm
@@ -227,7 +227,7 @@ sub serve_smart {
 		$r->[0] == 403 ? serve_dumb($env, $git, $path) : $r;
 	};
 	my $res;
-	my $async = $env->{'pi-httpd.async'};
+	my $async = $env->{'pi-httpd.async'}; # XXX unstable API
 	my $io = $env->{'psgix.io'};
 	my $cb = sub {
 		my $r = $rd_hdr->() or return;
diff --git a/lib/PublicInbox/HTTPD.pm b/lib/PublicInbox/HTTPD.pm
index 433d6da..fb47662 100644
--- a/lib/PublicInbox/HTTPD.pm
+++ b/lib/PublicInbox/HTTPD.pm
@@ -29,6 +29,8 @@ sub new {
 		'psgi.multiprocess' => Plack::Util::TRUE,
 		'psgix.harakiri'=> Plack::Util::FALSE,
 		'psgix.input.buffered' => Plack::Util::TRUE,
+
+		# XXX unstable API!
 		'pi-httpd.async' => do {
 			no warnings 'once';
 			*pi_httpd_async
diff --git a/lib/PublicInbox/Listener.pm b/lib/PublicInbox/Listener.pm
index 5f351a7..a3a2015 100644
--- a/lib/PublicInbox/Listener.pm
+++ b/lib/PublicInbox/Listener.pm
@@ -13,7 +13,7 @@ require IO::Handle;
 sub new ($$$) {
 	my ($class, $s, $cb) = @_;
 	setsockopt($s, SOL_SOCKET, SO_KEEPALIVE, 1);
-	setsockopt($s, IPPROTO_TCP, TCP_NODELAY, 1);
+	setsockopt($s, IPPROTO_TCP, TCP_NODELAY, 1); # ignore errors on non-TCP
 	listen($s, 1024);
 	IO::Handle::blocking($s, 0);
 	my $self = fields::new($class);
@@ -26,8 +26,12 @@ sub new ($$$) {
 sub event_read {
 	my ($self) = @_;
 	my $sock = $self->{sock};
+
 	# no loop here, we want to fairly distribute clients
 	# between multiple processes sharing the same socket
+	# XXX our event loop needs better granularity for
+	# a single accept() here to be, umm..., acceptable
+	# on high-traffic sites.
 	if (my $addr = accept(my $c, $sock)) {
 		IO::Handle::blocking($c, 0); # no accept4 :<
 		$self->{post_accept}->($c, $addr, $sock);
-- 
EW