diff options
Diffstat (limited to 'upstream/mageia-cauldron/man1/perlfork.1')
| -rw-r--r-- | upstream/mageia-cauldron/man1/perlfork.1 | 388 |
1 files changed, 388 insertions, 0 deletions
diff --git a/upstream/mageia-cauldron/man1/perlfork.1 b/upstream/mageia-cauldron/man1/perlfork.1 new file mode 100644 index 00000000..e4829041 --- /dev/null +++ b/upstream/mageia-cauldron/man1/perlfork.1 @@ -0,0 +1,388 @@ +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" ======================================================================== +.\" +.IX Title "PERLFORK 1" +.TH PERLFORK 1 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +perlfork \- Perl's fork() emulation +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 4 +\& NOTE: As of the 5.8.0 release, fork() emulation has considerably +\& matured. However, there are still a few known bugs and differences +\& from real fork() that might affect you. See the "BUGS" and +\& "CAVEATS AND LIMITATIONS" sections below. +.Ve +.PP +Perl provides a \fBfork()\fR keyword that corresponds to the Unix system call +of the same name. On most Unix-like platforms where the \fBfork()\fR system +call is available, Perl's \fBfork()\fR simply calls it. +.PP +On some platforms such as Windows where the \fBfork()\fR system call is not +available, Perl can be built to emulate \fBfork()\fR at the interpreter level. +While the emulation is designed to be as compatible as possible with the +real \fBfork()\fR at the level of the Perl program, there are certain +important differences that stem from the fact that all the pseudo child +"processes" created this way live in the same real process as far as the +operating system is concerned. +.PP +This document provides a general overview of the capabilities and +limitations of the \fBfork()\fR emulation. Note that the issues discussed here +are not applicable to platforms where a real \fBfork()\fR is available and Perl +has been configured to use it. +.SH DESCRIPTION +.IX Header "DESCRIPTION" +The \fBfork()\fR emulation is implemented at the level of the Perl interpreter. +What this means in general is that running \fBfork()\fR will actually clone the +running interpreter and all its state, and run the cloned interpreter in +a separate thread, beginning execution in the new thread just after the +point where the \fBfork()\fR was called in the parent. We will refer to the +thread that implements this child "process" as the pseudo-process. +.PP +To the Perl program that called \fBfork()\fR, all this is designed to be +transparent. The parent returns from the \fBfork()\fR with a pseudo-process +ID that can be subsequently used in any process-manipulation functions; +the child returns from the \fBfork()\fR with a value of \f(CW0\fR to signify that +it is the child pseudo-process. +.SS "Behavior of other Perl features in forked pseudo-processes" +.IX Subsection "Behavior of other Perl features in forked pseudo-processes" +Most Perl features behave in a natural way within pseudo-processes. +.ie n .IP "$$ or $PROCESS_ID" 8 +.el .IP "$$ or \f(CW$PROCESS_ID\fR" 8 +.IX Item "$$ or $PROCESS_ID" +This special variable is correctly set to the pseudo-process ID. +It can be used to identify pseudo-processes within a particular +session. Note that this value is subject to recycling if any +pseudo-processes are launched after others have been \fBwait()\fR\-ed on. +.ie n .IP %ENV 8 +.el .IP \f(CW%ENV\fR 8 +.IX Item "%ENV" +Each pseudo-process maintains its own virtual environment. Modifications +to \f(CW%ENV\fR affect the virtual environment, and are only visible within that +pseudo-process, and in any processes (or pseudo-processes) launched from +it. +.IP "\fBchdir()\fR and all other builtins that accept filenames" 8 +.IX Item "chdir() and all other builtins that accept filenames" +Each pseudo-process maintains its own virtual idea of the current directory. +Modifications to the current directory using \fBchdir()\fR are only visible within +that pseudo-process, and in any processes (or pseudo-processes) launched from +it. All file and directory accesses from the pseudo-process will correctly +map the virtual working directory to the real working directory appropriately. +.IP "\fBwait()\fR and \fBwaitpid()\fR" 8 +.IX Item "wait() and waitpid()" +\&\fBwait()\fR and \fBwaitpid()\fR can be passed a pseudo-process ID returned by \fBfork()\fR. +These calls will properly wait for the termination of the pseudo-process +and return its status. +.IP \fBkill()\fR 8 +.IX Item "kill()" +\&\f(CW\*(C`kill(\*(AqKILL\*(Aq, ...)\*(C'\fR can be used to terminate a pseudo-process by +passing it the ID returned by \fBfork()\fR. The outcome of kill on a pseudo-process +is unpredictable and it should not be used except +under dire circumstances, because the operating system may not +guarantee integrity of the process resources when a running thread is +terminated. The process which implements the pseudo-processes can be blocked +and the Perl interpreter hangs. Note that using \f(CW\*(C`kill(\*(AqKILL\*(Aq, ...)\*(C'\fR on a +pseudo\-\fBprocess()\fR may typically cause memory leaks, because the thread +that implements the pseudo-process does not get a chance to clean up +its resources. +.Sp +\&\f(CW\*(C`kill(\*(AqTERM\*(Aq, ...)\*(C'\fR can also be used on pseudo-processes, but the +signal will not be delivered while the pseudo-process is blocked by a +system call, e.g. waiting for a socket to connect, or trying to read +from a socket with no data available. Starting in Perl 5.14 the +parent process will not wait for children to exit once they have been +signalled with \f(CW\*(C`kill(\*(AqTERM\*(Aq, ...)\*(C'\fR to avoid deadlock during process +exit. You will have to explicitly call \fBwaitpid()\fR to make sure the +child has time to clean-up itself, but you are then also responsible +that the child is not blocking on I/O either. +.IP \fBexec()\fR 8 +.IX Item "exec()" +Calling \fBexec()\fR within a pseudo-process actually spawns the requested +executable in a separate process and waits for it to complete before +exiting with the same exit status as that process. This means that the +process ID reported within the running executable will be different from +what the earlier Perl \fBfork()\fR might have returned. Similarly, any process +manipulation functions applied to the ID returned by \fBfork()\fR will affect the +waiting pseudo-process that called \fBexec()\fR, not the real process it is +waiting for after the \fBexec()\fR. +.Sp +When \fBexec()\fR is called inside a pseudo-process then DESTROY methods and +END blocks will still be called after the external process returns. +.IP \fBexit()\fR 8 +.IX Item "exit()" +\&\fBexit()\fR always exits just the executing pseudo-process, after automatically +\&\fBwait()\fR\-ing for any outstanding child pseudo-processes. Note that this means +that the process as a whole will not exit unless all running pseudo-processes +have exited. See below for some limitations with open filehandles. +.IP "Open handles to files, directories and network sockets" 8 +.IX Item "Open handles to files, directories and network sockets" +All open handles are \fBdup()\fR\-ed in pseudo-processes, so that closing +any handles in one process does not affect the others. See below for +some limitations. +.SS "Resource limits" +.IX Subsection "Resource limits" +In the eyes of the operating system, pseudo-processes created via the \fBfork()\fR +emulation are simply threads in the same process. This means that any +process-level limits imposed by the operating system apply to all +pseudo-processes taken together. This includes any limits imposed by the +operating system on the number of open file, directory and socket handles, +limits on disk space usage, limits on memory size, limits on CPU utilization +etc. +.SS "Killing the parent process" +.IX Subsection "Killing the parent process" +If the parent process is killed (either using Perl's \fBkill()\fR builtin, or +using some external means) all the pseudo-processes are killed as well, +and the whole process exits. +.SS "Lifetime of the parent process and pseudo-processes" +.IX Subsection "Lifetime of the parent process and pseudo-processes" +During the normal course of events, the parent process and every +pseudo-process started by it will wait for their respective pseudo-children +to complete before they exit. This means that the parent and every +pseudo-child created by it that is also a pseudo-parent will only exit +after their pseudo-children have exited. +.PP +Starting with Perl 5.14 a parent will not \fBwait()\fR automatically +for any child that has been signalled with \f(CW\*(C`kill(\*(AqTERM\*(Aq, ...)\*(C'\fR +to avoid a deadlock in case the child is blocking on I/O and +never receives the signal. +.SH "CAVEATS AND LIMITATIONS" +.IX Header "CAVEATS AND LIMITATIONS" +.IP "BEGIN blocks" 8 +.IX Item "BEGIN blocks" +The \fBfork()\fR emulation will not work entirely correctly when called from +within a BEGIN block. The forked copy will run the contents of the +BEGIN block, but will not continue parsing the source stream after the +BEGIN block. For example, consider the following code: +.Sp +.Vb 5 +\& BEGIN { +\& fork and exit; # fork child and exit the parent +\& print "inner\en"; +\& } +\& print "outer\en"; +.Ve +.Sp +This will print: +.Sp +.Vb 1 +\& inner +.Ve +.Sp +rather than the expected: +.Sp +.Vb 2 +\& inner +\& outer +.Ve +.Sp +This limitation arises from fundamental technical difficulties in +cloning and restarting the stacks used by the Perl parser in the +middle of a parse. +.IP "Open filehandles" 8 +.IX Item "Open filehandles" +Any filehandles open at the time of the \fBfork()\fR will be \fBdup()\fR\-ed. Thus, +the files can be closed independently in the parent and child, but beware +that the \fBdup()\fR\-ed handles will still share the same seek pointer. Changing +the seek position in the parent will change it in the child and vice-versa. +One can avoid this by opening files that need distinct seek pointers +separately in the child. +.Sp +On some operating systems, notably Solaris and Unixware, calling \f(CWexit()\fR +from a child process will flush and close open filehandles in the parent, +thereby corrupting the filehandles. On these systems, calling \f(CW_exit()\fR +is suggested instead. \f(CW_exit()\fR is available in Perl through the +\&\f(CW\*(C`POSIX\*(C'\fR module. Please consult your system's manpages for more information +on this. +.IP "Open directory handles" 8 +.IX Item "Open directory handles" +Perl will completely read from all open directory handles until they +reach the end of the stream. It will then \fBseekdir()\fR back to the +original location and all future \fBreaddir()\fR requests will be fulfilled +from the cache buffer. That means that neither the directory handle held +by the parent process nor the one held by the child process will see +any changes made to the directory after the \fBfork()\fR call. +.Sp +Note that \fBrewinddir()\fR has a similar limitation on Windows and will not +force \fBreaddir()\fR to read the directory again either. Only a newly +opened directory handle will reflect changes to the directory. +.IP "Forking pipe \fBopen()\fR not yet implemented" 8 +.IX Item "Forking pipe open() not yet implemented" +The \f(CW\*(C`open(FOO, "|\-")\*(C'\fR and \f(CW\*(C`open(BAR, "\-|")\*(C'\fR constructs are not yet +implemented. This limitation can be easily worked around in new code +by creating a pipe explicitly. The following example shows how to +write to a forked child: +.Sp +.Vb 10 +\& # simulate open(FOO, "|\-") +\& sub pipe_to_fork ($) { +\& my $parent = shift; +\& pipe my $child, $parent or die; +\& my $pid = fork(); +\& die "fork() failed: $!" unless defined $pid; +\& if ($pid) { +\& close $child; +\& } +\& else { +\& close $parent; +\& open(STDIN, "<&=" . fileno($child)) or die; +\& } +\& $pid; +\& } +\& +\& if (pipe_to_fork(\*(AqFOO\*(Aq)) { +\& # parent +\& print FOO "pipe_to_fork\en"; +\& close FOO; +\& } +\& else { +\& # child +\& while (<STDIN>) { print; } +\& exit(0); +\& } +.Ve +.Sp +And this one reads from the child: +.Sp +.Vb 10 +\& # simulate open(FOO, "\-|") +\& sub pipe_from_fork ($) { +\& my $parent = shift; +\& pipe $parent, my $child or die; +\& my $pid = fork(); +\& die "fork() failed: $!" unless defined $pid; +\& if ($pid) { +\& close $child; +\& } +\& else { +\& close $parent; +\& open(STDOUT, ">&=" . fileno($child)) or die; +\& } +\& $pid; +\& } +\& +\& if (pipe_from_fork(\*(AqBAR\*(Aq)) { +\& # parent +\& while (<BAR>) { print; } +\& close BAR; +\& } +\& else { +\& # child +\& print "pipe_from_fork\en"; +\& exit(0); +\& } +.Ve +.Sp +Forking pipe \fBopen()\fR constructs will be supported in future. +.IP "Global state maintained by XSUBs" 8 +.IX Item "Global state maintained by XSUBs" +External subroutines (XSUBs) that maintain their own global state may +not work correctly. Such XSUBs will either need to maintain locks to +protect simultaneous access to global data from different pseudo-processes, +or maintain all their state on the Perl symbol table, which is copied +naturally when \fBfork()\fR is called. A callback mechanism that provides +extensions an opportunity to clone their state will be provided in the +near future. +.IP "Interpreter embedded in larger application" 8 +.IX Item "Interpreter embedded in larger application" +The \fBfork()\fR emulation may not behave as expected when it is executed in an +application which embeds a Perl interpreter and calls Perl APIs that can +evaluate bits of Perl code. This stems from the fact that the emulation +only has knowledge about the Perl interpreter's own data structures and +knows nothing about the containing application's state. For example, any +state carried on the application's own call stack is out of reach. +.IP "Thread-safety of extensions" 8 +.IX Item "Thread-safety of extensions" +Since the \fBfork()\fR emulation runs code in multiple threads, extensions +calling into non-thread-safe libraries may not work reliably when +calling \fBfork()\fR. As Perl's threading support gradually becomes more +widely adopted even on platforms with a native \fBfork()\fR, such extensions +are expected to be fixed for thread-safety. +.SH "PORTABILITY CAVEATS" +.IX Header "PORTABILITY CAVEATS" +In portable Perl code, \f(CW\*(C`kill(9, $child)\*(C'\fR must not be used on forked processes. +Killing a forked process is unsafe and has unpredictable results. +See "\fBkill()\fR", above. +.SH BUGS +.IX Header "BUGS" +.IP \(bu 8 +Having pseudo-process IDs be negative integers breaks down for the integer +\&\f(CW\-1\fR because the \fBwait()\fR and \fBwaitpid()\fR functions treat this number as +being special. The tacit assumption in the current implementation is that +the system never allocates a thread ID of \f(CW1\fR for user threads. A better +representation for pseudo-process IDs will be implemented in future. +.IP \(bu 8 +In certain cases, the OS-level handles created by the \fBpipe()\fR, \fBsocket()\fR, +and \fBaccept()\fR operators are apparently not duplicated accurately in +pseudo-processes. This only happens in some situations, but where it +does happen, it may result in deadlocks between the read and write ends +of pipe handles, or inability to send or receive data across socket +handles. +.IP \(bu 8 +This document may be incomplete in some respects. +.SH AUTHOR +.IX Header "AUTHOR" +Support for concurrent interpreters and the \fBfork()\fR emulation was implemented +by ActiveState, with funding from Microsoft Corporation. +.PP +This document is authored and maintained by Gurusamy Sarathy +<gsar@activestate.com>. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +"fork" in perlfunc, perlipc |