[ViewVC] Annotation of: cvs/Proc-FastSpawn/README

NAME
    Proc::FastSpawn - fork+exec, or spawn, a subprocess as quickly as
    possible

SYNOPSIS
       use Proc::FastSpawn;

       # simple use
       my $pid = spawn "/bin/echo", ["echo", "hello, world"];
       ...
       waitpid $pid, 0;

       # with environment
       my $pid = spawn "/bin/echo", ["echo", "hello, world"], ["PATH=/bin", "HOME=/tmp"];

       # inheriting file descriptors
       pipe R, W or die;
       fd_inherit fileno W;
       my $pid = spawn "/bin/sh", ["sh", "-c", "echo a pipe >&" . fileno W];
       close W;
       print <R>;

DESCRIPTION
    The purpose of this small (in scope and footprint) module is simple:
    spawn a subprocess asynchronously as efficiently and/or fast as
    possible. Basically the same as calling fork+exec (on POSIX), but
    hopefully faster than those two syscalls.

    Apart from fork overhead, this module also allows you to fork+exec
    programs when otherwise you couldn't - for example, when you use POSIX
    threads in your perl process then it generally isn't safe to call fork
    from perl, but it is safe to use this module to execute external
    processes.

    If neither of these are problems for you, you can safely ignore this
    module.

    So when is fork+exec not fast enough, how can you do it faster, and why
    would it matter?

    Forking a process requires making a complete copy of a process. Even
    thougth almost every implementation only copies page tables and not the
    memory istelf, this is still not free. For example, on my 3.6GHz amd64
    box, I can fork a 5GB process only twenty times a second. For a realtime
    process that must meet stricter deadlines, this is too slow. For a busy
    and big webserver, starting CGI scripts might mean unacceptable
    overhead.

    A workaround is to use "vfork" - this function isn't very portable, but
    it avoids the memory copy that "fork" has to do. Some systems have an
    optimised implementation of "spawn", and some systems have nothing.

    This module tries to abstract these differences away.

    As for what improvements to expect - on the 3.6GHz amd64 box that this
    module was originally developed on, a 3MB perl process (basically just
    perl + Proc::FastSpawn) takes 3.6s to run /bin/true 10000 times using
    fork+exec, and only 2.6s when using vfork+exec. In a 22MB process, the
    difference is already 5.0s vs 2.6s, and so on.

FUNCTIONS
    All the following functions are currently exported by default.

    $pid = spawn $path, \@argv[, \@envp]
        Creates a new process and tries to make it execute $path, with the
        given arguments and optionally the given environment variables,
        similar to calling fork + execv, or execve.

        Returns the PID of the new process if successful. On any error,
        "undef" is currently returned. Failure to execution might or might
        not be reported as "undef", or via a subprocess exit status of 127.

    fd_inherit $fileno[, $on]
        File descriptors can be inherited by the spawned proceses or not.
        This is decided on a per file descriptor basis. This module does
        nothing to any preexisting handles, but with this call, you can
        change the state of a single file descriptor to either be inherited
        ($on is true or missing) or not $on is false).

PORTABILITY NOTES
    On POSIX systems, this module currently calls vfork+exec, spawn, or
    fork+exec, depending on the platform. If your platform has a good vfork
    or spawn but is misdetected and falls back to slow fork+exec, drop me a
    note.

    On win32, the "_spawn" family of functions is used, and the module tries
    hard to patch the new process into perl's internal pid table, so the pid
    returned should work with other perl functions such as waitpid. Also,
    win32 doesn't have a meaningful way to quote arguments containing
    "special" characters, so this module tries it's best to quote those
    strings itself. Other typical platform limitations (such as being able
    to only have 64 or so subprocesses) are not worked around.

AUTHOR
     Marc Lehmann <schmorp@schmorp.de>
     http://home.schmorp.de/

Revision:	1.3
Committed:	Thu Apr 4 06:25:04 2013 UTC (11 years, 1 month ago) by root
Branch:	MAIN
CVS Tags:	rel-0_2
Changes since 1.2:	+18 -3 lines
Log Message:	0.2
#	User	Rev	Content
1	root	1.2	NAME
2			Proc::FastSpawn - fork+exec, or spawn, a subprocess as quickly as
3			possible
4
5			SYNOPSIS
6	root	1.3	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	root	1.2
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			thougth almost every implementation only copies page tables and not the
43			memory istelf, 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 realtime
45			process that must meet stricter deadlines, this is too slow. For a busy
46			and big webserver, starting CGI scripts might mean unacceptable
47			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			fd_inherit $fileno[, $on]
74			File descriptors can be inherited by the spawned proceses or not.
75			This is decided on a per file descriptor basis. This module does
76			nothing to any preexisting handles, but with this call, you can
77			change the state of a single file descriptor to either be inherited
78			($on is true or missing) or not $on is false).
79
80			PORTABILITY NOTES
81			On POSIX systems, this module currently calls vfork+exec, spawn, or
82			fork+exec, depending on the platform. If your platform has a good vfork
83	root	1.3	or spawn but is misdetected and falls back to slow fork+exec, drop me a
84	root	1.2	note.
85
86			On win32, the "_spawn" family of functions is used, and the module tries
87			hard to patch the new process into perl's internal pid table, so the pid
88			returned should work with other perl functions such as waitpid. Also,
89			win32 doesn't have a meaningful way to quote arguments containing
90			"special" characters, so this module tries it's best to quote those
91			strings itself. Other typical platform limitations (such as being able
92	root	1.3	to only have 64 or so subprocesses) are not worked around.
93	root	1.2
94			AUTHOR
95			Marc Lehmann <schmorp@schmorp.de>
96			http://home.schmorp.de/
97