ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/AnyEvent-Fork/Fork.pm
(Generate patch)

Comparing AnyEvent-Fork/Fork.pm (file contents):
Revision 1.4 by root, Wed Apr 3 07:35:57 2013 UTC vs.
Revision 1.42 by root, Mon Apr 8 05:44:23 2013 UTC

3AnyEvent::Fork - everything you wanted to use fork() for, but couldn't 3AnyEvent::Fork - everything you wanted to use fork() for, but couldn't
4 4
5=head1 SYNOPSIS 5=head1 SYNOPSIS
6 6
7 use AnyEvent::Fork; 7 use AnyEvent::Fork;
8
9 AnyEvent::Fork
10 ->new
11 ->require ("MyModule")
12 ->run ("MyModule::server", my $cv = AE::cv);
13
14 my $fh = $cv->recv;
8 15
9=head1 DESCRIPTION 16=head1 DESCRIPTION
10 17
11This module allows you to create new processes, without actually forking 18This module allows you to create new processes, without actually forking
12them from your current process (avoiding the problems of forking), but 19them from your current process (avoiding the problems of forking), but
13preserving most of the advantages of fork. 20preserving most of the advantages of fork.
14 21
15It can be used to create new worker processes or new independent 22It can be used to create new worker processes or new independent
16subprocesses for short- and long-running jobs, process pools (e.g. for use 23subprocesses for short- and long-running jobs, process pools (e.g. for use
17in pre-forked servers) but also to spawn new external processes (such as 24in pre-forked servers) but also to spawn new external processes (such as
18CGI scripts from a webserver), which can be faster (and more well behaved) 25CGI scripts from a web server), which can be faster (and more well behaved)
19than using fork+exec in big processes. 26than using fork+exec in big processes.
20 27
28Special care has been taken to make this module useful from other modules,
29while still supporting specialised environments such as L<App::Staticperl>
30or L<PAR::Packer>.
31
32=head2 WHAT THIS MODULE IS NOT
33
34This module only creates processes and lets you pass file handles and
35strings to it, and run perl code. It does not implement any kind of RPC -
36there is no back channel from the process back to you, and there is no RPC
37or message passing going on.
38
39If you need some form of RPC, you can either implement it yourself
40in whatever way you like, use some message-passing module such
41as L<AnyEvent::MP>, some pipe such as L<AnyEvent::ZeroMQ>, use
42L<AnyEvent::Handle> on both sides to send e.g. JSON or Storable messages,
43and so on.
44
45=head2 COMPARISON TO OTHER MODULES
46
47There is an abundance of modules on CPAN that do "something fork", such as
48L<Parallel::ForkManager>, L<AnyEvent::ForkManager>, L<AnyEvent::Worker>
49or L<AnyEvent::Subprocess>. There are modules that implement their own
50process management, such as L<AnyEvent::DBI>.
51
52The problems that all these modules try to solve are real, however, none
53of them (from what I have seen) tackle the very real problems of unwanted
54memory sharing, efficiency, not being able to use event processing or
55similar modules in the processes they create.
56
57This module doesn't try to replace any of them - instead it tries to solve
58the problem of creating processes with a minimum of fuss and overhead (and
59also luxury). Ideally, most of these would use AnyEvent::Fork internally,
60except they were written before AnyEvent:Fork was available, so obviously
61had to roll their own.
62
21=head1 PROBLEM STATEMENT 63=head2 PROBLEM STATEMENT
22 64
23There are two ways to implement parallel processing on UNIX like operating 65There are two traditional ways to implement parallel processing on UNIX
24systems - fork and process, and fork+exec and process. They have different 66like operating systems - fork and process, and fork+exec and process. They
25advantages and disadvantages that I describe below, together with how this 67have different advantages and disadvantages that I describe below,
26module tries to mitigate the disadvantages. 68together with how this module tries to mitigate the disadvantages.
27 69
28=over 4 70=over 4
29 71
30=item Forking from a big process can be very slow (a 5GB process needs 72=item Forking from a big process can be very slow.
310.05s to fork on my 3.6GHz amd64 GNU/Linux box for example). This overhead 73
74A 5GB process needs 0.05s to fork on my 3.6GHz amd64 GNU/Linux box. This
32is often shared with exec (because you have to fork first), but in some 75overhead is often shared with exec (because you have to fork first), but
33circumstances (e.g. when vfork is used), fork+exec can be much faster. 76in some circumstances (e.g. when vfork is used), fork+exec can be much
77faster.
34 78
35This module can help here by telling a small(er) helper process to fork, 79This module can help here by telling a small(er) helper process to fork,
36or fork+exec instead. 80which is faster then forking the main process, and also uses vfork where
81possible. This gives the speed of vfork, with the flexibility of fork.
37 82
38=item Forking usually creates a copy-on-write copy of the parent 83=item Forking usually creates a copy-on-write copy of the parent
39process. Memory (for example, modules or data files that have been 84process.
40will not take additional memory). When exec'ing a new process, modules 85
41and data files might need to be loaded again, at extra cpu and memory 86For example, modules or data files that are loaded will not use additional
42cost. Likewise when forking, all data structures are copied as well - if 87memory after a fork. When exec'ing a new process, modules and data files
88might need to be loaded again, at extra CPU and memory cost. But when
89forking, literally all data structures are copied - if the program frees
43the program frees them and replaces them by new data, the child processes 90them and replaces them by new data, the child processes will retain the
44will retain the memory even if it isn't used. 91old version even if it isn't used, which can suddenly and unexpectedly
92increase memory usage when freeing memory.
93
94The trade-off is between more sharing with fork (which can be good or
95bad), and no sharing with exec.
45 96
46This module allows the main program to do a controlled fork, and allows 97This module allows the main program to do a controlled fork, and allows
47modules to exec processes safely at any time. When creating a custom 98modules to exec processes safely at any time. When creating a custom
48process pool you can take advantage of data sharing via fork without 99process pool you can take advantage of data sharing via fork without
49risking to share large dynamic data structures that will blow up child 100risking to share large dynamic data structures that will blow up child
50memory usage. 101memory usage.
51 102
103In other words, this module puts you into control over what is being
104shared and what isn't, at all times.
105
52=item Exec'ing a new perl process might be difficult and slow. For 106=item Exec'ing a new perl process might be difficult.
107
53example, it is not easy to find the correct path to the perl interpreter, 108For example, it is not easy to find the correct path to the perl
54and all modules have to be loaded from disk again. Long running processes 109interpreter - C<$^X> might not be a perl interpreter at all.
55might run into problems when perl is upgraded for example.
56 110
57This module supports creating pre-initialised perl processes to be used
58as template, and also tries hard to identify the correct path to the perl 111This module tries hard to identify the correct path to the perl
59interpreter. With a cooperative main program, exec'ing the interpreter 112interpreter. With a cooperative main program, exec'ing the interpreter
60might not even be necessary. 113might not even be necessary, but even without help from the main program,
114it will still work when used from a module.
61 115
116=item Exec'ing a new perl process might be slow, as all necessary modules
117have to be loaded from disk again, with no guarantees of success.
118
119Long running processes might run into problems when perl is upgraded
120and modules are no longer loadable because they refer to a different
121perl version, or parts of a distribution are newer than the ones already
122loaded.
123
124This module supports creating pre-initialised perl processes to be used as
125a template for new processes.
126
62=item Forking might be impossible when a program is running. For example, 127=item Forking might be impossible when a program is running.
63POSIX makes it almost impossible to fork from a multithreaded program and
64do anything useful in the child - strictly speaking, if your perl program
65uses posix threads (even indirectly via e.g. L<IO::AIO> or L<threads>),
66you cannot call fork on the perl level anymore, at all.
67 128
129For example, POSIX makes it almost impossible to fork from a
130multi-threaded program while doing anything useful in the child - in
131fact, if your perl program uses POSIX threads (even indirectly via
132e.g. L<IO::AIO> or L<threads>), you cannot call fork on the perl level
133anymore without risking corruption issues on a number of operating
134systems.
135
68This module can safely fork helper processes at any time, by caling 136This module can safely fork helper processes at any time, by calling
69fork+exec in C, in a POSIX-compatible way. 137fork+exec in C, in a POSIX-compatible way (via L<Proc::FastSpawn>).
70 138
71=item Parallel processing with fork might be inconvenient or difficult 139=item Parallel processing with fork might be inconvenient or difficult
140to implement. Modules might not work in both parent and child.
141
72to implement. For example, when a program uses an event loop and creates 142For example, when a program uses an event loop and creates watchers it
73watchers it becomes very hard to use the event loop from a child 143becomes very hard to use the event loop from a child program, as the
74program, as the watchers already exist but are only meaningful in the 144watchers already exist but are only meaningful in the parent. Worse, a
75parent. Worse, a module might want to use such a system, not knowing 145module might want to use such a module, not knowing whether another module
76whether another module or the main program also does, leading to problems. 146or the main program also does, leading to problems.
77 147
78This module only lets the main program create pools by forking (because 148Apart from event loops, graphical toolkits also commonly fall into the
79only the main program can know when it is still safe to do so) - all other 149"unsafe module" category, or just about anything that communicates with
80pools are created by fork+exec, after which such modules can again be 150the external world, such as network libraries and file I/O modules, which
81loaded. 151usually don't like being copied and then allowed to continue in two
152processes.
153
154With this module only the main program is allowed to create new processes
155by forking (because only the main program can know when it is still safe
156to do so) - all other processes are created via fork+exec, which makes it
157possible to use modules such as event loops or window interfaces safely.
82 158
83=back 159=back
160
161=head1 EXAMPLES
162
163=head2 Create a single new process, tell it to run your worker function.
164
165 AnyEvent::Fork
166 ->new
167 ->require ("MyModule")
168 ->run ("MyModule::worker, sub {
169 my ($master_filehandle) = @_;
170
171 # now $master_filehandle is connected to the
172 # $slave_filehandle in the new process.
173 });
174
175C<MyModule> might look like this:
176
177 package MyModule;
178
179 sub worker {
180 my ($slave_filehandle) = @_;
181
182 # now $slave_filehandle is connected to the $master_filehandle
183 # in the original prorcess. have fun!
184 }
185
186=head2 Create a pool of server processes all accepting on the same socket.
187
188 # create listener socket
189 my $listener = ...;
190
191 # create a pool template, initialise it and give it the socket
192 my $pool = AnyEvent::Fork
193 ->new
194 ->require ("Some::Stuff", "My::Server")
195 ->send_fh ($listener);
196
197 # now create 10 identical workers
198 for my $id (1..10) {
199 $pool
200 ->fork
201 ->send_arg ($id)
202 ->run ("My::Server::run");
203 }
204
205 # now do other things - maybe use the filehandle provided by run
206 # to wait for the processes to die. or whatever.
207
208C<My::Server> might look like this:
209
210 package My::Server;
211
212 sub run {
213 my ($slave, $listener, $id) = @_;
214
215 close $slave; # we do not use the socket, so close it to save resources
216
217 # we could go ballistic and use e.g. AnyEvent here, or IO::AIO,
218 # or anything we usually couldn't do in a process forked normally.
219 while (my $socket = $listener->accept) {
220 # do sth. with new socket
221 }
222 }
223
224=head2 use AnyEvent::Fork as a faster fork+exec
225
226This runs C</bin/echo hi>, with stdandard output redirected to /tmp/log
227and standard error redirected to the communications socket. It is usually
228faster than fork+exec, but still lets you prepare the environment.
229
230 open my $output, ">/tmp/log" or die "$!";
231
232 AnyEvent::Fork
233 ->new
234 ->eval ('
235 # compile a helper function for later use
236 sub run {
237 my ($fh, $output, @cmd) = @_;
238
239 # perl will clear close-on-exec on STDOUT/STDERR
240 open STDOUT, ">&", $output or die;
241 open STDERR, ">&", $fh or die;
242
243 exec @cmd;
244 }
245 ')
246 ->send_fh ($output)
247 ->send_arg ("/bin/echo", "hi")
248 ->run ("run", my $cv = AE::cv);
249
250 my $stderr = $cv->recv;
84 251
85=head1 CONCEPTS 252=head1 CONCEPTS
86 253
87This module can create new processes either by executing a new perl 254This module can create new processes either by executing a new perl
88process, or by forking from an existing "template" process. 255process, or by forking from an existing "template" process.
105needed the first time. Forking from this process shares the memory used 272needed the first time. Forking from this process shares the memory used
106for the perl interpreter with the new process, but loading modules takes 273for the perl interpreter with the new process, but loading modules takes
107time, and the memory is not shared with anything else. 274time, and the memory is not shared with anything else.
108 275
109This is ideal for when you only need one extra process of a kind, with the 276This is ideal for when you only need one extra process of a kind, with the
110option of starting and stipping it on demand. 277option of starting and stopping it on demand.
278
279Example:
280
281 AnyEvent::Fork
282 ->new
283 ->require ("Some::Module")
284 ->run ("Some::Module::run", sub {
285 my ($fork_fh) = @_;
286 });
111 287
112=item fork a new template process, load code, then fork processes off of 288=item fork a new template process, load code, then fork processes off of
113it and run the code 289it and run the code
114 290
115When you need to have a bunch of processes that all execute the same (or 291When you need to have a bunch of processes that all execute the same (or
121modules you loaded) is shared between the processes, and each new process 297modules you loaded) is shared between the processes, and each new process
122consumes relatively little memory of its own. 298consumes relatively little memory of its own.
123 299
124The disadvantage of this approach is that you need to create a template 300The disadvantage of this approach is that you need to create a template
125process for the sole purpose of forking new processes from it, but if you 301process for the sole purpose of forking new processes from it, but if you
126only need a fixed number of proceses you can create them, and then destroy 302only need a fixed number of processes you can create them, and then destroy
127the template process. 303the template process.
304
305Example:
306
307 my $template = AnyEvent::Fork->new->require ("Some::Module");
308
309 for (1..10) {
310 $template->fork->run ("Some::Module::run", sub {
311 my ($fork_fh) = @_;
312 });
313 }
314
315 # at this point, you can keep $template around to fork new processes
316 # later, or you can destroy it, which causes it to vanish.
128 317
129=item execute a new perl interpreter, load some code, run it 318=item execute a new perl interpreter, load some code, run it
130 319
131This is relatively slow, and doesn't allow you to share memory between 320This is relatively slow, and doesn't allow you to share memory between
132multiple processes. 321multiple processes.
134The only advantage is that you don't have to have a template process 323The only advantage is that you don't have to have a template process
135hanging around all the time to fork off some new processes, which might be 324hanging around all the time to fork off some new processes, which might be
136an advantage when there are long time spans where no extra processes are 325an advantage when there are long time spans where no extra processes are
137needed. 326needed.
138 327
328Example:
329
330 AnyEvent::Fork
331 ->new_exec
332 ->require ("Some::Module")
333 ->run ("Some::Module::run", sub {
334 my ($fork_fh) = @_;
335 });
336
139=back 337=back
140 338
141=head1 FUNCTIONS 339=head1 THE C<AnyEvent::Fork> CLASS
340
341This module exports nothing, and only implements a single class -
342C<AnyEvent::Fork>.
343
344There are two class constructors that both create new processes - C<new>
345and C<new_exec>. The C<fork> method creates a new process by forking an
346existing one and could be considered a third constructor.
347
348Most of the remaining methods deal with preparing the new process, by
349loading code, evaluating code and sending data to the new process. They
350usually return the process object, so you can chain method calls.
351
352If a process object is destroyed before calling its C<run> method, then
353the process simply exits. After C<run> is called, all responsibility is
354passed to the specified function.
355
356As long as there is any outstanding work to be done, process objects
357resist being destroyed, so there is no reason to store them unless you
358need them later - configure and forget works just fine.
142 359
143=over 4 360=over 4
144 361
145=cut 362=cut
146 363
147package AnyEvent::Fork; 364package AnyEvent::Fork;
148 365
149use common::sense; 366use common::sense;
150 367
151use Socket (); 368use Errno ();
152 369
153use AnyEvent; 370use AnyEvent;
154use AnyEvent::Fork::Util;
155use AnyEvent::Util (); 371use AnyEvent::Util ();
156 372
157our $PERL; # the path to the perl interpreter, deduces with various forms of magic 373use IO::FDPass;
158 374
159=item my $pool = new AnyEvent::Fork key => value... 375our $VERSION = 0.6;
160
161Create a new process pool. The following named parameters are supported:
162 376
163=over 4 377=over 4
164 378
165=back 379=back
166 380
167=cut 381=cut
382
383# the early fork template process
384our $EARLY;
168 385
169# the empty template process 386# the empty template process
170our $TEMPLATE; 387our $TEMPLATE;
171 388
389sub QUEUE() { 0 }
390sub FH() { 1 }
391sub WW() { 2 }
392sub PID() { 3 }
393sub CB() { 4 }
394
395sub _new {
396 my ($self, $fh, $pid) = @_;
397
398 AnyEvent::Util::fh_nonblocking $fh, 1;
399
400 $self = bless [
401 [], # write queue - strings or fd's
402 $fh,
403 undef, # AE watcher
404 $pid,
405 ], $self;
406
407 $self
408}
409
172sub _cmd { 410sub _cmd {
173 my $self = shift; 411 my $self = shift;
174 412
175 # ideally, we would want to use "a (w/a)*" as format string, but perl versions 413 # ideally, we would want to use "a (w/a)*" as format string, but perl
176 # form at least 5.8.9 to 5.16.3 are all buggy and can't unpack it. 414 # versions from at least 5.8.9 to 5.16.3 are all buggy and can't unpack
177 push @{ $self->[2] }, pack "N/a", pack "(w/a)*", @_; 415 # it.
416 push @{ $self->[QUEUE] }, pack "a L/a*", $_[0], $_[1];
178 417
179 $self->[3] ||= AE::io $self->[1], 1, sub { 418 $self->[WW] ||= AE::io $self->[FH], 1, sub {
419 do {
420 # send the next "thing" in the queue - either a reference to an fh,
421 # or a plain string.
422
180 if (ref $self->[2][0]) { 423 if (ref $self->[QUEUE][0]) {
181 AnyEvent::Fork::Util::fd_send fileno $self->[1], fileno ${ $self->[2][0] } 424 # send fh
425 unless (IO::FDPass::send fileno $self->[FH], fileno ${ $self->[QUEUE][0] }) {
426 return if $! == Errno::EAGAIN || $! == Errno::EWOULDBLOCK;
427 undef $self->[WW];
428 die "AnyEvent::Fork: file descriptor send failure: $!";
429 }
430
182 and shift @{ $self->[2] }; 431 shift @{ $self->[QUEUE] };
432
183 } else { 433 } else {
434 # send string
184 my $len = syswrite $self->[1], $self->[2][0] 435 my $len = syswrite $self->[FH], $self->[QUEUE][0];
436
437 unless ($len) {
438 return if $! == Errno::EAGAIN || $! == Errno::EWOULDBLOCK;
439 undef $self->[3];
185 or do { undef $self->[3]; die "AnyEvent::Fork: command write failure: $!" }; 440 die "AnyEvent::Fork: command write failure: $!";
441 }
442
186 substr $self->[2][0], 0, $len, ""; 443 substr $self->[QUEUE][0], 0, $len, "";
187 shift @{ $self->[2] } unless length $self->[2][0]; 444 shift @{ $self->[QUEUE] } unless length $self->[QUEUE][0];
188 } 445 }
446 } while @{ $self->[QUEUE] };
189 447
190 unless (@{ $self->[2] }) { 448 # everything written
191 undef $self->[3]; 449 undef $self->[WW];
450
451 # invoke run callback, if any
192 $self->[0]->($self->[1]) if $self->[0]; 452 $self->[CB]->($self->[FH]) if $self->[CB];
193 }
194 }; 453 };
195}
196 454
455 () # make sure we don't leak the watcher
456}
457
458# fork template from current process, used by AnyEvent::Fork::Early/Template
197sub _new { 459sub _new_fork {
198 my ($self, $fh) = @_;
199
200 $self = bless [
201 undef, # run callback
202 $fh,
203 [], # write queue - strings or fd's
204 undef, # AE watcher
205 ], $self;
206
207# my ($a, $b) = AnyEvent::Util::portable_socketpair; 460 my ($fh, $slave) = AnyEvent::Util::portable_socketpair;
461 my $parent = $$;
208 462
209# queue_cmd $template, "Iabc"; 463 my $pid = fork;
210# push @{ $template->[2] }, \$b;
211 464
212# use Coro::AnyEvent; Coro::AnyEvent::sleep 1; 465 if ($pid eq 0) {
213# undef $b; 466 require AnyEvent::Fork::Serve;
214# die "x" . <$a>; 467 $AnyEvent::Fork::Serve::OWNER = $parent;
468 close $fh;
469 $0 = "$_[1] of $parent";
470 AnyEvent::Fork::Serve::serve ($slave);
471 exit 0;
472 } elsif (!$pid) {
473 die "AnyEvent::Fork::Early/Template: unable to fork template process: $!";
474 }
215 475
216 $self 476 AnyEvent::Fork->_new ($fh, $pid)
217} 477}
218 478
219=item my $proc = new AnyEvent::Fork 479=item my $proc = new AnyEvent::Fork
220 480
221Create a new "empty" perl interpreter process and returns its process 481Create a new "empty" perl interpreter process and returns its process
222object for further manipulation. 482object for further manipulation.
223 483
224The new process is forked from a template process that is kept around 484The new process is forked from a template process that is kept around
225for this purpose. When it doesn't exist yet, it is created by a call to 485for this purpose. When it doesn't exist yet, it is created by a call to
226C<new_exec> and kept around for future calls. 486C<new_exec> first and then stays around for future calls.
227 487
228=cut 488=cut
229 489
230sub new { 490sub new {
231 my $class = shift; 491 my $class = shift;
252 my ($fh, $slave) = AnyEvent::Util::portable_socketpair; 512 my ($fh, $slave) = AnyEvent::Util::portable_socketpair;
253 513
254 $self->send_fh ($slave); 514 $self->send_fh ($slave);
255 $self->_cmd ("f"); 515 $self->_cmd ("f");
256 516
257 AnyEvent::Util::fh_nonblocking $fh, 1;
258
259 AnyEvent::Fork->_new ($fh) 517 AnyEvent::Fork->_new ($fh)
260} 518}
261 519
262=item my $proc = new_exec AnyEvent::Fork 520=item my $proc = new_exec AnyEvent::Fork
263 521
269reduces the amount of memory sharing that is possible, and is also slower. 527reduces the amount of memory sharing that is possible, and is also slower.
270 528
271You should use C<new> whenever possible, except when having a template 529You should use C<new> whenever possible, except when having a template
272process around is unacceptable. 530process around is unacceptable.
273 531
274The path to the perl interpreter is divined usign various methods - first 532The path to the perl interpreter is divined using various methods - first
275C<$^X> is investigated to see if the path ends with something that sounds 533C<$^X> is investigated to see if the path ends with something that sounds
276as if it were the perl interpreter. Failing this, the module falls back to 534as if it were the perl interpreter. Failing this, the module falls back to
277using C<$Config::Config{perlpath}>. 535using C<$Config::Config{perlpath}>.
278 536
279=cut 537=cut
280 538
281sub new_exec { 539sub new_exec {
282 my ($self) = @_; 540 my ($self) = @_;
283 541
542 return $EARLY->fork
543 if $EARLY;
544
284 # first find path of perl 545 # first find path of perl
285 my $perl = $; 546 my $perl = $;
286 547
287 # first we try $^X, but the path must be absolute (always on win32), and end in sth. 548 # first we try $^X, but the path must be absolute (always on win32), and end in sth.
288 # that looks like perl. this obviously only works for posix and win32 549 # that looks like perl. this obviously only works for posix and win32
289 unless ( 550 unless (
290 (AnyEvent::Fork::Util::WIN32 || $perl =~ m%^/%) 551 ($^O eq "MSWin32" || $perl =~ m%^/%)
291 && $perl =~ m%[/\\]perl(?:[0-9]+(\.[0-9]+)+)?(\.exe)?$%i 552 && $perl =~ m%[/\\]perl(?:[0-9]+(\.[0-9]+)+)?(\.exe)?$%i
292 ) { 553 ) {
293 # if it doesn't look perlish enough, try Config 554 # if it doesn't look perlish enough, try Config
294 require Config; 555 require Config;
295 $perl = $Config::Config{perlpath}; 556 $perl = $Config::Config{perlpath};
297 } 558 }
298 559
299 require Proc::FastSpawn; 560 require Proc::FastSpawn;
300 561
301 my ($fh, $slave) = AnyEvent::Util::portable_socketpair; 562 my ($fh, $slave) = AnyEvent::Util::portable_socketpair;
302 AnyEvent::Util::fh_nonblocking $fh, 1;
303 Proc::FastSpawn::fd_inherit (fileno $slave); 563 Proc::FastSpawn::fd_inherit (fileno $slave);
564
565 # new fh's should always be set cloexec (due to $^F),
566 # but hey, not on win32, so we always clear the inherit flag.
567 Proc::FastSpawn::fd_inherit (fileno $fh, 0);
304 568
305 # quick. also doesn't work in win32. of course. what did you expect 569 # quick. also doesn't work in win32. of course. what did you expect
306 #local $ENV{PERL5LIB} = join ":", grep !ref, @INC; 570 #local $ENV{PERL5LIB} = join ":", grep !ref, @INC;
307 my %env = %ENV; 571 my %env = %ENV;
308 $env{PERL5LIB} = join ":", grep !ref, @INC; 572 $env{PERL5LIB} = join +($^O eq "MSWin32" ? ";" : ":"), grep !ref, @INC;
309 573
310 Proc::FastSpawn::spawn ( 574 my $pid = Proc::FastSpawn::spawn (
311 $perl, 575 $perl,
312 ["perl", "-MAnyEvent::Fork::Serve", "-e", "AnyEvent::Fork::Serve::me", fileno $slave], 576 ["perl", "-MAnyEvent::Fork::Serve", "-e", "AnyEvent::Fork::Serve::me", fileno $slave, $$],
313 [map "$_=$env{$_}", keys %env], 577 [map "$_=$env{$_}", keys %env],
314 ) or die "unable to spawn AnyEvent::Fork server: $!"; 578 ) or die "unable to spawn AnyEvent::Fork server: $!";
315 579
316 $self->_new ($fh) 580 $self->_new ($fh, $pid)
581}
582
583=item $pid = $proc->pid
584
585Returns the process id of the process I<iff it is a direct child of the
586process running AnyEvent::Fork>, and C<undef> otherwise.
587
588Normally, only processes created via C<< AnyEvent::Fork->new_exec >> and
589L<AnyEvent::Fork::Template> are direct children, and you are responsible
590to clean up their zombies when they die.
591
592All other processes are not direct children, and will be cleaned up by
593AnyEvent::Fork itself.
594
595=cut
596
597sub pid {
598 $_[0][PID]
599}
600
601=item $proc = $proc->eval ($perlcode, @args)
602
603Evaluates the given C<$perlcode> as ... perl code, while setting C<@_> to
604the strings specified by C<@args>, in the "main" package.
605
606This call is meant to do any custom initialisation that might be required
607(for example, the C<require> method uses it). It's not supposed to be used
608to completely take over the process, use C<run> for that.
609
610The code will usually be executed after this call returns, and there is no
611way to pass anything back to the calling process. Any evaluation errors
612will be reported to stderr and cause the process to exit.
613
614If you want to execute some code (that isn't in a module) to take over the
615process, you should compile a function via C<eval> first, and then call
616it via C<run>. This also gives you access to any arguments passed via the
617C<send_xxx> methods, such as file handles. See the L<use AnyEvent::Fork as
618a faster fork+exec> example to see it in action.
619
620Returns the process object for easy chaining of method calls.
621
622=cut
623
624sub eval {
625 my ($self, $code, @args) = @_;
626
627 $self->_cmd (e => pack "(w/a*)*", $code, @args);
628
629 $self
317} 630}
318 631
319=item $proc = $proc->require ($module, ...) 632=item $proc = $proc->require ($module, ...)
320 633
321Tries to load the given modules into the process 634Tries to load the given module(s) into the process
322 635
323Returns the process object for easy chaining of method calls. 636Returns the process object for easy chaining of method calls.
637
638=cut
639
640sub require {
641 my ($self, @modules) = @_;
642
643 s%::%/%g for @modules;
644 $self->eval ('require "$_.pm" for @_', @modules);
645
646 $self
647}
324 648
325=item $proc = $proc->send_fh ($handle, ...) 649=item $proc = $proc->send_fh ($handle, ...)
326 650
327Send one or more file handles (I<not> file descriptors) to the process, 651Send one or more file handles (I<not> file descriptors) to the process,
328to prepare a call to C<run>. 652to prepare a call to C<run>.
329 653
330The process object keeps a reference to the handles until this is done, 654The process object keeps a reference to the handles until they have
331so you must not explicitly close the handles. This is most easily 655been passed over to the process, so you must not explicitly close the
332accomplished by simply not storing the file handles anywhere after passing 656handles. This is most easily accomplished by simply not storing the file
333them to this method. 657handles anywhere after passing them to this method - when AnyEvent::Fork
658is finished using them, perl will automatically close them.
334 659
335Returns the process object for easy chaining of method calls. 660Returns the process object for easy chaining of method calls.
661
662Example: pass a file handle to a process, and release it without
663closing. It will be closed automatically when it is no longer used.
664
665 $proc->send_fh ($my_fh);
666 undef $my_fh; # free the reference if you want, but DO NOT CLOSE IT
336 667
337=cut 668=cut
338 669
339sub send_fh { 670sub send_fh {
340 my ($self, @fh) = @_; 671 my ($self, @fh) = @_;
341 672
342 for my $fh (@fh) { 673 for my $fh (@fh) {
343 $self->_cmd ("h"); 674 $self->_cmd ("h");
344 push @{ $self->[2] }, \$fh; 675 push @{ $self->[QUEUE] }, \$fh;
345 } 676 }
346 677
347 $self 678 $self
348} 679}
349 680
350=item $proc = $proc->send_arg ($string, ...) 681=item $proc = $proc->send_arg ($string, ...)
351 682
352Send one or more argument strings to the process, to prepare a call to 683Send one or more argument strings to the process, to prepare a call to
353C<run>. The strings can be any octet string. 684C<run>. The strings can be any octet strings.
354 685
686The protocol is optimised to pass a moderate number of relatively short
687strings - while you can pass up to 4GB of data in one go, this is more
688meant to pass some ID information or other startup info, not big chunks of
689data.
690
355Returns the process object for easy chaining of emthod calls. 691Returns the process object for easy chaining of method calls.
356 692
357=cut 693=cut
358 694
359sub send_arg { 695sub send_arg {
360 my ($self, @arg) = @_; 696 my ($self, @arg) = @_;
361 697
362 $self->_cmd (a => @arg); 698 $self->_cmd (a => pack "(w/a*)*", @arg);
363 699
364 $self 700 $self
365} 701}
366 702
367=item $proc->run ($func, $cb->($fh)) 703=item $proc->run ($func, $cb->($fh))
368 704
369Enter the function specified by the fully qualified name in C<$func> in 705Enter the function specified by the function name in C<$func> in the
370the process. The function is called with the communication socket as first 706process. The function is called with the communication socket as first
371argument, followed by all file handles and string arguments sent earlier 707argument, followed by all file handles and string arguments sent earlier
372via C<send_fh> and C<send_arg> methods, in the order they were called. 708via C<send_fh> and C<send_arg> methods, in the order they were called.
373 709
374If the called function returns, the process exits.
375
376Preparing the process can take time - when the process is ready, the
377callback is invoked with the local communications socket as argument.
378
379The process object becomes unusable on return from this function. 710The process object becomes unusable on return from this function - any
711further method calls result in undefined behaviour.
712
713The function name should be fully qualified, but if it isn't, it will be
714looked up in the C<main> package.
715
716If the called function returns, doesn't exist, or any error occurs, the
717process exits.
718
719Preparing the process is done in the background - when all commands have
720been sent, the callback is invoked with the local communications socket
721as argument. At this point you can start using the socket in any way you
722like.
380 723
381If the communication socket isn't used, it should be closed on both sides, 724If the communication socket isn't used, it should be closed on both sides,
382to save on kernel memory. 725to save on kernel memory.
383 726
384The socket is non-blocking in the parent, and blocking in the newly 727The socket is non-blocking in the parent, and blocking in the newly
385created process. The close-on-exec flag is set on both. Even if not used 728created process. The close-on-exec flag is set in both.
729
386otherwise, the socket can be a good indicator for the existance of the 730Even if not used otherwise, the socket can be a good indicator for the
387process - if the othe rprocess exits, you get a readable event on it, 731existence of the process - if the other process exits, you get a readable
388because exiting the process closes the socket (if it didn't create any 732event on it, because exiting the process closes the socket (if it didn't
389children using fork). 733create any children using fork).
734
735Example: create a template for a process pool, pass a few strings, some
736file handles, then fork, pass one more string, and run some code.
737
738 my $pool = AnyEvent::Fork
739 ->new
740 ->send_arg ("str1", "str2")
741 ->send_fh ($fh1, $fh2);
742
743 for (1..2) {
744 $pool
745 ->fork
746 ->send_arg ("str3")
747 ->run ("Some::function", sub {
748 my ($fh) = @_;
749
750 # fh is nonblocking, but we trust that the OS can accept these
751 # few octets anyway.
752 syswrite $fh, "hi #$_\n";
753
754 # $fh is being closed here, as we don't store it anywhere
755 });
756 }
757
758 # Some::function might look like this - all parameters passed before fork
759 # and after will be passed, in order, after the communications socket.
760 sub Some::function {
761 my ($fh, $str1, $str2, $fh1, $fh2, $str3) = @_;
762
763 print scalar <$fh>; # prints "hi #1\n" and "hi #2\n" in any order
764 }
390 765
391=cut 766=cut
392 767
393sub run { 768sub run {
394 my ($self, $func, $cb) = @_; 769 my ($self, $func, $cb) = @_;
395 770
396 $self->[0] = $cb; 771 $self->[CB] = $cb;
397 $self->_cmd ("r", $func); 772 $self->_cmd (r => $func);
398} 773}
399 774
400=back 775=back
776
777=head1 PERFORMANCE
778
779Now for some unscientific benchmark numbers (all done on an amd64
780GNU/Linux box). These are intended to give you an idea of the relative
781performance you can expect, they are not meant to be absolute performance
782numbers.
783
784OK, so, I ran a simple benchmark that creates a socket pair, forks, calls
785exit in the child and waits for the socket to close in the parent. I did
786load AnyEvent, EV and AnyEvent::Fork, for a total process size of 5100kB.
787
788 2079 new processes per second, using manual socketpair + fork
789
790Then I did the same thing, but instead of calling fork, I called
791AnyEvent::Fork->new->run ("CORE::exit") and then again waited for the
792socket form the child to close on exit. This does the same thing as manual
793socket pair + fork, except that what is forked is the template process
794(2440kB), and the socket needs to be passed to the server at the other end
795of the socket first.
796
797 2307 new processes per second, using AnyEvent::Fork->new
798
799And finally, using C<new_exec> instead C<new>, using vforks+execs to exec
800a new perl interpreter and compile the small server each time, I get:
801
802 479 vfork+execs per second, using AnyEvent::Fork->new_exec
803
804So how can C<< AnyEvent->new >> be faster than a standard fork, even
805though it uses the same operations, but adds a lot of overhead?
806
807The difference is simply the process size: forking the 5MB process takes
808so much longer than forking the 2.5MB template process that the extra
809overhead introduced is canceled out.
810
811If the benchmark process grows, the normal fork becomes even slower:
812
813 1340 new processes, manual fork of a 20MB process
814 731 new processes, manual fork of a 200MB process
815 235 new processes, manual fork of a 2000MB process
816
817What that means (to me) is that I can use this module without having a bad
818conscience because of the extra overhead required to start new processes.
819
820=head1 TYPICAL PROBLEMS
821
822This section lists typical problems that remain. I hope by recognising
823them, most can be avoided.
824
825=over 4
826
827=item leaked file descriptors for exec'ed processes
828
829POSIX systems inherit file descriptors by default when exec'ing a new
830process. While perl itself laudably sets the close-on-exec flags on new
831file handles, most C libraries don't care, and even if all cared, it's
832often not possible to set the flag in a race-free manner.
833
834That means some file descriptors can leak through. And since it isn't
835possible to know which file descriptors are "good" and "necessary" (or
836even to know which file descriptors are open), there is no good way to
837close the ones that might harm.
838
839As an example of what "harm" can be done consider a web server that
840accepts connections and afterwards some module uses AnyEvent::Fork for the
841first time, causing it to fork and exec a new process, which might inherit
842the network socket. When the server closes the socket, it is still open
843in the child (which doesn't even know that) and the client might conclude
844that the connection is still fine.
845
846For the main program, there are multiple remedies available -
847L<AnyEvent::Fork::Early> is one, creating a process early and not using
848C<new_exec> is another, as in both cases, the first process can be exec'ed
849well before many random file descriptors are open.
850
851In general, the solution for these kind of problems is to fix the
852libraries or the code that leaks those file descriptors.
853
854Fortunately, most of these leaked descriptors do no harm, other than
855sitting on some resources.
856
857=item leaked file descriptors for fork'ed processes
858
859Normally, L<AnyEvent::Fork> does start new processes by exec'ing them,
860which closes file descriptors not marked for being inherited.
861
862However, L<AnyEvent::Fork::Early> and L<AnyEvent::Fork::Template> offer
863a way to create these processes by forking, and this leaks more file
864descriptors than exec'ing them, as there is no way to mark descriptors as
865"close on fork".
866
867An example would be modules like L<EV>, L<IO::AIO> or L<Gtk2>. Both create
868pipes for internal uses, and L<Gtk2> might open a connection to the X
869server. L<EV> and L<IO::AIO> can deal with fork, but Gtk2 might have
870trouble with a fork.
871
872The solution is to either not load these modules before use'ing
873L<AnyEvent::Fork::Early> or L<AnyEvent::Fork::Template>, or to delay
874initialising them, for example, by calling C<init Gtk2> manually.
875
876=item exiting calls object destructors
877
878This only applies to users of L<AnyEvent::Fork:Early> and
879L<AnyEvent::Fork::Template>, or when initialiasing code creates objects
880that reference external resources.
881
882When a process created by AnyEvent::Fork exits, it might do so by calling
883exit, or simply letting perl reach the end of the program. At which point
884Perl runs all destructors.
885
886Not all destructors are fork-safe - for example, an object that represents
887the connection to an X display might tell the X server to free resources,
888which is inconvenient when the "real" object in the parent still needs to
889use them.
890
891This is obviously not a problem for L<AnyEvent::Fork::Early>, as you used
892it as the very first thing, right?
893
894It is a problem for L<AnyEvent::Fork::Template> though - and the solution
895is to not create objects with nontrivial destructors that might have an
896effect outside of Perl.
897
898=back
899
900=head1 PORTABILITY NOTES
901
902Native win32 perls are somewhat supported (AnyEvent::Fork::Early is a nop,
903and ::Template is not going to work), and it cost a lot of blood and sweat
904to make it so, mostly due to the bloody broken perl that nobody seems to
905care about. The fork emulation is a bad joke - I have yet to see something
906useful that you can do with it without running into memory corruption
907issues or other braindamage. Hrrrr.
908
909Cygwin perl is not supported at the moment due to some hilarious
910shortcomings of its API - see L<IO::FDPoll> for more details.
911
912=head1 SEE ALSO
913
914L<AnyEvent::Fork::Early> (to avoid executing a perl interpreter),
915L<AnyEvent::Fork::Template> (to create a process by forking the main
916program at a convenient time).
401 917
402=head1 AUTHOR 918=head1 AUTHOR
403 919
404 Marc Lehmann <schmorp@schmorp.de> 920 Marc Lehmann <schmorp@schmorp.de>
405 http://home.schmorp.de/ 921 http://home.schmorp.de/

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines