process_pipe: warn hackers off using it for bidirectional pipes

While most uses of ->DESTROY happens in a predictable order in
long-lived daemons, process teardown on exit is chaotic and not
subject to ordering guarantees, so we must keep both ends of a
`git cat-file --batch*' pipe at the same level in the object
hierarchy.

Drop an old Carp import while I'm in the area.

2 files changed, 5 insertions, 2 deletions

diff --git a/lib/PublicInbox/Git.pm b/lib/PublicInbox/Git.pm
index ff3ac40f..a3813bf2 100644
--- a/lib/PublicInbox/Git.pm
+++ b/lib/PublicInbox/Git.pm
@@ -156,6 +156,7 @@ sub _bidi_pipe {
                 $self->{$err} = $fh;
                 $rdr->{2} = $fh;
         }
+        # see lib/PublicInbox/ProcessPipe.pm for why we don't use that here
         my ($in_r, $p) = popen_rd(\@cmd, undef, $rdr);
         awaitpid($self->{$pid} = $p, undef);
         $self->{"$pid.owner"} = $$;
diff --git a/lib/PublicInbox/ProcessPipe.pm b/lib/PublicInbox/ProcessPipe.pm
index 068631c6..1bc792c4 100644
--- a/lib/PublicInbox/ProcessPipe.pm
+++ b/lib/PublicInbox/ProcessPipe.pm
@@ -1,10 +1,12 @@
 # Copyright (C) all contributors <meta@public-inbox.org>
 # License: AGPL-3.0+ <https://www.gnu.org/licenses/agpl-3.0.txt>
 
-# a tied handle for auto reaping of children tied to a pipe, see perltie(1)
+# a tied handle for auto reaping of children tied to a read-only pipe, see perltie(1)
+# DO NOT use this as-is for bidirectional pipes/sockets (e.g. in PublicInbox::Git),
+# both ends of the pipe must be at the same level of the Perl object hierarchy
+# to ensure orderly destruction.
 package PublicInbox::ProcessPipe;
 use v5.12;
-use Carp qw(carp);
 use PublicInbox::DS qw(awaitpid);
 
 sub waitcb { # awaitpid callback