qspawn: improve variable naming and commenting

Naming $start_cb consistently helps avoid confusing new readers,
and some comments will help with understanding flow

2 files changed, 10 insertions, 8 deletions

diff --git a/lib/PublicInbox/GitHTTPBackend.pm b/lib/PublicInbox/GitHTTPBackend.pm
index c9a7cff8..ec8e6516 100644
--- a/lib/PublicInbox/GitHTTPBackend.pm
+++ b/lib/PublicInbox/GitHTTPBackend.pm
@@ -204,7 +204,7 @@ sub serve_smart {
         $env{PATH_TRANSLATED} = "$git->{git_dir}/$path";
         my $rdr = input_prepare($env) or return r(500);
         my $qsp = PublicInbox::Qspawn->new([qw(git http-backend)], \%env, $rdr);
-        $qsp->psgi_return($env, $limiter, sub {
+        $qsp->psgi_return($env, $limiter, sub { # parse_hdr
                 my ($r, $bref) = @_;
                 my $res = parse_cgi_headers($r, $bref) or return; # incomplete
                 $res->[0] == 403 ? serve_dumb($env, $git, $path) : $res;
diff --git a/lib/PublicInbox/Qspawn.pm b/lib/PublicInbox/Qspawn.pm
index 10fe5341..5a300644 100644
--- a/lib/PublicInbox/Qspawn.pm
+++ b/lib/PublicInbox/Qspawn.pm
@@ -44,7 +44,7 @@ sub new ($$$;) {
 }
 
 sub _do_spawn {
-        my ($self, $cb, $limiter) = @_;
+        my ($self, $start_cb, $limiter) = @_;
         my $err;
         my ($cmd, $env, $opts) = @{$self->{args}};
         my %opts = %{$opts || {}};
@@ -66,7 +66,7 @@ sub _do_spawn {
         } else {
                 $self->{err} = $!;
         }
-        $cb->($self->{rpipe});
+        $start_cb->($self->{rpipe});
 }
 
 sub child_err ($) {
@@ -135,11 +135,11 @@ sub finish ($;$) {
 }
 
 sub start {
-        my ($self, $limiter, $cb) = @_;
+        my ($self, $limiter, $start_cb) = @_;
         if ($limiter->{running} < $limiter->{max}) {
-                _do_spawn($self, $cb, $limiter);
+                _do_spawn($self, $start_cb, $limiter);
         } else {
-                push @{$limiter->{run_queue}}, [ $self, $cb ];
+                push @{$limiter->{run_queue}}, [ $self, $start_cb ];
         }
 }
 
@@ -175,11 +175,12 @@ reread:
                 }
         };
         $limiter ||= $def_limiter ||= PublicInbox::Qspawn::Limiter->new(32);
-        $self->start($limiter, sub { # may run later, much later...
+        $self->start($limiter, sub { # start_cb, may run later, much later...
                 ($rpipe) = @_; # popen_rd result
                 if ($async) {
                 # PublicInbox::HTTPD::Async->new($rpipe, $cb, $end)
                         $async = $async->($rpipe, $cb, $end);
+                        # $cb will call ->async_pass or ->close
                 } else { # generic PSGI
                         $cb->() while $qx;
                 }
@@ -254,7 +255,7 @@ sub psgi_return {
                 $ret;
         };
 
-        my $wcb = delete $env->{'qspawn.wcb'};
+        my $wcb = delete $env->{'qspawn.wcb'}; # or PSGI server supplies it
         my $async = $env->{'pi-httpd.async'};
 
         my $cb = sub {
@@ -287,6 +288,7 @@ sub psgi_return {
                 if ($async) {
                         # PublicInbox::HTTPD::Async->new($rpipe, $cb, $end)
                         $async = $async->($rpipe, $cb, $end);
+                        # $cb will call ->async_pass or ->close
                 } else { # generic PSGI
                         $cb->() while $rd_hdr;
                 }