ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/Proc-FastSpawn/README
Revision: 1.5
Committed: Sun Apr 28 00:49:43 2013 UTC (11 years, 2 months ago) by root
Branch: MAIN
CVS Tags: rel-1_1, rel-1_2, HEAD
Changes since 1.4: +4 -0 lines
Log Message:
1.1

File Contents

# Content
1 NAME
2 Proc::FastSpawn - fork+exec, or spawn, a subprocess as quickly as
3 possible
4
5 SYNOPSIS
6 use Proc::FastSpawn;
7
8 # simple use
9 my $pid = spawn "/bin/echo", ["echo", "hello, world"];
10 ...
11 waitpid $pid, 0;
12
13 # with environment
14 my $pid = spawn "/bin/echo", ["echo", "hello, world"], ["PATH=/bin", "HOME=/tmp"];
15
16 # inheriting file descriptors
17 pipe R, W or die;
18 fd_inherit fileno W;
19 my $pid = spawn "/bin/sh", ["sh", "-c", "echo a pipe >&" . fileno W];
20 close W;
21 print <R>;
22
23 DESCRIPTION
24 The purpose of this small (in scope and footprint) module is simple:
25 spawn a subprocess asynchronously as efficiently and/or fast as
26 possible. Basically the same as calling fork+exec (on POSIX), but
27 hopefully faster than those two syscalls.
28
29 Apart from fork overhead, this module also allows you to fork+exec
30 programs when otherwise you couldn't - for example, when you use POSIX
31 threads in your perl process then it generally isn't safe to call fork
32 from perl, but it is safe to use this module to execute external
33 processes.
34
35 If neither of these are problems for you, you can safely ignore this
36 module.
37
38 So when is fork+exec not fast enough, how can you do it faster, and why
39 would it matter?
40
41 Forking a process requires making a complete copy of a process. Even
42 thought almost every implementation only copies page tables and not the
43 memory itself, this is still not free. For example, on my 3.6GHz amd64
44 box, I can fork a 5GB process only twenty times a second. For a
45 real-time process that must meet stricter deadlines, this is too slow.
46 For a busy and big web server, starting CGI scripts might mean
47 unacceptable overhead.
48
49 A workaround is to use "vfork" - this function isn't very portable, but
50 it avoids the memory copy that "fork" has to do. Some systems have an
51 optimised implementation of "spawn", and some systems have nothing.
52
53 This module tries to abstract these differences away.
54
55 As for what improvements to expect - on the 3.6GHz amd64 box that this
56 module was originally developed on, a 3MB perl process (basically just
57 perl + Proc::FastSpawn) takes 3.6s to run /bin/true 10000 times using
58 fork+exec, and only 2.6s when using vfork+exec. In a 22MB process, the
59 difference is already 5.0s vs 2.6s, and so on.
60
61 FUNCTIONS
62 All the following functions are currently exported by default.
63
64 $pid = spawn $path, \@argv[, \@envp]
65 Creates a new process and tries to make it execute $path, with the
66 given arguments and optionally the given environment variables,
67 similar to calling fork + execv, or execve.
68
69 Returns the PID of the new process if successful. On any error,
70 "undef" is currently returned. Failure to execution might or might
71 not be reported as "undef", or via a subprocess exit status of 127.
72
73 $pid = spawnp $file, \@argv[, \@envp]
74 Like "spawn", but searches $file in $ENV{PATH} like the shell would
75 do.
76
77 fd_inherit $fileno[, $on]
78 File descriptors can be inherited by the spawned processes or not.
79 This is decided on a per file descriptor basis. This module does
80 nothing to any preexisting handles, but with this call, you can
81 change the state of a single file descriptor to either be inherited
82 ($on is true or missing) or not $on is false).
83
84 Free portability pro-tip: it seems native win32 perls ignore $^F and
85 set all file handles to be inherited by default - but this function
86 can switch it off.
87
88 PORTABILITY NOTES
89 On POSIX systems, this module currently calls vfork+exec, spawn, or
90 fork+exec, depending on the platform. If your platform has a good vfork
91 or spawn but is misdetected and falls back to slow fork+exec, drop me a
92 note.
93
94 On win32, the "_spawn" family of functions is used, and the module tries
95 hard to patch the new process into perl's internal pid table, so the pid
96 returned should work with other Perl functions such as waitpid. Also,
97 win32 doesn't have a meaningful way to quote arguments containing
98 "special" characters, so this module tries it's best to quote those
99 strings itself. Other typical platform limitations (such as being able
100 to only have 64 or so subprocesses) are not worked around.
101
102 AUTHOR
103 Marc Lehmann <schmorp@schmorp.de>
104 http://home.schmorp.de/
105