This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Add information about portability caveats related to using kill on forked process.
[perl5.git] / pod / perlfork.pod
CommitLineData
7766f137
GS
1=head1 NAME
2
c3c83ace 3perlfork - Perl's fork() emulation
7766f137
GS
4
5=head1 SYNOPSIS
6
c3c83ace
GS
7 NOTE: As of the 5.8.0 release, fork() emulation has considerably
8 matured. However, there are still a few known bugs and differences
9 from real fork() that might affect you. See the "BUGS" and
10 "CAVEATS AND LIMITATIONS" sections below.
c7fa416b 11
7766f137
GS
12Perl provides a fork() keyword that corresponds to the Unix system call
13of the same name. On most Unix-like platforms where the fork() system
14call is available, Perl's fork() simply calls it.
15
16On some platforms such as Windows where the fork() system call is not
17available, Perl can be built to emulate fork() at the interpreter level.
18While the emulation is designed to be as compatible as possible with the
106325ad 19real fork() at the level of the Perl program, there are certain
7766f137
GS
20important differences that stem from the fact that all the pseudo child
21"processes" created this way live in the same real process as far as the
22operating system is concerned.
23
24This document provides a general overview of the capabilities and
25limitations of the fork() emulation. Note that the issues discussed here
26are not applicable to platforms where a real fork() is available and Perl
27has been configured to use it.
28
29=head1 DESCRIPTION
30
31The fork() emulation is implemented at the level of the Perl interpreter.
32What this means in general is that running fork() will actually clone the
33running interpreter and all its state, and run the cloned interpreter in
34a separate thread, beginning execution in the new thread just after the
35point where the fork() was called in the parent. We will refer to the
36thread that implements this child "process" as the pseudo-process.
37
38To the Perl program that called fork(), all this is designed to be
39transparent. The parent returns from the fork() with a pseudo-process
6eecded3 40ID that can be subsequently used in any process-manipulation functions;
7766f137
GS
41the child returns from the fork() with a value of C<0> to signify that
42it is the child pseudo-process.
43
44=head2 Behavior of other Perl features in forked pseudo-processes
45
46Most Perl features behave in a natural way within pseudo-processes.
47
48=over 8
49
50=item $$ or $PROCESS_ID
51
52This special variable is correctly set to the pseudo-process ID.
53It can be used to identify pseudo-processes within a particular
54session. Note that this value is subject to recycling if any
55pseudo-processes are launched after others have been wait()-ed on.
56
57=item %ENV
58
4375e838 59Each pseudo-process maintains its own virtual environment. Modifications
7766f137
GS
60to %ENV affect the virtual environment, and are only visible within that
61pseudo-process, and in any processes (or pseudo-processes) launched from
62it.
63
64=item chdir() and all other builtins that accept filenames
65
66Each pseudo-process maintains its own virtual idea of the current directory.
67Modifications to the current directory using chdir() are only visible within
68that pseudo-process, and in any processes (or pseudo-processes) launched from
69it. All file and directory accesses from the pseudo-process will correctly
70map the virtual working directory to the real working directory appropriately.
71
72=item wait() and waitpid()
73
74wait() and waitpid() can be passed a pseudo-process ID returned by fork().
75These calls will properly wait for the termination of the pseudo-process
76and return its status.
77
78=item kill()
79
3aa0ac5a 80C<kill('KILL', ...)> can be used to terminate a pseudo-process by
bd1171b0 81passing it the ID returned by fork(). The outcome of kill on a pseudo-process
82is unpredictable and it should not be used except
3aa0ac5a
JD
83under dire circumstances, because the operating system may not
84guarantee integrity of the process resources when a running thread is
bd1171b0 85terminated. The process which implements the pseudo-processes can be blocked
86and the Perl interpreter hangs. Note that using C<kill('KILL', ...)> on a
3aa0ac5a
JD
87pseudo-process() may typically cause memory leaks, because the thread
88that implements the pseudo-process does not get a chance to clean up
89its resources.
90
91C<kill('TERM', ...)> can also be used on pseudo-processes, but the
92signal will not be delivered while the pseudo-process is blocked by a
93system call, e.g. waiting for a socket to connect, or trying to read
94from a socket with no data available. Starting in Perl 5.14 the
95parent process will not wait for children to exit once they have been
96signalled with C<kill('TERM', ...)> to avoid deadlock during process
97exit. You will have to explicitly call waitpid() to make sure the
98child has time to clean-up itself, but you are then also responsible
99that the child is not blocking on I/O either.
7766f137
GS
100
101=item exec()
102
103Calling exec() within a pseudo-process actually spawns the requested
104executable in a separate process and waits for it to complete before
105exiting with the same exit status as that process. This means that the
106process ID reported within the running executable will be different from
107what the earlier Perl fork() might have returned. Similarly, any process
108manipulation functions applied to the ID returned by fork() will affect the
109waiting pseudo-process that called exec(), not the real process it is
110waiting for after the exec().
111
1cb5e8fb
JD
112When exec() is called inside a pseudo-process then DESTROY methods and
113END blocks will still be called after the external process returns.
114
7766f137
GS
115=item exit()
116
117exit() always exits just the executing pseudo-process, after automatically
118wait()-ing for any outstanding child pseudo-processes. Note that this means
119that the process as a whole will not exit unless all running pseudo-processes
1d335e36 120have exited. See below for some limitations with open filehandles.
7766f137
GS
121
122=item Open handles to files, directories and network sockets
123
124All open handles are dup()-ed in pseudo-processes, so that closing
125any handles in one process does not affect the others. See below for
126some limitations.
127
128=back
129
130=head2 Resource limits
131
132In the eyes of the operating system, pseudo-processes created via the fork()
133emulation are simply threads in the same process. This means that any
134process-level limits imposed by the operating system apply to all
135pseudo-processes taken together. This includes any limits imposed by the
136operating system on the number of open file, directory and socket handles,
137limits on disk space usage, limits on memory size, limits on CPU utilization
138etc.
139
140=head2 Killing the parent process
141
142If the parent process is killed (either using Perl's kill() builtin, or
143using some external means) all the pseudo-processes are killed as well,
144and the whole process exits.
145
146=head2 Lifetime of the parent process and pseudo-processes
147
148During the normal course of events, the parent process and every
149pseudo-process started by it will wait for their respective pseudo-children
150to complete before they exit. This means that the parent and every
151pseudo-child created by it that is also a pseudo-parent will only exit
152after their pseudo-children have exited.
153
3aa0ac5a
JD
154Starting with Perl 5.14 a parent will not wait() automatically
155for any child that has been signalled with C<sig('TERM', ...)>
156to avoid a deadlock in case the child is blocking on I/O and
157never receives the signal.
7766f137 158
6eecded3 159=head1 CAVEATS AND LIMITATIONS
7766f137
GS
160
161=over 8
162
163=item BEGIN blocks
164
165The fork() emulation will not work entirely correctly when called from
166within a BEGIN block. The forked copy will run the contents of the
167BEGIN block, but will not continue parsing the source stream after the
168BEGIN block. For example, consider the following code:
169
170 BEGIN {
171 fork and exit; # fork child and exit the parent
172 print "inner\n";
173 }
174 print "outer\n";
175
176This will print:
177
178 inner
179
180rather than the expected:
181
182 inner
183 outer
184
185This limitation arises from fundamental technical difficulties in
186cloning and restarting the stacks used by the Perl parser in the
187middle of a parse.
188
189=item Open filehandles
190
191Any filehandles open at the time of the fork() will be dup()-ed. Thus,
192the files can be closed independently in the parent and child, but beware
193that the dup()-ed handles will still share the same seek pointer. Changing
194the seek position in the parent will change it in the child and vice-versa.
195One can avoid this by opening files that need distinct seek pointers
196separately in the child.
197
1d335e36
SP
198On some operating systems, notably Solaris and Unixware, calling C<exit()>
199from a child process will flush and close open filehandles in the parent,
200thereby corrupting the filehandles. On these systems, calling C<_exit()>
201is suggested instead. C<_exit()> is available in Perl through the
96d4712d 202C<POSIX> module. Please consult your system's manpages for more information
1d335e36
SP
203on this.
204
3ba4b5c1
JD
205=item Open directory handles
206
207Perl will completely read from all open directory handles until they
208reach the end of the stream. It will then seekdir() back to the
209original location and all future readdir() requests will be fulfilled
6eecded3 210from the cache buffer. That means that neither the directory handle held
3ba4b5c1
JD
211by the parent process nor the one held by the child process will see
212any changes made to the directory after the fork() call.
213
214Note that rewinddir() has a similar limitation on Windows and will not
215force readdir() to read the directory again either. Only a newly
216opened directory handle will reflect changes to the directory.
217
030866aa
GS
218=item Forking pipe open() not yet implemented
219
220The C<open(FOO, "|-")> and C<open(BAR, "-|")> constructs are not yet
221implemented. This limitation can be easily worked around in new code
222by creating a pipe explicitly. The following example shows how to
223write to a forked child:
224
225 # simulate open(FOO, "|-")
226 sub pipe_to_fork ($) {
227 my $parent = shift;
228 pipe my $child, $parent or die;
229 my $pid = fork();
230 die "fork() failed: $!" unless defined $pid;
231 if ($pid) {
232 close $child;
233 }
234 else {
235 close $parent;
236 open(STDIN, "<&=" . fileno($child)) or die;
237 }
238 $pid;
239 }
240
241 if (pipe_to_fork('FOO')) {
242 # parent
243 print FOO "pipe_to_fork\n";
244 close FOO;
245 }
246 else {
247 # child
248 while (<STDIN>) { print; }
030866aa
GS
249 exit(0);
250 }
251
252And this one reads from the child:
253
254 # simulate open(FOO, "-|")
255 sub pipe_from_fork ($) {
256 my $parent = shift;
257 pipe $parent, my $child or die;
258 my $pid = fork();
259 die "fork() failed: $!" unless defined $pid;
260 if ($pid) {
261 close $child;
262 }
263 else {
264 close $parent;
265 open(STDOUT, ">&=" . fileno($child)) or die;
266 }
267 $pid;
268 }
269
270 if (pipe_from_fork('BAR')) {
271 # parent
272 while (<BAR>) { print; }
273 close BAR;
274 }
275 else {
276 # child
277 print "pipe_from_fork\n";
030866aa
GS
278 exit(0);
279 }
280
281Forking pipe open() constructs will be supported in future.
282
7766f137
GS
283=item Global state maintained by XSUBs
284
285External subroutines (XSUBs) that maintain their own global state may
286not work correctly. Such XSUBs will either need to maintain locks to
287protect simultaneous access to global data from different pseudo-processes,
288or maintain all their state on the Perl symbol table, which is copied
289naturally when fork() is called. A callback mechanism that provides
290extensions an opportunity to clone their state will be provided in the
291near future.
292
293=item Interpreter embedded in larger application
294
295The fork() emulation may not behave as expected when it is executed in an
296application which embeds a Perl interpreter and calls Perl APIs that can
297evaluate bits of Perl code. This stems from the fact that the emulation
298only has knowledge about the Perl interpreter's own data structures and
299knows nothing about the containing application's state. For example, any
300state carried on the application's own call stack is out of reach.
301
7e396c59
GS
302=item Thread-safety of extensions
303
304Since the fork() emulation runs code in multiple threads, extensions
305calling into non-thread-safe libraries may not work reliably when
306calling fork(). As Perl's threading support gradually becomes more
307widely adopted even on platforms with a native fork(), such extensions
308are expected to be fixed for thread-safety.
309
7766f137
GS
310=back
311
bd1171b0 312=head1 PORTABILITY CAVEATS
313
314In portable Perl code, C<kill(9, $child)> must not be used on forked processes.
315Killing a forked process is unsafe and have unpredictable results.
316See L</kill()>, above.
317
7766f137
GS
318=head1 BUGS
319
320=over 8
321
322=item *
323
324Having pseudo-process IDs be negative integers breaks down for the integer
325C<-1> because the wait() and waitpid() functions treat this number as
326being special. The tacit assumption in the current implementation is that
327the system never allocates a thread ID of C<1> for user threads. A better
328representation for pseudo-process IDs will be implemented in future.
329
330=item *
331
c3c83ace
GS
332In certain cases, the OS-level handles created by the pipe(), socket(),
333and accept() operators are apparently not duplicated accurately in
334pseudo-processes. This only happens in some situations, but where it
335does happen, it may result in deadlocks between the read and write ends
336of pipe handles, or inability to send or receive data across socket
337handles.
338
339=item *
340
7766f137
GS
341This document may be incomplete in some respects.
342
a45bd81d
GS
343=back
344
7766f137
GS
345=head1 AUTHOR
346
7e396c59
GS
347Support for concurrent interpreters and the fork() emulation was implemented
348by ActiveState, with funding from Microsoft Corporation.
7766f137
GS
349
350This document is authored and maintained by Gurusamy Sarathy
351E<lt>gsar@activestate.comE<gt>.
352
353=head1 SEE ALSO
354
355L<perlfunc/"fork">, L<perlipc>
356
357=cut