From mboxrd@z Thu Jan  1 00:00:00 1970
Return-Path: <e@80x24.org>
X-Spam-Checker-Version: SpamAssassin 3.4.2 (2018-09-13) on dcvr.yhbt.net
X-Spam-Level: 
X-Spam-ASN:  
X-Spam-Status: No, score=-4.0 required=3.0 tests=ALL_TRUSTED,BAYES_00
	shortcircuit=no autolearn=ham autolearn_force=no version=3.4.2
Received: from localhost (dcvr.yhbt.net [127.0.0.1])
	by dcvr.yhbt.net (Postfix) with ESMTP id 9C8B81F463
	for <meta@public-inbox.org>; Sat, 14 Sep 2019 09:35:39 +0000 (UTC)
From: Eric Wong <e@80x24.org>
To: meta@public-inbox.org
Subject: [PATCH] httpd/async: improve naming and comments
Date: Sat, 14 Sep 2019 09:35:39 +0000
Message-Id: <20190914093539.32586-1-e@80x24.org>
MIME-Version: 1.0
Content-Transfer-Encoding: 8bit
List-Id: <meta.public-inbox.org>

Rename the {cleanup} field to {end}, since it's similar
to END {} and is consistent with the variable in Qspawn.pm

And document how certain subs get called, since we have
many subs named "new" and "close".
---
 lib/PublicInbox/HTTPD/Async.pm | 37 ++++++++++++++++++++++++----------
 lib/PublicInbox/Qspawn.pm      |  4 +++-
 2 files changed, 29 insertions(+), 12 deletions(-)

diff --git a/lib/PublicInbox/HTTPD/Async.pm b/lib/PublicInbox/HTTPD/Async.pm
index 8e8ece39..d5628ee8 100644
--- a/lib/PublicInbox/HTTPD/Async.pm
+++ b/lib/PublicInbox/HTTPD/Async.pm
@@ -10,26 +10,29 @@ package PublicInbox::HTTPD::Async;
 use strict;
 use warnings;
 use base qw(PublicInbox::DS);
-use fields qw(cb cleanup);
+use fields qw(cb end);
 use Errno qw(EAGAIN);
 use PublicInbox::Syscall qw(EPOLLIN EPOLLET);
 
+# This is called via: $env->{'pi-httpd.async'}->()
+# $io is a read-only pipe ($rpipe) for now, but may be a
+# bidirectional socket in the future.
 sub new {
-	my ($class, $io, $cb, $cleanup) = @_;
+	my ($class, $io, $cb, $end) = @_;
 
 	# no $io? call $cb at the top of the next event loop to
 	# avoid recursion:
 	unless (defined($io)) {
 		PublicInbox::DS::requeue($cb);
-		die 'cleanup unsupported w/o $io' if $cleanup;
+		die '$end unsupported w/o $io' if $end;
 		return;
 	}
 
 	my $self = fields::new($class);
 	IO::Handle::blocking($io, 0);
 	$self->SUPER::new($io, EPOLLIN | EPOLLET);
-	$self->{cb} = $cb;
-	$self->{cleanup} = $cleanup;
+	$self->{cb} = $cb; # initial read callback, later replaced by main_cb
+	$self->{end} = $end; # like END {}, but only for this object
 	$self;
 }
 
@@ -37,6 +40,8 @@ sub main_cb ($$) {
 	my ($http, $fh) = @_;
 	sub {
 		my ($self) = @_;
+		# $self->{sock} is a read pipe for git-http-backend or cgit
+		# and 65536 is the default Linux pipe size
 		my $r = sysread($self->{sock}, my $buf, 65536);
 		if ($r) {
 			$fh->write($buf); # may call $http->close
@@ -52,19 +57,28 @@ sub main_cb ($$) {
 		}
 
 		# Done! Error handling will happen in $fh->close
-		# called by the {cleanup} handler
+		# called by the {end} handler
 		delete $http->{forward};
-		$self->close;
+		$self->close; # queues ->{end} to be called
 	}
 }
 
+# once this is called, all data we read is passed to the
+# to the PublicInbox::HTTP instance ($http) via $fh->write
 sub async_pass {
 	my ($self, $http, $fh, $bref) = @_;
 	# In case the client HTTP connection ($http) dies, it
 	# will automatically close this ($self) object.
 	$http->{forward} = $self;
+
+	# write anything we overread when we were reading headers
 	$fh->write($$bref); # PublicInbox:HTTP::{chunked,identity}_wcb
-	$$bref = undef; # we're done with this
+
+	# we're done with this, free this memory up ASAP since the
+	# calls after this may use much memory:
+	$$bref = undef;
+
+	# replace the header read callback with the main one
 	my $cb = $self->{cb} = main_cb($http, $fh);
 	$cb->($self); # either hit EAGAIN or ->requeue to keep EPOLLET happy
 }
@@ -75,14 +89,15 @@ sub event_step {
 	$cb->(@_);
 }
 
+# may be called as $forward->close in PublicInbox::HTTP or EOF (main_cb)
 sub close {
 	my $self = $_[0];
 	delete $self->{cb};
-	$self->SUPER::close;
+	$self->SUPER::close; # DS::close
 
 	# we defer this to the next timer loop since close is deferred
-	if (my $cleanup = delete $self->{cleanup}) {
-		PublicInbox::DS::requeue($cleanup);
+	if (my $end = delete $self->{end}) {
+		PublicInbox::DS::requeue($end);
 	}
 }
 
diff --git a/lib/PublicInbox/Qspawn.pm b/lib/PublicInbox/Qspawn.pm
index 76e48e81..294bf0a4 100644
--- a/lib/PublicInbox/Qspawn.pm
+++ b/lib/PublicInbox/Qspawn.pm
@@ -230,6 +230,7 @@ sub psgi_return {
 
 	my $buf = '';
 	my $rd_hdr = sub {
+		# typically used for reading CGI headers
 		# we must loop until EAGAIN for EPOLLET in HTTPD/Async.pm
 		# We also need to check EINTR for generic PSGI servers.
 		my $ret;
@@ -250,7 +251,7 @@ sub psgi_return {
 
 	my $cb = sub {
 		my $r = $rd_hdr->() or return;
-		$rd_hdr = undef;
+		$rd_hdr = undef; # done reading headers
 		my $filter = delete $env->{'qspawn.filter'};
 		if (scalar(@$r) == 3) { # error
 			if ($async) {
@@ -261,6 +262,7 @@ sub psgi_return {
 			}
 			$wcb->($r);
 		} elsif ($async) {
+			# done reading headers, handoff to read body
 			$fh = $wcb->($r); # scalar @$r == 2
 			$fh = filter_fh($fh, $filter) if $filter;
 			$async->async_pass($env->{'psgix.io'}, $fh, \$buf);