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.25 by root, Sat Apr 6 08:55:16 2013 UTC vs.
Revision 1.41 by root, Mon Apr 8 03:20:53 2013 UTC

… …
27 27
28Special care has been taken to make this module useful from other modules, 28Special care has been taken to make this module useful from other modules,
29while still supporting specialised environments such as L<App::Staticperl> 29while still supporting specialised environments such as L<App::Staticperl>
30or L<PAR::Packer>. 30or L<PAR::Packer>.
31 31
32=head1 WHAT THIS MODULE IS NOT 32=head2 WHAT THIS MODULE IS NOT
33 33
34This module only creates processes and lets you pass file handles and 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 - 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 36there is no back channel from the process back to you, and there is no RPC
37or message passing going on. 37or message passing going on.
… …
40in whatever way you like, use some message-passing module such 40in whatever way you like, use some message-passing module such
41as L<AnyEvent::MP>, some pipe such as L<AnyEvent::ZeroMQ>, use 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, 42L<AnyEvent::Handle> on both sides to send e.g. JSON or Storable messages,
43and so on. 43and so on.
44 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
45=head1 PROBLEM STATEMENT 63=head2 PROBLEM STATEMENT
46 64
47There are two traditional ways to implement parallel processing on UNIX 65There are two traditional ways to implement parallel processing on UNIX
48like operating systems - fork and process, and fork+exec and process. They 66like operating systems - fork and process, and fork+exec and process. They
49have different advantages and disadvantages that I describe below, 67have different advantages and disadvantages that I describe below,
50together with how this module tries to mitigate the disadvantages. 68together with how this module tries to mitigate the disadvantages.
… …
125becomes very hard to use the event loop from a child program, as the 143becomes very hard to use the event loop from a child program, as the
126watchers already exist but are only meaningful in the parent. Worse, a 144watchers already exist but are only meaningful in the parent. Worse, a
127module might want to use such a module, not knowing whether another module 145module might want to use such a module, not knowing whether another module
128or the main program also does, leading to problems. 146or the main program also does, leading to problems.
129 147
148Apart from event loops, graphical toolkits also commonly fall into the
149"unsafe module" category, or just about anything that communicates with
150the external world, such as network libraries and file I/O modules, which
151usually don't like being copied and then allowed to continue in two
152processes.
153
130With this module only the main program is allowed to create new processes 154With this module only the main program is allowed to create new processes
131by forking (because only the main program can know when it is still safe 155by forking (because only the main program can know when it is still safe
132to do so) - all other processes are created via fork+exec, which makes it 156to do so) - all other processes are created via fork+exec, which makes it
133possible to use modules such as event loops or window interfaces safely. 157possible to use modules such as event loops or window interfaces safely.
134 158
… …
146 170
147 # now $master_filehandle is connected to the 171 # now $master_filehandle is connected to the
148 # $slave_filehandle in the new process. 172 # $slave_filehandle in the new process.
149 }); 173 });
150 174
151 # MyModule::worker might look like this 175C<MyModule> might look like this:
176
177 package MyModule;
178
152 sub MyModule::worker { 179 sub worker {
153 my ($slave_filehandle) = @_; 180 my ($slave_filehandle) = @_;
154 181
155 # now $slave_filehandle is connected to the $master_filehandle 182 # now $slave_filehandle is connected to the $master_filehandle
156 # in the original prorcess. have fun! 183 # in the original prorcess. have fun!
157 } 184 }
… …
176 } 203 }
177 204
178 # now do other things - maybe use the filehandle provided by run 205 # now do other things - maybe use the filehandle provided by run
179 # to wait for the processes to die. or whatever. 206 # to wait for the processes to die. or whatever.
180 207
181 # My::Server::run might look like this 208C<My::Server> might look like this:
182 sub My::Server::run { 209
210 package My::Server;
211
212 sub run {
183 my ($slave, $listener, $id) = @_; 213 my ($slave, $listener, $id) = @_;
184 214
185 close $slave; # we do not use the socket, so close it to save resources 215 close $slave; # we do not use the socket, so close it to save resources
186 216
187 # we could go ballistic and use e.g. AnyEvent here, or IO::AIO, 217 # we could go ballistic and use e.g. AnyEvent here, or IO::AIO,
… …
191 } 221 }
192 } 222 }
193 223
194=head2 use AnyEvent::Fork as a faster fork+exec 224=head2 use AnyEvent::Fork as a faster fork+exec
195 225
196This runs /bin/echo hi, with stdout redirected to /tmp/log and stderr to 226This runs C</bin/echo hi>, with stdandard output redirected to /tmp/log
197the communications socket. It is usually faster than fork+exec, but still 227and standard error redirected to the communications socket. It is usually
198let's you prepare the environment. 228faster than fork+exec, but still lets you prepare the environment.
199 229
200 open my $output, ">/tmp/log" or die "$!"; 230 open my $output, ">/tmp/log" or die "$!";
201 231
202 AnyEvent::Fork 232 AnyEvent::Fork
203 ->new 233 ->new
204 ->eval (' 234 ->eval ('
235 # compile a helper function for later use
205 sub run { 236 sub run {
206 my ($fh, $output, @cmd) = @_; 237 my ($fh, $output, @cmd) = @_;
207 238
208 # perl will clear close-on-exec on STDOUT/STDERR 239 # perl will clear close-on-exec on STDOUT/STDERR
209 open STDOUT, ">&", $output or die; 240 open STDOUT, ">&", $output or die;
… …
303 my ($fork_fh) = @_; 334 my ($fork_fh) = @_;
304 }); 335 });
305 336
306=back 337=back
307 338
308=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.
309 359
310=over 4 360=over 4
311 361
312=cut 362=cut
313 363
… …
320use AnyEvent; 370use AnyEvent;
321use AnyEvent::Util (); 371use AnyEvent::Util ();
322 372
323use IO::FDPass; 373use IO::FDPass;
324 374
325our $VERSION = 0.5; 375our $VERSION = 0.6;
326
327our $PERL; # the path to the perl interpreter, deduces with various forms of magic
328
329=item my $pool = new AnyEvent::Fork key => value...
330
331Create a new process pool. The following named parameters are supported:
332 376
333=over 4 377=over 4
334 378
335=back 379=back
336 380
… …
415 if ($pid eq 0) { 459 if ($pid eq 0) {
416 require AnyEvent::Fork::Serve; 460 require AnyEvent::Fork::Serve;
417 $AnyEvent::Fork::Serve::OWNER = $parent; 461 $AnyEvent::Fork::Serve::OWNER = $parent;
418 close $fh; 462 close $fh;
419 $0 = "$_[1] of $parent"; 463 $0 = "$_[1] of $parent";
420 $SIG{CHLD} = 'IGNORE';
421 AnyEvent::Fork::Serve::serve ($slave); 464 AnyEvent::Fork::Serve::serve ($slave);
422 exit 0; 465 exit 0;
423 } elsif (!$pid) { 466 } elsif (!$pid) {
424 die "AnyEvent::Fork::Early/Template: unable to fork template process: $!"; 467 die "AnyEvent::Fork::Early/Template: unable to fork template process: $!";
425 } 468 }
… …
432Create a new "empty" perl interpreter process and returns its process 475Create a new "empty" perl interpreter process and returns its process
433object for further manipulation. 476object for further manipulation.
434 477
435The new process is forked from a template process that is kept around 478The new process is forked from a template process that is kept around
436for this purpose. When it doesn't exist yet, it is created by a call to 479for this purpose. When it doesn't exist yet, it is created by a call to
437C<new_exec> and kept around for future calls. 480C<new_exec> first and then stays around for future calls.
438
439When the process object is destroyed, it will release the file handle
440that connects it with the new process. When the new process has not yet
441called C<run>, then the process will exit. Otherwise, what happens depends
442entirely on the code that is executed.
443 481
444=cut 482=cut
445 483
446sub new { 484sub new {
447 my $class = shift; 485 my $class = shift;
… …
537} 575}
538 576
539=item $pid = $proc->pid 577=item $pid = $proc->pid
540 578
541Returns the process id of the process I<iff it is a direct child of the 579Returns the process id of the process I<iff it is a direct child of the
542process> running AnyEvent::Fork, and C<undef> otherwise. 580process running AnyEvent::Fork>, and C<undef> otherwise.
543 581
544Normally, only processes created via C<< AnyEvent::Fork->new_exec >> and 582Normally, only processes created via C<< AnyEvent::Fork->new_exec >> and
545L<AnyEvent::Fork::Template> are direct children, and you are responsible 583L<AnyEvent::Fork::Template> are direct children, and you are responsible
546to clean up their zombies when they die. 584to clean up their zombies when they die.
547 585
548All other processes are not direct children, and will be cleaned up by 586All other processes are not direct children, and will be cleaned up by
549AnyEvent::Fork. 587AnyEvent::Fork itself.
550 588
551=cut 589=cut
552 590
553sub pid { 591sub pid {
554 $_[0][0] 592 $_[0][0]
… …
565 603
566The code will usually be executed after this call returns, and there is no 604The code will usually be executed after this call returns, and there is no
567way to pass anything back to the calling process. Any evaluation errors 605way to pass anything back to the calling process. Any evaluation errors
568will be reported to stderr and cause the process to exit. 606will be reported to stderr and cause the process to exit.
569 607
570If you want to execute some code to take over the process (see the 608If you want to execute some code (that isn't in a module) to take over the
571"fork+exec" example in the SYNOPSIS), you should compile a function via 609process, you should compile a function via C<eval> first, and then call
572C<eval> first, and then call it via C<run>. This also gives you access to 610it via C<run>. This also gives you access to any arguments passed via the
573any arguments passed via the C<send_xxx> methods, such as file handles. 611C<send_xxx> methods, such as file handles. See the L<use AnyEvent::Fork as
612a faster fork+exec> example to see it in action.
574 613
575Returns the process object for easy chaining of method calls. 614Returns the process object for easy chaining of method calls.
576 615
577=cut 616=cut
578 617
… …
604=item $proc = $proc->send_fh ($handle, ...) 643=item $proc = $proc->send_fh ($handle, ...)
605 644
606Send one or more file handles (I<not> file descriptors) to the process, 645Send one or more file handles (I<not> file descriptors) to the process,
607to prepare a call to C<run>. 646to prepare a call to C<run>.
608 647
609The process object keeps a reference to the handles until this is done, 648The process object keeps a reference to the handles until they have
610so you must not explicitly close the handles. This is most easily 649been passed over to the process, so you must not explicitly close the
611accomplished by simply not storing the file handles anywhere after passing 650handles. This is most easily accomplished by simply not storing the file
612them to this method. 651handles anywhere after passing them to this method - when AnyEvent::Fork
652is finished using them, perl will automatically close them.
613 653
614Returns the process object for easy chaining of method calls. 654Returns the process object for easy chaining of method calls.
615 655
616Example: pass a file handle to a process, and release it without 656Example: pass a file handle to a process, and release it without
617closing. It will be closed automatically when it is no longer used. 657closing. It will be closed automatically when it is no longer used.
… …
633} 673}
634 674
635=item $proc = $proc->send_arg ($string, ...) 675=item $proc = $proc->send_arg ($string, ...)
636 676
637Send one or more argument strings to the process, to prepare a call to 677Send one or more argument strings to the process, to prepare a call to
638C<run>. The strings can be any octet string. 678C<run>. The strings can be any octet strings.
639 679
640The protocol is optimised to pass a moderate number of relatively short 680The protocol is optimised to pass a moderate number of relatively short
641strings - while you can pass up to 4GB of data in one go, this is more 681strings - while you can pass up to 4GB of data in one go, this is more
642meant to pass some ID information or other startup info, not big chunks of 682meant to pass some ID information or other startup info, not big chunks of
643data. 683data.
… …
659Enter the function specified by the function name in C<$func> in the 699Enter the function specified by the function name in C<$func> in the
660process. The function is called with the communication socket as first 700process. The function is called with the communication socket as first
661argument, followed by all file handles and string arguments sent earlier 701argument, followed by all file handles and string arguments sent earlier
662via C<send_fh> and C<send_arg> methods, in the order they were called. 702via C<send_fh> and C<send_arg> methods, in the order they were called.
663 703
704The process object becomes unusable on return from this function - any
705further method calls result in undefined behaviour.
706
664The function name should be fully qualified, but if it isn't, it will be 707The function name should be fully qualified, but if it isn't, it will be
665looked up in the main package. 708looked up in the C<main> package.
666 709
667If the called function returns, doesn't exist, or any error occurs, the 710If the called function returns, doesn't exist, or any error occurs, the
668process exits. 711process exits.
669 712
670Preparing the process is done in the background - when all commands have 713Preparing the process is done in the background - when all commands have
671been sent, the callback is invoked with the local communications socket 714been sent, the callback is invoked with the local communications socket
672as argument. At this point you can start using the socket in any way you 715as argument. At this point you can start using the socket in any way you
673like. 716like.
674
675The process object becomes unusable on return from this function - any
676further method calls result in undefined behaviour.
677 717
678If the communication socket isn't used, it should be closed on both sides, 718If the communication socket isn't used, it should be closed on both sides,
679to save on kernel memory. 719to save on kernel memory.
680 720
681The socket is non-blocking in the parent, and blocking in the newly 721The socket is non-blocking in the parent, and blocking in the newly
… …
756 479 vfork+execs per second, using AnyEvent::Fork->new_exec 796 479 vfork+execs per second, using AnyEvent::Fork->new_exec
757 797
758So how can C<< AnyEvent->new >> be faster than a standard fork, even 798So how can C<< AnyEvent->new >> be faster than a standard fork, even
759though it uses the same operations, but adds a lot of overhead? 799though it uses the same operations, but adds a lot of overhead?
760 800
761The difference is simply the process size: forking the 6MB process takes 801The difference is simply the process size: forking the 5MB process takes
762so much longer than forking the 2.5MB template process that the overhead 802so much longer than forking the 2.5MB template process that the extra
763introduced is canceled out. 803overhead introduced is canceled out.
764 804
765If the benchmark process grows, the normal fork becomes even slower: 805If the benchmark process grows, the normal fork becomes even slower:
766 806
767 1340 new processes, manual fork in a 20MB process 807 1340 new processes, manual fork of a 20MB process
768 731 new processes, manual fork in a 200MB process 808 731 new processes, manual fork of a 200MB process
769 235 new processes, manual fork in a 2000MB process 809 235 new processes, manual fork of a 2000MB process
770 810
771What that means (to me) is that I can use this module without having a 811What that means (to me) is that I can use this module without having a bad
772very bad conscience because of the extra overhead required to start new 812conscience because of the extra overhead required to start new processes.
773processes.
774 813
775=head1 TYPICAL PROBLEMS 814=head1 TYPICAL PROBLEMS
776 815
777This section lists typical problems that remain. I hope by recognising 816This section lists typical problems that remain. I hope by recognising
778them, most can be avoided. 817them, most can be avoided.
779 818
780=over 4 819=over 4
781 820
782=item "leaked" file descriptors for exec'ed processes 821=item leaked file descriptors for exec'ed processes
783 822
784POSIX systems inherit file descriptors by default when exec'ing a new 823POSIX systems inherit file descriptors by default when exec'ing a new
785process. While perl itself laudably sets the close-on-exec flags on new 824process. While perl itself laudably sets the close-on-exec flags on new
786file handles, most C libraries don't care, and even if all cared, it's 825file handles, most C libraries don't care, and even if all cared, it's
787often not possible to set the flag in a race-free manner. 826often not possible to set the flag in a race-free manner.
… …
807libraries or the code that leaks those file descriptors. 846libraries or the code that leaks those file descriptors.
808 847
809Fortunately, most of these leaked descriptors do no harm, other than 848Fortunately, most of these leaked descriptors do no harm, other than
810sitting on some resources. 849sitting on some resources.
811 850
812=item "leaked" file descriptors for fork'ed processes 851=item leaked file descriptors for fork'ed processes
813 852
814Normally, L<AnyEvent::Fork> does start new processes by exec'ing them, 853Normally, L<AnyEvent::Fork> does start new processes by exec'ing them,
815which closes file descriptors not marked for being inherited. 854which closes file descriptors not marked for being inherited.
816 855
817However, L<AnyEvent::Fork::Early> and L<AnyEvent::Fork::Template> offer 856However, L<AnyEvent::Fork::Early> and L<AnyEvent::Fork::Template> offer
… …
826 865
827The solution is to either not load these modules before use'ing 866The solution is to either not load these modules before use'ing
828L<AnyEvent::Fork::Early> or L<AnyEvent::Fork::Template>, or to delay 867L<AnyEvent::Fork::Early> or L<AnyEvent::Fork::Template>, or to delay
829initialising them, for example, by calling C<init Gtk2> manually. 868initialising them, for example, by calling C<init Gtk2> manually.
830 869
831=item exit runs destructors 870=item exiting calls object destructors
832 871
833This only applies to users of Lc<AnyEvent::Fork:Early> and 872This only applies to users of L<AnyEvent::Fork:Early> and
834L<AnyEvent::Fork::Template>. 873L<AnyEvent::Fork::Template>, or when initialiasing code creates objects
874that reference external resources.
835 875
836When a process created by AnyEvent::Fork exits, it might do so by calling 876When a process created by AnyEvent::Fork exits, it might do so by calling
837exit, or simply letting perl reach the end of the program. At which point 877exit, or simply letting perl reach the end of the program. At which point
838Perl runs all destructors. 878Perl runs all destructors.
839 879
… …
858to make it so, mostly due to the bloody broken perl that nobody seems to 898to make it so, mostly due to the bloody broken perl that nobody seems to
859care about. The fork emulation is a bad joke - I have yet to see something 899care about. The fork emulation is a bad joke - I have yet to see something
860useful that you can do with it without running into memory corruption 900useful that you can do with it without running into memory corruption
861issues or other braindamage. Hrrrr. 901issues or other braindamage. Hrrrr.
862 902
863Cygwin perl is not supported at the moment, as it should implement fd 903Cygwin perl is not supported at the moment due to some hilarious
864passing, but doesn't, and rolling my own is hard, as cygwin doesn't 904shortcomings of its API - see L<IO::FDPoll> for more details.
865support enough functionality to do it.
866 905
867=head1 SEE ALSO 906=head1 SEE ALSO
868 907
869L<AnyEvent::Fork::Early> (to avoid executing a perl interpreter), 908L<AnyEvent::Fork::Early> (to avoid executing a perl interpreter),
870L<AnyEvent::Fork::Template> (to create a process by forking the main 909L<AnyEvent::Fork::Template> (to create a process by forking the main

Diff Legend

– Removed lines
+ Added lines
< Changed lines
> Changed lines