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.3 by root, Tue Apr 2 18:00:04 2013 UTC vs.
Revision 1.55 by root, Fri Apr 26 23:24:30 2013 UTC

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

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines