perldelta: present tense for changes alreday in effect

[perl5.git] / pod / perlfork.pod

diff --git a/pod/perlfork.pod b/pod/perlfork.pod
index 82ac689..709d053 100644 (file)
--- a/pod/perlfork.pod
+++ b/pod/perlfork.pod
@@ -4,6 +4,11 @@ perlfork - Perl's fork() emulation
 
 =head1 SYNOPSIS
 
 
 =head1 SYNOPSIS
 

+    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.
+

 Perl provides a fork() keyword that corresponds to the Unix system call
 of the same name.  On most Unix-like platforms where the fork() system
 call is available, Perl's fork() simply calls it.
 Perl provides a fork() keyword that corresponds to the Unix system call
 of the same name.  On most Unix-like platforms where the fork() system
 call is available, Perl's fork() simply calls it.


@@ -32,7 +37,7 @@ thread that implements this child "process" as the pseudo-process.
 
 To the Perl program that called fork(), all this is designed to be
 transparent.  The parent returns from the fork() with a pseudo-process
 
 To the Perl program that called fork(), all this is designed to be
 transparent.  The parent returns from the fork() with a pseudo-process

-ID that can be subsequently used in any process manipulation functions;
+ID that can be subsequently used in any process-manipulation functions;

 the child returns from the fork() with a value of C<0> to signify that
 it is the child pseudo-process.
 
 the child returns from the fork() with a value of C<0> to signify that
 it is the child pseudo-process.
 


@@ -72,12 +77,24 @@ and return its status.
 
 =item kill()
 
 
 =item kill()
 

-kill() can be used to terminate a pseudo-process by passing it the ID returned
-by fork().  This 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.  Note that using kill() on a
-pseudo-process() may typically cause memory leaks, because the thread that
-implements the pseudo-process does not get a chance to clean up its resources.
+C<kill('KILL', ...)> can be used to terminate a pseudo-process by
+passing it the ID returned by fork().  This 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.  Note that using C<kill('KILL', ...)> on a
+pseudo-process() may typically cause memory leaks, because the thread
+that implements the pseudo-process does not get a chance to clean up
+its resources.
+
+C<kill('TERM', ...)> 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 C<kill('TERM', ...)> to avoid deadlock during process
+exit.  You will have to explicitly call waitpid() 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.

 
 =item exec()
 
 
 =item exec()
 


@@ -90,12 +107,15 @@ manipulation functions applied to the ID returned by fork() will affect the
 waiting pseudo-process that called exec(), not the real process it is
 waiting for after the exec().
 
 waiting pseudo-process that called exec(), not the real process it is
 waiting for after the exec().
 

+When exec() is called inside a pseudo-process then DESTROY methods and
+END blocks will still be called after the external process returns.
+

 =item exit()
 
 exit() always exits just the executing pseudo-process, after automatically
 wait()-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
 =item exit()
 
 exit() always exits just the executing pseudo-process, after automatically
 wait()-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.
+have exited.  See below for some limitations with open filehandles.

 
 =item Open handles to files, directories and network sockets
 
 
 =item Open handles to files, directories and network sockets
 


@@ -129,11 +149,12 @@ 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.
 
 pseudo-child created by it that is also a pseudo-parent will only exit
 after their pseudo-children have exited.
 

-A way to mark a pseudo-processes as running detached from their parent (so
-that the parent would not have to wait() for them if it doesn't want to)
-will be provided in future.
+Starting with Perl 5.14 a parent will not wait() automatically
+for any child that has been signalled with C<sig('TERM', ...)>
+to avoid a deadlock in case the child is blocking on I/O and
+never receives the signal.

 
 

-=head2 CAVEATS AND LIMITATIONS
+=head1 CAVEATS AND LIMITATIONS

 
 =over 8
 
 
 =over 8
 


@@ -172,6 +193,26 @@ 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.
 
 One can avoid this by opening files that need distinct seek pointers
 separately in the child.
 

+On some operating systems, notably Solaris and Unixware, calling C<exit()>
+from a child process will flush and close open filehandles in the parent,
+thereby corrupting the filehandles.  On these systems, calling C<_exit()>
+is suggested instead.  C<_exit()> is available in Perl through the 
+C<POSIX> module.  Please consult your system's manpages for more information
+on this.
+
+=item Open directory handles
+
+Perl will completely read from all open directory handles until they
+reach the end of the stream.  It will then seekdir() back to the
+original location and all future readdir() 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 fork() call.
+
+Note that rewinddir() has a similar limitation on Windows and will not
+force readdir() to read the directory again either.  Only a newly
+opened directory handle will reflect changes to the directory.
+

 =item Forking pipe open() not yet implemented
 
 The C<open(FOO, "|-")> and C<open(BAR, "-|")> constructs are not yet
 =item Forking pipe open() not yet implemented
 
 The C<open(FOO, "|-")> and C<open(BAR, "-|")> constructs are not yet


@@ -203,7 +244,6 @@ write to a forked child:
     else {
        # child
        while (<STDIN>) { print; }
     else {
        # child
        while (<STDIN>) { print; }

-       close STDIN;

        exit(0);
     }
 
        exit(0);
     }
 


@@ -233,7 +273,6 @@ And this one reads from the child:
     else {
        # child
        print "pipe_from_fork\n";
     else {
        # child
        print "pipe_from_fork\n";

-       close STDOUT;

        exit(0);
     }
 
        exit(0);
     }
 


@@ -282,6 +321,15 @@ representation for pseudo-process IDs will be implemented in future.
 
 =item *
 
 
 =item *
 

+In certain cases, the OS-level handles created by the pipe(), socket(),
+and accept() 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.
+
+=item *
+

 This document may be incomplete in some respects.
 
 =back
 This document may be incomplete in some respects.
 
 =back