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