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

Comparing AnyEvent-Fork/README (file contents):
Revision 1.6 by root, Thu Apr 18 20:17:35 2013 UTC vs.
Revision 1.7 by root, Sun Apr 21 12:26:00 2013 UTC

… …
34 34
35 If you need some form of RPC, you could use the AnyEvent::Fork::RPC 35 If you need some form of RPC, you could use the AnyEvent::Fork::RPC
36 companion module, which adds simple RPC/job queueing to a process 36 companion module, which adds simple RPC/job queueing to a process
37 created by this module. 37 created by this module.
38 38
39 And if you need some automatic process pool management on top of
40 AnyEvent::Fork::RPC, you can look at the AnyEvent::Fork::Pool companion
41 module.
42
39 Or you can implement it yourself in whatever way you like, use some 43 Or you can implement it yourself in whatever way you like: use some
40 message-passing module such as AnyEvent::MP, some pipe such as 44 message-passing module such as AnyEvent::MP, some pipe such as
41 AnyEvent::ZeroMQ, use AnyEvent::Handle on both sides to send e.g. JSON 45 AnyEvent::ZeroMQ, use AnyEvent::Handle on both sides to send e.g. JSON
42 or Storable messages, and so on. 46 or Storable messages, and so on.
43 47
44 COMPARISON TO OTHER MODULES 48 COMPARISON TO OTHER MODULES
… …
233 ->send_arg ("/bin/echo", "hi") 237 ->send_arg ("/bin/echo", "hi")
234 ->run ("run", my $cv = AE::cv); 238 ->run ("run", my $cv = AE::cv);
235 239
236 my $stderr = $cv->recv; 240 my $stderr = $cv->recv;
237 241
238CONCEPTS 242 For stingy users: put the worker code into a "DATA" section.
243 When you want to be stingy with files, you cna put your code into the
244 "DATA" section of your module (or program):
245
246 use AnyEvent::Fork;
247
248 AnyEvent::Fork
249 ->new
250 ->eval (do { local $/; <DATA> })
251 ->run ("doit", sub { ... });
252
253 __DATA__
254
255 sub doit {
256 ... do something!
257 }
258
259 For stingy standalone programs: do not rely on external files at
260all.
261 For single-file scripts it can be inconvenient to rely on external files
262 - even when using < "DATA" section, you still need to "exec" an external
263 perl interpreter, which might not be available when using
264 App::Staticperl, Urlader or PAR::Packer for example.
265
266 Two modules help here - AnyEvent::Fork::Early forks a template process
267 for all further calls to "new_exec", and AnyEvent::Fork::Template forks
268 the main program as a template process.
269
270 Here is how your main program should look like:
271
272 #! perl
273
274 # optional, as the very first thing.
275 # in case modules want to create their own processes.
276 use AnyEvent::Fork::Early;
277
278 # next, load all modules you need in your template process
279 use Example::My::Module
280 use Example::Whatever;
281
282 # next, put your run function definition and anything else you
283 # need, but do not use code outside of BEGIN blocks.
284 sub worker_run {
285 my ($fh, @args) = @_;
286 ...
287 }
288
289 # now preserve everything so far as AnyEvent::Fork object
290 # in §TEMPLATE.
291 use AnyEvent::Fork::Template;
292
293 # do not put code outside of BEGIN blocks until here
294
295 # now use the $TEMPLATE process in any way you like
296
297 # for example: create 10 worker processes
298 my @worker;
299 my $cv = AE::cv;
300 for (1..10) {
301 $cv->begin;
302 $TEMPLATE->fork->send_arg ($_)->run ("worker_run", sub {
303 push @worker, shift;
304 $cv->end;
305 });
306 }
307 $cv->recv;
308
309 lhead1 CONCEPTS
310
239 This module can create new processes either by executing a new perl 311 This module can create new processes either by executing a new perl
240 process, or by forking from an existing "template" process. 312 process, or by forking from an existing "template" process.
241 313
242 All these processes are called "child processes" (whether they are 314 All these processes are called "child processes" (whether they are
243 direct children or not), while the process that manages them is called 315 direct children or not), while the process that manages them is called
… …
504 my ($fh, $str1, $str2, $fh1, $fh2, $str3) = @_; 576 my ($fh, $str1, $str2, $fh1, $fh2, $str3) = @_;
505 577
506 print scalar <$fh>; # prints "hi #1\n" and "hi #2\n" in any order 578 print scalar <$fh>; # prints "hi #1\n" and "hi #2\n" in any order
507 } 579 }
508 580
581 $proc->to_fh ($cb->($fh)) # EXPERIMENTAL, MIGHT BE REMOVED
582 Flushes all commands out to the process and then calls the callback
583 with the communications socket.
584
585 The process object becomes unusable on return from this function -
586 any further method calls result in undefined behaviour.
587
588 The point of this method is to give you a file handle thta you cna
589 pass to another process. In that other process, you can call
590 "new_from_fh AnyEvent::Fork" to create a new "AnyEvent::Fork" object
591 from it, thereby effectively passing a fork object to another
592 process.
593
594 new_from_fh AnyEvent::Fork $fh # EXPERIMENTAL, MIGHT BE REMOVED
595 Takes a file handle originally rceeived by the "to_fh" method and
596 creates a new "AnyEvent:Fork" object. The child process itself will
597 not change in any way, i.e. it will keep all the modifications done
598 to it before calling "to_fh".
599
600 The new object is very much like the original object, except that
601 the "pid" method will return "undef" even if the process is a direct
602 child.
603
509PERFORMANCE 604PERFORMANCE
510 Now for some unscientific benchmark numbers (all done on an amd64 605 Now for some unscientific benchmark numbers (all done on an amd64
511 GNU/Linux box). These are intended to give you an idea of the relative 606 GNU/Linux box). These are intended to give you an idea of the relative
512 performance you can expect, they are not meant to be absolute 607 performance you can expect, they are not meant to be absolute
513 performance numbers. 608 performance numbers.
… …
519 614
520 2079 new processes per second, using manual socketpair + fork 615 2079 new processes per second, using manual socketpair + fork
521 616
522 Then I did the same thing, but instead of calling fork, I called 617 Then I did the same thing, but instead of calling fork, I called
523 AnyEvent::Fork->new->run ("CORE::exit") and then again waited for the 618 AnyEvent::Fork->new->run ("CORE::exit") and then again waited for the
524 socket form the child to close on exit. This does the same thing as 619 socket from the child to close on exit. This does the same thing as
525 manual socket pair + fork, except that what is forked is the template 620 manual socket pair + fork, except that what is forked is the template
526 process (2440kB), and the socket needs to be passed to the server at the 621 process (2440kB), and the socket needs to be passed to the server at the
527 other end of the socket first. 622 other end of the socket first.
528 623
529 2307 new processes per second, using AnyEvent::Fork->new 624 2307 new processes per second, using AnyEvent::Fork->new
… …
629 and sweat to make it so, mostly due to the bloody broken perl that 724 and sweat to make it so, mostly due to the bloody broken perl that
630 nobody seems to care about. The fork emulation is a bad joke - I have 725 nobody seems to care about. The fork emulation is a bad joke - I have
631 yet to see something useful that you can do with it without running into 726 yet to see something useful that you can do with it without running into
632 memory corruption issues or other braindamage. Hrrrr. 727 memory corruption issues or other braindamage. Hrrrr.
633 728
729 Since fork is endlessly broken on win32 perls (it doesn't even remotely
730 work within it's documented limits) and quite obviously it's not getting
731 improved any time soon, the best way to proceed on windows would be to
732 always use "new_exec" and thus never rely on perl's fork "emulation".
733
634 Cygwin perl is not supported at the moment due to some hilarious 734 Cygwin perl is not supported at the moment due to some hilarious
635 shortcomings of its API - see IO::FDPoll for more details. 735 shortcomings of its API - see IO::FDPoll for more details. If you never
736 use "send_fh" and always use "new_exec" to create processes, it should
737 work though.
636 738
637SEE ALSO 739SEE ALSO
638 AnyEvent::Fork::Early, to avoid executing a perl interpreter at all 740 AnyEvent::Fork::Early, to avoid executing a perl interpreter at all
639 (part of this distribution). 741 (part of this distribution).
640 742
641 AnyEvent::Fork::Template, to create a process by forking the main 743 AnyEvent::Fork::Template, to create a process by forking the main
642 program at a convenient time (part of this distribution). 744 program at a convenient time (part of this distribution).
643 745
644 AnyEvent::Fork::RPC, for simple RPC to child processes (on CPAN). 746 AnyEvent::Fork::RPC, for simple RPC to child processes (on CPAN).
645 747
748 AnyEvent::Fork::Pool, for simple worker process pool (on CPAN).
749
646AUTHOR AND CONTACT INFORMATION 750AUTHOR AND CONTACT INFORMATION
647 Marc Lehmann <schmorp@schmorp.de> 751 Marc Lehmann <schmorp@schmorp.de>
648 http://software.schmorp.de/pkg/AnyEvent-Fork 752 http://software.schmorp.de/pkg/AnyEvent-Fork
649 753

Diff Legend

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