Note on SIGCHLD

The requirements for a proper "SIGCHLD" handling are:

• avoid zombie processes of our forked children by calling waitpid() on them,
• allow follow up code to evaluate the status of e.g. sytem() calls or doing own waitpid() on children not forked by "OpenXPKI::Server::Bedroom",
• avoid interfering with Net::Server's "SIGCHLD" handler,
• keep the "OpenXPKI::Server::Bedroom" instance that contains the "SIGCHLD" handler alive as long as there are child processes. Destroying the instance too early could lead to errors: without resetting "SIGCHLD" handler to 'IGNORE' a finished child process would raise the error "Signal SIGCHLD received, but no signal handler set". When set to 'IGNORE' e.g. a following system() call from code higher up the hierarchy would fail.

The most compatible way to handle "SIGCHLD" is to set it to 'DEFAULT', letting Perl handle it. This way commands like system() will work properly.

But for the "OpenXPKI::Server::Bedroom" parent process to be able to reap its child processes we need a custom "SIGCHLD" handler to call waitpid() on them. So in our custom handler we keep track of the PIDs of our own forked children and only reap those. Other children (e.g. forked via system()) are left untouched.

Thus there are two usage modes:

1. Default ("keep_parent_sigchld => 0"):

Parent: install custom "SIGCHLD" handler (NOT compatible with "Net::Server" parent process, reaps children forked by us, system() compatible)

Child: inherit parent's custom handler

2. "keep_parent_sigchld => 1" (for use in "Net::Server" parent process):

Parent: do not touch "SIGCHLD" handler (to keep "Net::Server"'s handler, reaps children forked by us via existing handler, NOT system() compatible)

Child: set "$SIG{'CHLD'} = 'DEFAULT'".

If this object is destroyed while the $SIG{'CHLD'} still refers to our handler then children exiting later on will raise the internal Perl error "Signal SIGCHLD received, but no signal handler set."

That is why in "DEMOLISH" we explicitely hand over child reaping to the operating system. But this also means after this the process will not be able to call system() and the like anymore. So a better solution is to keep this object alive as long as possible, ideally until "OpenXPKI::Server" shuts down.

Also see <https://github.com/Perl/perl5/issues/17662>, might be related.

Also see <https://perldoc.perl.org/perlipc#Signals>.

new_child

Tries to fork a child process.

Return value depends on who returns: parent will get the child PID and child will get 0.

An exception will be thrown if the fork fails.

Note on STDIN, STDOUT, STDERR

All IO handles will be connected to /dev/null with one exception: if "STDERR" was already redirected to a file (and is not a terminal) then it is left untouched. This is to make sure error messages still go to the desired log files.

Parameters

• "max_fork_redo" Int - optional: max. retries in case forking fails. Default: 5.
• "sighup_handler" CodeRef - optional: handler for "SIGHUP" signals.
• "sigterm_handler" CodeRef - optional: handler for "SIGTERM" signals.
• "uid" Int - optional: user ID to set for the newly forked child process. Default: do not change ID.
• "gid" Int - optional: group ID to set for the newly forked child process. Default: do not change ID.
• "keep_parent_sigchld" Bool - optional: 1 = parent: keep currently installed "SIGCHLD" handler, child: set "SIGCHLD" to "default". Default: 0
• "capture_stdout" Bool - optional: 1 = redirect child process STDOUT to a filehandle that can be queried using "get_stdout_fh". Default: 0

get_stdout_fh

Returns the STDOUT filehandle for the given child pid. Is "undef" if the child process was not started using "new_child(... capture_stdout => 1)".

Parameters

•

$pid Int - child process PID

DEMOLISH

Hand "SIGCHLD" processing over to operating system via "$SIG{'CHLD'} = 'IGNORE'", see "Note on SIGCHLD".