NAME

       Test2::Harness::Util::IPC - Utilities for IPC management.

DESCRIPTION

       This package provides low-level IPC tools for Test2::Harness.

EXPORTS

       All exports are optional and must be specified at import time.

       $bool = USE_P_GROUPS()
           This is a shortcut for:

               use Config qw/%Config/;
               $Config{'d_setpgrp'};

       swap_io($from, $to)
       swap_io($from, $to, \&die)
           This  will  close  and re-open the file handle designated by $from so that it redirects to the handle
           specified in $to. It preserves the file descriptor in the process, and  throws  an  exception  if  it
           fails to do so.

               swap_io(\*STDOUT, $fh);
               # STDOUT now points to wherever $fh did, but maintains the file descriptor number '2'.

           As  long as the file descriptor is greater than 0 it will open for writing. If the descriptor is 0 it
           will open for reading, allowing for a swap of "STDIN" as well.

           Extra effort is made to insure errors go to the real "STDERR", specially  when  trying  to  swap  out
           "STDERR".  If  you  have trouble with this, or do not trust it, you can provide a custom coderef as a
           third argument, this coderef will be used instead of die() to throw exceptions.

           Note that the custom die logic when you do not provide  your  own  bypasses  the  exception  catching
           mechanism  and  will exit your program. If this is not desirable then you should provide a custom die
           subref.

       $pid = run_cmd(command => [...], %params)
           This function will run the specified command and return a pid to you. When possible this will be done
           via fork() and exec(). When that is not possible it uses the "system(1, ...)" trick to  spawn  a  new
           process. Some parameters do not work in the second case, and are silently ignored.

           Parameters:

           command => [$command, sub { ... }, @args]
           command => sub { return ($command, @args) }
               This  parameter  is  required.  This  should  either be an arrayref of arguments for exec(), or a
               coderef that returns a list of arguments for exec(). On systems without fork/exec  the  arguments
               will be passed to "system(1, $command, @args)" instead.

               If the command arrayref has a coderef in it, the coderef will be run and its return value(s) will
               be inserted in its place. This replacement happens post-chroot

           run_in_parent => [sub { ... }, sub { ... }]
               An  arrayref  of  callbacks to be run in the parent process immedietly after the child process is
               started.

           run_in_child => [sub { ... }, sub { ... }]
               An arrayref of callbacks to be run in the child process immedietly after fork.  This parameter is
               silently ignored on systems without fork/exec.

           env => { ENVVAR => $VAL, ... }
               A hashref of custom environment variables to set in the child process.  In  the  fork/exec  model
               this is done post-fork, in the spawn model this is done via local prior to the spawn.

           no_set_pgrp => $bool,
               Normall  "setpgrp(0,0)" is called on systems where it is supported. You can use this parameter to
               override the normal behavior. setpgrp() is not called in the spawn model, so  this  parameter  is
               silently ignored there.

           chdir => 'path/to/dir'
           ch_dir => 'path/to/dir'
               chdir() to the specified directory for the new process. In the fork/exec model this is done post-
               fork  in  the child. In the spawn model this is done before the spawn, then a second chdir() puts
               the parent process back to its original dir after the spawn.

           stdout => $handle
           stderr => $handle
           stdin  => $handle
               Thise can be used to provide custom STDERR, STDOUT, and STDIN. In the fork/exec model  these  are
               swapped into place post-fork in the child. In the spawn model the swap occurs pre-spawn, then the
               old handles are swapped back post-spawn.

SOURCE

       The source code repository for Test2-Harness can be found at http://github.com/Test-More/Test2-Harness/.

MAINTAINERS

       Chad Granum <exodist@cpan.org>

AUTHORS

       Chad Granum <exodist@cpan.org>

COPYRIGHT

       Copyright 2020 Chad Granum <exodist7@gmail.com>.

       This  program  is  free  software;  you can redistribute it and/or modify it under the same terms as Perl
       itself.

       See http://dev.perl.org/licenses/

perl v5.38.2                                       2024-03-08                     Test2::Harness::Util::IPC(3pm)