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.18 by root, Sat Apr 6 01:33:56 2013 UTC vs.
Revision 1.42 by root, Mon Apr 8 05:44:23 2013 UTC

4 4
5=head1 SYNOPSIS 5=head1 SYNOPSIS
6 6
7 use AnyEvent::Fork; 7 use AnyEvent::Fork;
8 8
9 ################################################################## 9 AnyEvent::Fork
10 ->new
11 ->require ("MyModule")
12 ->run ("MyModule::server", my $cv = AE::cv);
13
14 my $fh = $cv->recv;
15
16=head1 DESCRIPTION
17
18This module allows you to create new processes, without actually forking
19them from your current process (avoiding the problems of forking), but
20preserving most of the advantages of fork.
21
22It can be used to create new worker processes or new independent
23subprocesses for short- and long-running jobs, process pools (e.g. for use
24in pre-forked servers) but also to spawn new external processes (such as
25CGI scripts from a web server), which can be faster (and more well behaved)
26than using fork+exec in big processes.
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
63=head2 PROBLEM STATEMENT
64
65There are two traditional ways to implement parallel processing on UNIX
66like operating systems - fork and process, and fork+exec and process. They
67have different advantages and disadvantages that I describe below,
68together with how this module tries to mitigate the disadvantages.
69
70=over 4
71
72=item Forking from a big process can be very slow.
73
74A 5GB process needs 0.05s to fork on my 3.6GHz amd64 GNU/Linux box. This
75overhead is often shared with exec (because you have to fork first), but
76in some circumstances (e.g. when vfork is used), fork+exec can be much
77faster.
78
79This module can help here by telling a small(er) helper process to fork,
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.
82
83=item Forking usually creates a copy-on-write copy of the parent
84process.
85
86For example, modules or data files that are loaded will not use additional
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
90them and replaces them by new data, the child processes will retain the
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.
96
97This module allows the main program to do a controlled fork, and allows
98modules to exec processes safely at any time. When creating a custom
99process pool you can take advantage of data sharing via fork without
100risking to share large dynamic data structures that will blow up child
101memory usage.
102
103In other words, this module puts you into control over what is being
104shared and what isn't, at all times.
105
106=item Exec'ing a new perl process might be difficult.
107
108For example, it is not easy to find the correct path to the perl
109interpreter - C<$^X> might not be a perl interpreter at all.
110
111This module tries hard to identify the correct path to the perl
112interpreter. With a cooperative main program, exec'ing the interpreter
113might not even be necessary, but even without help from the main program,
114it will still work when used from a module.
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
127=item Forking might be impossible when a program is running.
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
136This module can safely fork helper processes at any time, by calling
137fork+exec in C, in a POSIX-compatible way (via L<Proc::FastSpawn>).
138
139=item Parallel processing with fork might be inconvenient or difficult
140to implement. Modules might not work in both parent and child.
141
142For example, when a program uses an event loop and creates watchers it
143becomes very hard to use the event loop from a child program, as the
144watchers already exist but are only meaningful in the parent. Worse, a
145module might want to use such a module, not knowing whether another module
146or the main program also does, leading to problems.
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
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.
158
159=back
160
161=head1 EXAMPLES
162
10 # create a single new process, tell it to run your worker function 163=head2 Create a single new process, tell it to run your worker function.
11 164
12 AnyEvent::Fork 165 AnyEvent::Fork
13 ->new 166 ->new
14 ->require ("MyModule") 167 ->require ("MyModule")
15 ->run ("MyModule::worker, sub { 168 ->run ("MyModule::worker, sub {
17 170
18 # now $master_filehandle is connected to the 171 # now $master_filehandle is connected to the
19 # $slave_filehandle in the new process. 172 # $slave_filehandle in the new process.
20 }); 173 });
21 174
22 # MyModule::worker might look like this 175C<MyModule> might look like this:
176
177 package MyModule;
178
23 sub MyModule::worker { 179 sub worker {
24 my ($slave_filehandle) = @_; 180 my ($slave_filehandle) = @_;
25 181
26 # now $slave_filehandle is connected to the $master_filehandle 182 # now $slave_filehandle is connected to the $master_filehandle
27 # in the original prorcess. have fun! 183 # in the original prorcess. have fun!
28 } 184 }
29 185
30 ##################################################################
31 # create a pool of server processes all accepting on the same socket 186=head2 Create a pool of server processes all accepting on the same socket.
32 187
33 # create listener socket 188 # create listener socket
34 my $listener = ...; 189 my $listener = ...;
35 190
36 # create a pool template, initialise it and give it the socket 191 # create a pool template, initialise it and give it the socket
48 } 203 }
49 204
50 # now do other things - maybe use the filehandle provided by run 205 # now do other things - maybe use the filehandle provided by run
51 # to wait for the processes to die. or whatever. 206 # to wait for the processes to die. or whatever.
52 207
53 # My::Server::run might look like this 208C<My::Server> might look like this:
54 sub My::Server::run { 209
210 package My::Server;
211
212 sub run {
55 my ($slave, $listener, $id) = @_; 213 my ($slave, $listener, $id) = @_;
56 214
57 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
58 216
59 # 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,
61 while (my $socket = $listener->accept) { 219 while (my $socket = $listener->accept) {
62 # do sth. with new socket 220 # do sth. with new socket
63 } 221 }
64 } 222 }
65 223
66=head1 DESCRIPTION 224=head2 use AnyEvent::Fork as a faster fork+exec
67 225
68This module allows you to create new processes, without actually forking 226This runs C</bin/echo hi>, with stdandard output redirected to /tmp/log
69them from your current process (avoiding the problems of forking), but 227and standard error redirected to the communications socket. It is usually
70preserving most of the advantages of fork. 228faster than fork+exec, but still lets you prepare the environment.
71 229
72It can be used to create new worker processes or new independent 230 open my $output, ">/tmp/log" or die "$!";
73subprocesses for short- and long-running jobs, process pools (e.g. for use
74in pre-forked servers) but also to spawn new external processes (such as
75CGI scripts from a web server), which can be faster (and more well behaved)
76than using fork+exec in big processes.
77 231
78Special care has been taken to make this module useful from other modules, 232 AnyEvent::Fork
79while still supporting specialised environments such as L<App::Staticperl> 233 ->new
80or L<PAR::Packer>. 234 ->eval ('
235 # compile a helper function for later use
236 sub run {
237 my ($fh, $output, @cmd) = @_;
81 238
82=head1 WHAT THIS MODULE IS NOT 239 # perl will clear close-on-exec on STDOUT/STDERR
240 open STDOUT, ">&", $output or die;
241 open STDERR, ">&", $fh or die;
83 242
84This module only creates processes and lets you pass file handles and 243 exec @cmd;
85strings to it, and run perl code. It does not implement any kind of RPC - 244 }
86there is no back channel from the process back to you, and there is no RPC 245 ')
87or message passing going on. 246 ->send_fh ($output)
247 ->send_arg ("/bin/echo", "hi")
248 ->run ("run", my $cv = AE::cv);
88 249
89If you need some form of RPC, you can either implement it yourself 250 my $stderr = $cv->recv;
90in whatever way you like, use some message-passing module such
91as L<AnyEvent::MP>, some pipe such as L<AnyEvent::ZeroMQ>, use
92L<AnyEvent::Handle> on both sides to send e.g. JSON or Storable messages,
93and so on.
94
95=head1 PROBLEM STATEMENT
96
97There are two ways to implement parallel processing on UNIX like operating
98systems - fork and process, and fork+exec and process. They have different
99advantages and disadvantages that I describe below, together with how this
100module tries to mitigate the disadvantages.
101
102=over 4
103
104=item Forking from a big process can be very slow (a 5GB process needs
1050.05s to fork on my 3.6GHz amd64 GNU/Linux box for example). This overhead
106is often shared with exec (because you have to fork first), but in some
107circumstances (e.g. when vfork is used), fork+exec can be much faster.
108
109This module can help here by telling a small(er) helper process to fork,
110or fork+exec instead.
111
112=item Forking usually creates a copy-on-write copy of the parent
113process. Memory (for example, modules or data files that have been
114will not take additional memory). When exec'ing a new process, modules
115and data files might need to be loaded again, at extra CPU and memory
116cost. Likewise when forking, all data structures are copied as well - if
117the program frees them and replaces them by new data, the child processes
118will retain the memory even if it isn't used.
119
120This module allows the main program to do a controlled fork, and allows
121modules to exec processes safely at any time. When creating a custom
122process pool you can take advantage of data sharing via fork without
123risking to share large dynamic data structures that will blow up child
124memory usage.
125
126=item Exec'ing a new perl process might be difficult and slow. For
127example, it is not easy to find the correct path to the perl interpreter,
128and all modules have to be loaded from disk again. Long running processes
129might run into problems when perl is upgraded for example.
130
131This module supports creating pre-initialised perl processes to be used
132as template, and also tries hard to identify the correct path to the perl
133interpreter. With a cooperative main program, exec'ing the interpreter
134might not even be necessary.
135
136=item Forking might be impossible when a program is running. For example,
137POSIX makes it almost impossible to fork from a multi-threaded program and
138do anything useful in the child - strictly speaking, if your perl program
139uses posix threads (even indirectly via e.g. L<IO::AIO> or L<threads>),
140you cannot call fork on the perl level anymore, at all.
141
142This module can safely fork helper processes at any time, by calling
143fork+exec in C, in a POSIX-compatible way.
144
145=item Parallel processing with fork might be inconvenient or difficult
146to implement. For example, when a program uses an event loop and creates
147watchers it becomes very hard to use the event loop from a child
148program, as the watchers already exist but are only meaningful in the
149parent. Worse, a module might want to use such a system, not knowing
150whether another module or the main program also does, leading to problems.
151
152This module only lets the main program create pools by forking (because
153only the main program can know when it is still safe to do so) - all other
154pools are created by fork+exec, after which such modules can again be
155loaded.
156
157=back
158 251
159=head1 CONCEPTS 252=head1 CONCEPTS
160 253
161This module can create new processes either by executing a new perl 254This module can create new processes either by executing a new perl
162process, or by forking from an existing "template" process. 255process, or by forking from an existing "template" process.
241 my ($fork_fh) = @_; 334 my ($fork_fh) = @_;
242 }); 335 });
243 336
244=back 337=back
245 338
246=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.
247 359
248=over 4 360=over 4
249 361
250=cut 362=cut
251 363
258use AnyEvent; 370use AnyEvent;
259use AnyEvent::Util (); 371use AnyEvent::Util ();
260 372
261use IO::FDPass; 373use IO::FDPass;
262 374
263our $VERSION = 0.2; 375our $VERSION = 0.6;
264
265our $PERL; # the path to the perl interpreter, deduces with various forms of magic
266
267=item my $pool = new AnyEvent::Fork key => value...
268
269Create a new process pool. The following named parameters are supported:
270 376
271=over 4 377=over 4
272 378
273=back 379=back
274 380
277# the early fork template process 383# the early fork template process
278our $EARLY; 384our $EARLY;
279 385
280# the empty template process 386# the empty template process
281our $TEMPLATE; 387our $TEMPLATE;
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}
282 409
283sub _cmd { 410sub _cmd {
284 my $self = shift; 411 my $self = shift;
285 412
286 # ideally, we would want to use "a (w/a)*" as format string, but perl 413 # ideally, we would want to use "a (w/a)*" as format string, but perl
287 # versions from at least 5.8.9 to 5.16.3 are all buggy and can't unpack 414 # versions from at least 5.8.9 to 5.16.3 are all buggy and can't unpack
288 # it. 415 # it.
289 push @{ $self->[2] }, pack "L/a*", pack "(w/a*)*", @_; 416 push @{ $self->[QUEUE] }, pack "a L/a*", $_[0], $_[1];
290 417
291 unless ($self->[3]) { 418 $self->[WW] ||= AE::io $self->[FH], 1, sub {
292 my $wcb = sub {
293 do { 419 do {
294 # send the next "thing" in the queue - either a reference to an fh, 420 # send the next "thing" in the queue - either a reference to an fh,
295 # or a plain string. 421 # or a plain string.
296 422
297 if (ref $self->[2][0]) { 423 if (ref $self->[QUEUE][0]) {
298 # send fh 424 # send fh
299 unless (IO::FDPass::send fileno $self->[1], fileno ${ $self->[2][0] }) { 425 unless (IO::FDPass::send fileno $self->[FH], fileno ${ $self->[QUEUE][0] }) {
300 return if $! == Errno::EAGAIN || $! == Errno::EWOULDBLOCK; 426 return if $! == Errno::EAGAIN || $! == Errno::EWOULDBLOCK;
301 undef $self->[3]; 427 undef $self->[WW];
302 die "AnyEvent::Fork: file descriptor send failure: $!"; 428 die "AnyEvent::Fork: file descriptor send failure: $!";
303 }
304
305 shift @{ $self->[2] };
306
307 } else {
308 # send string
309 my $len = syswrite $self->[1], $self->[2][0];
310
311 unless ($len) {
312 return if $! == Errno::EAGAIN || $! == Errno::EWOULDBLOCK;
313 undef $self->[3];
314 die "AnyEvent::Fork: command write failure: $!";
315 }
316
317 substr $self->[2][0], 0, $len, "";
318 shift @{ $self->[2] } unless length $self->[2][0];
319 } 429 }
430
431 shift @{ $self->[QUEUE] };
432
433 } else {
434 # send string
435 my $len = syswrite $self->[FH], $self->[QUEUE][0];
436
437 unless ($len) {
438 return if $! == Errno::EAGAIN || $! == Errno::EWOULDBLOCK;
439 undef $self->[3];
440 die "AnyEvent::Fork: command write failure: $!";
441 }
442
443 substr $self->[QUEUE][0], 0, $len, "";
444 shift @{ $self->[QUEUE] } unless length $self->[QUEUE][0];
445 }
320 } while @{ $self->[2] }; 446 } while @{ $self->[QUEUE] };
321 447
322 # everything written 448 # everything written
323 undef $self->[3]; 449 undef $self->[WW];
450
324 # invoke run callback 451 # invoke run callback, if any
325 $self->[0]->($self->[1]) if $self->[0]; 452 $self->[CB]->($self->[FH]) if $self->[CB];
326 };
327
328 $wcb->();
329
330 $self->[3] ||= AE::io $self->[1], 1, $wcb
331 if @{ $self->[2] };
332 } 453 };
333 454
334 () # make sure we don't leak the watcher 455 () # make sure we don't leak the watcher
335}
336
337sub _new {
338 my ($self, $fh) = @_;
339
340 AnyEvent::Util::fh_nonblocking $fh, 1;
341
342 $self = bless [
343 undef, # run callback
344 $fh,
345 [], # write queue - strings or fd's
346 undef, # AE watcher
347 ], $self;
348
349 $self
350} 456}
351 457
352# fork template from current process, used by AnyEvent::Fork::Early/Template 458# fork template from current process, used by AnyEvent::Fork::Early/Template
353sub _new_fork { 459sub _new_fork {
354 my ($fh, $slave) = AnyEvent::Util::portable_socketpair; 460 my ($fh, $slave) = AnyEvent::Util::portable_socketpair;
359 if ($pid eq 0) { 465 if ($pid eq 0) {
360 require AnyEvent::Fork::Serve; 466 require AnyEvent::Fork::Serve;
361 $AnyEvent::Fork::Serve::OWNER = $parent; 467 $AnyEvent::Fork::Serve::OWNER = $parent;
362 close $fh; 468 close $fh;
363 $0 = "$_[1] of $parent"; 469 $0 = "$_[1] of $parent";
364 $SIG{CHLD} = 'IGNORE';
365 AnyEvent::Fork::Serve::serve ($slave); 470 AnyEvent::Fork::Serve::serve ($slave);
366 exit 0; 471 exit 0;
367 } elsif (!$pid) { 472 } elsif (!$pid) {
368 die "AnyEvent::Fork::Early/Template: unable to fork template process: $!"; 473 die "AnyEvent::Fork::Early/Template: unable to fork template process: $!";
369 } 474 }
370 475
371 AnyEvent::Fork->_new ($fh) 476 AnyEvent::Fork->_new ($fh, $pid)
372} 477}
373 478
374=item my $proc = new AnyEvent::Fork 479=item my $proc = new AnyEvent::Fork
375 480
376Create a new "empty" perl interpreter process and returns its process 481Create a new "empty" perl interpreter process and returns its process
377object for further manipulation. 482object for further manipulation.
378 483
379The 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
380for 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
381C<new_exec> and kept around for future calls. 486C<new_exec> first and then stays around for future calls.
382
383When the process object is destroyed, it will release the file handle
384that connects it with the new process. When the new process has not yet
385called C<run>, then the process will exit. Otherwise, what happens depends
386entirely on the code that is executed.
387 487
388=cut 488=cut
389 489
390sub new { 490sub new {
391 my $class = shift; 491 my $class = shift;
469 # 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
470 #local $ENV{PERL5LIB} = join ":", grep !ref, @INC; 570 #local $ENV{PERL5LIB} = join ":", grep !ref, @INC;
471 my %env = %ENV; 571 my %env = %ENV;
472 $env{PERL5LIB} = join +($^O eq "MSWin32" ? ";" : ":"), grep !ref, @INC; 572 $env{PERL5LIB} = join +($^O eq "MSWin32" ? ";" : ":"), grep !ref, @INC;
473 573
474 Proc::FastSpawn::spawn ( 574 my $pid = Proc::FastSpawn::spawn (
475 $perl, 575 $perl,
476 ["perl", "-MAnyEvent::Fork::Serve", "-e", "AnyEvent::Fork::Serve::me", fileno $slave, $$], 576 ["perl", "-MAnyEvent::Fork::Serve", "-e", "AnyEvent::Fork::Serve::me", fileno $slave, $$],
477 [map "$_=$env{$_}", keys %env], 577 [map "$_=$env{$_}", keys %env],
478 ) or die "unable to spawn AnyEvent::Fork server: $!"; 578 ) or die "unable to spawn AnyEvent::Fork server: $!";
479 579
480 $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]
481} 599}
482 600
483=item $proc = $proc->eval ($perlcode, @args) 601=item $proc = $proc->eval ($perlcode, @args)
484 602
485Evaluates the given C<$perlcode> as ... perl code, while setting C<@_> to 603Evaluates the given C<$perlcode> as ... perl code, while setting C<@_> to
486the strings specified by C<@args>. 604the strings specified by C<@args>, in the "main" package.
487 605
488This call is meant to do any custom initialisation that might be required 606This call is meant to do any custom initialisation that might be required
489(for example, the C<require> method uses it). It's not supposed to be used 607(for example, the C<require> method uses it). It's not supposed to be used
490to completely take over the process, use C<run> for that. 608to completely take over the process, use C<run> for that.
491 609
492The code will usually be executed after this call returns, and there is no 610The code will usually be executed after this call returns, and there is no
493way to pass anything back to the calling process. Any evaluation errors 611way to pass anything back to the calling process. Any evaluation errors
494will be reported to stderr and cause the process to exit. 612will be reported to stderr and cause the process to exit.
495 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
496Returns the process object for easy chaining of method calls. 620Returns the process object for easy chaining of method calls.
497 621
498=cut 622=cut
499 623
500sub eval { 624sub eval {
501 my ($self, $code, @args) = @_; 625 my ($self, $code, @args) = @_;
502 626
503 $self->_cmd (e => $code, @args); 627 $self->_cmd (e => pack "(w/a*)*", $code, @args);
504 628
505 $self 629 $self
506} 630}
507 631
508=item $proc = $proc->require ($module, ...) 632=item $proc = $proc->require ($module, ...)
525=item $proc = $proc->send_fh ($handle, ...) 649=item $proc = $proc->send_fh ($handle, ...)
526 650
527Send 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,
528to prepare a call to C<run>. 652to prepare a call to C<run>.
529 653
530The process object keeps a reference to the handles until this is done, 654The process object keeps a reference to the handles until they have
531so you must not explicitly close the handles. This is most easily 655been passed over to the process, so you must not explicitly close the
532accomplished by simply not storing the file handles anywhere after passing 656handles. This is most easily accomplished by simply not storing the file
533them to this method. 657handles anywhere after passing them to this method - when AnyEvent::Fork
658is finished using them, perl will automatically close them.
534 659
535Returns the process object for easy chaining of method calls. 660Returns the process object for easy chaining of method calls.
536 661
537Example: pass a file handle to a process, and release it without 662Example: pass a file handle to a process, and release it without
538closing. It will be closed automatically when it is no longer used. 663closing. It will be closed automatically when it is no longer used.
545sub send_fh { 670sub send_fh {
546 my ($self, @fh) = @_; 671 my ($self, @fh) = @_;
547 672
548 for my $fh (@fh) { 673 for my $fh (@fh) {
549 $self->_cmd ("h"); 674 $self->_cmd ("h");
550 push @{ $self->[2] }, \$fh; 675 push @{ $self->[QUEUE] }, \$fh;
551 } 676 }
552 677
553 $self 678 $self
554} 679}
555 680
556=item $proc = $proc->send_arg ($string, ...) 681=item $proc = $proc->send_arg ($string, ...)
557 682
558Send 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
559C<run>. The strings can be any octet string. 684C<run>. The strings can be any octet strings.
560 685
561The protocol is optimised to pass a moderate number of relatively short 686The protocol is optimised to pass a moderate number of relatively short
562strings - while you can pass up to 4GB of data in one go, this is more 687strings - while you can pass up to 4GB of data in one go, this is more
563meant to pass some ID information or other startup info, not big chunks of 688meant to pass some ID information or other startup info, not big chunks of
564data. 689data.
568=cut 693=cut
569 694
570sub send_arg { 695sub send_arg {
571 my ($self, @arg) = @_; 696 my ($self, @arg) = @_;
572 697
573 $self->_cmd (a => @arg); 698 $self->_cmd (a => pack "(w/a*)*", @arg);
574 699
575 $self 700 $self
576} 701}
577 702
578=item $proc->run ($func, $cb->($fh)) 703=item $proc->run ($func, $cb->($fh))
579 704
580Enter 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
581the process. The function is called with the communication socket as first 706process. The function is called with the communication socket as first
582argument, followed by all file handles and string arguments sent earlier 707argument, followed by all file handles and string arguments sent earlier
583via 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.
584 709
585If the called function returns, the process exits.
586
587Preparing the process can take time - when the process is ready, the
588callback is invoked with the local communications socket as argument.
589
590The 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.
591 723
592If 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,
593to save on kernel memory. 725to save on kernel memory.
594 726
595The 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
596created 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
597otherwise, the socket can be a good indicator for the existence of the 730Even if not used otherwise, the socket can be a good indicator for the
598process - if the other process exits, you get a readable event on it, 731existence of the process - if the other process exits, you get a readable
599because 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
600children using fork). 733create any children using fork).
601 734
602Example: create a template for a process pool, pass a few strings, some 735Example: create a template for a process pool, pass a few strings, some
603file handles, then fork, pass one more string, and run some code. 736file handles, then fork, pass one more string, and run some code.
604 737
605 my $pool = AnyEvent::Fork 738 my $pool = AnyEvent::Fork
613 ->send_arg ("str3") 746 ->send_arg ("str3")
614 ->run ("Some::function", sub { 747 ->run ("Some::function", sub {
615 my ($fh) = @_; 748 my ($fh) = @_;
616 749
617 # fh is nonblocking, but we trust that the OS can accept these 750 # fh is nonblocking, but we trust that the OS can accept these
618 # extra 3 octets anyway. 751 # few octets anyway.
619 syswrite $fh, "hi #$_\n"; 752 syswrite $fh, "hi #$_\n";
620 753
621 # $fh is being closed here, as we don't store it anywhere 754 # $fh is being closed here, as we don't store it anywhere
622 }); 755 });
623 } 756 }
625 # Some::function might look like this - all parameters passed before fork 758 # Some::function might look like this - all parameters passed before fork
626 # and after will be passed, in order, after the communications socket. 759 # and after will be passed, in order, after the communications socket.
627 sub Some::function { 760 sub Some::function {
628 my ($fh, $str1, $str2, $fh1, $fh2, $str3) = @_; 761 my ($fh, $str1, $str2, $fh1, $fh2, $str3) = @_;
629 762
630 print scalar <$fh>; # prints "hi 1\n" and "hi 2\n" 763 print scalar <$fh>; # prints "hi #1\n" and "hi #2\n" in any order
631 } 764 }
632 765
633=cut 766=cut
634 767
635sub run { 768sub run {
636 my ($self, $func, $cb) = @_; 769 my ($self, $func, $cb) = @_;
637 770
638 $self->[0] = $cb; 771 $self->[CB] = $cb;
639 $self->_cmd (r => $func); 772 $self->_cmd (r => $func);
640} 773}
641 774
642=back 775=back
643 776
669 479 vfork+execs per second, using AnyEvent::Fork->new_exec 802 479 vfork+execs per second, using AnyEvent::Fork->new_exec
670 803
671So how can C<< AnyEvent->new >> be faster than a standard fork, even 804So how can C<< AnyEvent->new >> be faster than a standard fork, even
672though it uses the same operations, but adds a lot of overhead? 805though it uses the same operations, but adds a lot of overhead?
673 806
674The difference is simply the process size: forking the 6MB process takes 807The difference is simply the process size: forking the 5MB process takes
675so much longer than forking the 2.5MB template process that the overhead 808so much longer than forking the 2.5MB template process that the extra
676introduced is canceled out. 809overhead introduced is canceled out.
677 810
678If the benchmark process grows, the normal fork becomes even slower: 811If the benchmark process grows, the normal fork becomes even slower:
679 812
680 1340 new processes, manual fork in a 20MB process 813 1340 new processes, manual fork of a 20MB process
681 731 new processes, manual fork in a 200MB process 814 731 new processes, manual fork of a 200MB process
682 235 new processes, manual fork in a 2000MB process 815 235 new processes, manual fork of a 2000MB process
683 816
684What that means (to me) is that I can use this module without having a 817What that means (to me) is that I can use this module without having a bad
685very bad conscience because of the extra overhead required to start new 818conscience because of the extra overhead required to start new processes.
686processes.
687 819
688=head1 TYPICAL PROBLEMS 820=head1 TYPICAL PROBLEMS
689 821
690This section lists typical problems that remain. I hope by recognising 822This section lists typical problems that remain. I hope by recognising
691them, most can be avoided. 823them, most can be avoided.
692 824
693=over 4 825=over 4
694 826
695=item exit runs destructors
696
697=item "leaked" file descriptors for exec'ed processes 827=item leaked file descriptors for exec'ed processes
698 828
699POSIX systems inherit file descriptors by default when exec'ing a new 829POSIX systems inherit file descriptors by default when exec'ing a new
700process. While perl itself laudably sets the close-on-exec flags on new 830process. While perl itself laudably sets the close-on-exec flags on new
701file handles, most C libraries don't care, and even if all cared, it's 831file handles, most C libraries don't care, and even if all cared, it's
702often not possible to set the flag in a race-free manner. 832often not possible to set the flag in a race-free manner.
722libraries or the code that leaks those file descriptors. 852libraries or the code that leaks those file descriptors.
723 853
724Fortunately, most of these leaked descriptors do no harm, other than 854Fortunately, most of these leaked descriptors do no harm, other than
725sitting on some resources. 855sitting on some resources.
726 856
727=item "leaked" file descriptors for fork'ed processes 857=item leaked file descriptors for fork'ed processes
728 858
729Normally, L<AnyEvent::Fork> does start new processes by exec'ing them, 859Normally, L<AnyEvent::Fork> does start new processes by exec'ing them,
730which closes file descriptors not marked for being inherited. 860which closes file descriptors not marked for being inherited.
731 861
732However, L<AnyEvent::Fork::Early> and L<AnyEvent::Fork::Template> offer 862However, L<AnyEvent::Fork::Early> and L<AnyEvent::Fork::Template> offer
740trouble with a fork. 870trouble with a fork.
741 871
742The solution is to either not load these modules before use'ing 872The solution is to either not load these modules before use'ing
743L<AnyEvent::Fork::Early> or L<AnyEvent::Fork::Template>, or to delay 873L<AnyEvent::Fork::Early> or L<AnyEvent::Fork::Template>, or to delay
744initialising them, for example, by calling C<init Gtk2> manually. 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.
745 897
746=back 898=back
747 899
748=head1 PORTABILITY NOTES 900=head1 PORTABILITY NOTES
749 901
752to make it so, mostly due to the bloody broken perl that nobody seems to 904to make it so, mostly due to the bloody broken perl that nobody seems to
753care about. The fork emulation is a bad joke - I have yet to see something 905care about. The fork emulation is a bad joke - I have yet to see something
754useful that you can do with it without running into memory corruption 906useful that you can do with it without running into memory corruption
755issues or other braindamage. Hrrrr. 907issues or other braindamage. Hrrrr.
756 908
757Cygwin perl is not supported at the moment, as it should implement fd 909Cygwin perl is not supported at the moment due to some hilarious
758passing, but doesn't, and rolling my own is hard, as cygwin doesn't 910shortcomings of its API - see L<IO::FDPoll> for more details.
759support enough functionality to do it.
760 911
761=head1 SEE ALSO 912=head1 SEE ALSO
762 913
763L<AnyEvent::Fork::Early> (to avoid executing a perl interpreter), 914L<AnyEvent::Fork::Early> (to avoid executing a perl interpreter),
764L<AnyEvent::Fork::Template> (to create a process by forking the main 915L<AnyEvent::Fork::Template> (to create a process by forking the main

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines