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.11 by root, Thu Nov 10 16:31:03 2016 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
… …
47 AnyEvent::Subprocess. There are modules that implement their own process 51 AnyEvent::Subprocess. There are modules that implement their own process
48 management, such as AnyEvent::DBI. 52 management, such as AnyEvent::DBI.
49 53
50 The problems that all these modules try to solve are real, however, none 54 The problems that all these modules try to solve are real, however, none
51 of them (from what I have seen) tackle the very real problems of 55 of them (from what I have seen) tackle the very real problems of
52 unwanted memory sharing, efficiency, not being able to use event 56 unwanted memory sharing, efficiency or not being able to use event
53 processing or similar modules in the processes they create. 57 processing, GUI toolkits or similar modules in the processes they
58 create.
54 59
55 This module doesn't try to replace any of them - instead it tries to 60 This module doesn't try to replace any of them - instead it tries to
56 solve the problem of creating processes with a minimum of fuss and 61 solve the problem of creating processes with a minimum of fuss and
57 overhead (and also luxury). Ideally, most of these would use 62 overhead (and also luxury). Ideally, most of these would use
58 AnyEvent::Fork internally, except they were written before AnyEvent:Fork 63 AnyEvent::Fork internally, except they were written before AnyEvent:Fork
… …
75 vfork where possible. This gives the speed of vfork, with the 80 vfork where possible. This gives the speed of vfork, with the
76 flexibility of fork. 81 flexibility of fork.
77 82
78 Forking usually creates a copy-on-write copy of the parent process. 83 Forking usually creates a copy-on-write copy of the parent process.
79 For example, modules or data files that are loaded will not use 84 For example, modules or data files that are loaded will not use
80 additional memory after a fork. When exec'ing a new process, modules 85 additional memory after a fork. Exec'ing a new process, in contrast,
81 and data files might need to be loaded again, at extra CPU and 86 means modules and data files might need to be loaded again, at extra
82 memory cost. But when forking, literally all data structures are 87 CPU and memory cost.
88
89 But when forking, you still create a copy of your data structures -
83 copied - if the program frees them and replaces them by new data, 90 if the program frees them and replaces them by new data, the child
84 the child processes will retain the old version even if it isn't 91 processes will retain the old version even if it isn't used, which
85 used, which can suddenly and unexpectedly increase memory usage when 92 can suddenly and unexpectedly increase memory usage when freeing
86 freeing memory. 93 memory.
87 94
95 For example, Gtk2::CV is an image viewer optimised for large
96 directories (millions of pictures). It also forks subprocesses for
97 thumbnail generation, which inherit the data structure that stores
98 all file information. If the user changes the directory, it gets
99 freed in the main process, leaving a copy in the thumbnailer
100 processes. This can lead to many times the memory usage that would
101 actually be required. The solution is to fork early (and being
102 unable to dynamically generate more subprocesses or do this from a
103 module)... or to use <AnyEvent:Fork>.
104
88 The trade-off is between more sharing with fork (which can be good 105 There is a trade-off between more sharing with fork (which can be
89 or bad), and no sharing with exec. 106 good or bad), and no sharing with exec.
90 107
91 This module allows the main program to do a controlled fork, and 108 This module allows the main program to do a controlled fork, and
92 allows modules to exec processes safely at any time. When creating a 109 allows modules to exec processes safely at any time. When creating a
93 custom process pool you can take advantage of data sharing via fork 110 custom process pool you can take advantage of data sharing via fork
94 without risking to share large dynamic data structures that will 111 without risking to share large dynamic data structures that will
… …
97 In other words, this module puts you into control over what is being 114 In other words, this module puts you into control over what is being
98 shared and what isn't, at all times. 115 shared and what isn't, at all times.
99 116
100 Exec'ing a new perl process might be difficult. 117 Exec'ing a new perl process might be difficult.
101 For example, it is not easy to find the correct path to the perl 118 For example, it is not easy to find the correct path to the perl
102 interpreter - $^X might not be a perl interpreter at all. 119 interpreter - $^X might not be a perl interpreter at all. Worse,
120 there might not even be a perl binary installed on the system.
103 121
104 This module tries hard to identify the correct path to the perl 122 This module tries hard to identify the correct path to the perl
105 interpreter. With a cooperative main program, exec'ing the 123 interpreter. With a cooperative main program, exec'ing the
106 interpreter might not even be necessary, but even without help from 124 interpreter might not even be necessary, but even without help from
107 the main program, it will still work when used from a module. 125 the main program, it will still work when used from a module.
… …
112 and modules are no longer loadable because they refer to a different 130 and modules are no longer loadable because they refer to a different
113 perl version, or parts of a distribution are newer than the ones 131 perl version, or parts of a distribution are newer than the ones
114 already loaded. 132 already loaded.
115 133
116 This module supports creating pre-initialised perl processes to be 134 This module supports creating pre-initialised perl processes to be
117 used as a template for new processes. 135 used as a template for new processes at a later time, e.g. for use
136 in a process pool.
118 137
119 Forking might be impossible when a program is running. 138 Forking might be impossible when a program is running.
120 For example, POSIX makes it almost impossible to fork from a 139 For example, POSIX makes it almost impossible to fork from a
121 multi-threaded program while doing anything useful in the child - in 140 multi-threaded program while doing anything useful in the child - in
122 fact, if your perl program uses POSIX threads (even indirectly via 141 fact, if your perl program uses POSIX threads (even indirectly via
123 e.g. IO::AIO or threads), you cannot call fork on the perl level 142 e.g. IO::AIO or threads), you cannot call fork on the perl level
124 anymore without risking corruption issues on a number of operating 143 anymore without risking memory corruption or worse on a number of
125 systems. 144 operating systems.
126 145
127 This module can safely fork helper processes at any time, by calling 146 This module can safely fork helper processes at any time, by calling
128 fork+exec in C, in a POSIX-compatible way (via Proc::FastSpawn). 147 fork+exec in C, in a POSIX-compatible way (via Proc::FastSpawn).
129 148
130 Parallel processing with fork might be inconvenient or difficult to 149 Parallel processing with fork might be inconvenient or difficult to
… …
146 is still safe to do so) - all other processes are created via 165 is still safe to do so) - all other processes are created via
147 fork+exec, which makes it possible to use modules such as event 166 fork+exec, which makes it possible to use modules such as event
148 loops or window interfaces safely. 167 loops or window interfaces safely.
149 168
150EXAMPLES 169EXAMPLES
170 This is where the wall of text ends and code speaks.
171
151 Create a single new process, tell it to run your worker function. 172 Create a single new process, tell it to run your worker function.
152 AnyEvent::Fork 173 AnyEvent::Fork
153 ->new 174 ->new
154 ->require ("MyModule") 175 ->require ("MyModule")
155 ->run ("MyModule::worker, sub { 176 ->run ("MyModule::worker, sub {
… …
165 186
166 sub worker { 187 sub worker {
167 my ($slave_filehandle) = @_; 188 my ($slave_filehandle) = @_;
168 189
169 # now $slave_filehandle is connected to the $master_filehandle 190 # now $slave_filehandle is connected to the $master_filehandle
170 # in the original prorcess. have fun! 191 # in the original process. have fun!
171 } 192 }
172 193
173 Create a pool of server processes all accepting on the same socket. 194 Create a pool of server processes all accepting on the same socket.
174 # create listener socket 195 # create listener socket
175 my $listener = ...; 196 my $listener = ...;
… …
233 ->send_arg ("/bin/echo", "hi") 254 ->send_arg ("/bin/echo", "hi")
234 ->run ("run", my $cv = AE::cv); 255 ->run ("run", my $cv = AE::cv);
235 256
236 my $stderr = $cv->recv; 257 my $stderr = $cv->recv;
237 258
259 For stingy users: put the worker code into a "DATA" section.
260 When you want to be stingy with files, you can put your code into the
261 "DATA" section of your module (or program):
262
263 use AnyEvent::Fork;
264
265 AnyEvent::Fork
266 ->new
267 ->eval (do { local $/; <DATA> })
268 ->run ("doit", sub { ... });
269
270 __DATA__
271
272 sub doit {
273 ... do something!
274 }
275
276 For stingy standalone programs: do not rely on external files at
277all.
278 For single-file scripts it can be inconvenient to rely on external files
279 - even when using a "DATA" section, you still need to "exec" an external
280 perl interpreter, which might not be available when using
281 App::Staticperl, Urlader or PAR::Packer for example.
282
283 Two modules help here - AnyEvent::Fork::Early forks a template process
284 for all further calls to "new_exec", and AnyEvent::Fork::Template forks
285 the main program as a template process.
286
287 Here is how your main program should look like:
288
289 #! perl
290
291 # optional, as the very first thing.
292 # in case modules want to create their own processes.
293 use AnyEvent::Fork::Early;
294
295 # next, load all modules you need in your template process
296 use Example::My::Module
297 use Example::Whatever;
298
299 # next, put your run function definition and anything else you
300 # need, but do not use code outside of BEGIN blocks.
301 sub worker_run {
302 my ($fh, @args) = @_;
303 ...
304 }
305
306 # now preserve everything so far as AnyEvent::Fork object
307 # in $TEMPLATE.
308 use AnyEvent::Fork::Template;
309
310 # do not put code outside of BEGIN blocks until here
311
312 # now use the $TEMPLATE process in any way you like
313
314 # for example: create 10 worker processes
315 my @worker;
316 my $cv = AE::cv;
317 for (1..10) {
318 $cv->begin;
319 $TEMPLATE->fork->send_arg ($_)->run ("worker_run", sub {
320 push @worker, shift;
321 $cv->end;
322 });
323 }
324 $cv->recv;
325
238CONCEPTS 326CONCEPTS
239 This module can create new processes either by executing a new perl 327 This module can create new processes either by executing a new perl
240 process, or by forking from an existing "template" process. 328 process, or by forking from an existing "template" process.
241 329
242 All these processes are called "child processes" (whether they are 330 All these processes are called "child processes" (whether they are
… …
368 You should use "new" whenever possible, except when having a 456 You should use "new" whenever possible, except when having a
369 template process around is unacceptable. 457 template process around is unacceptable.
370 458
371 The path to the perl interpreter is divined using various methods - 459 The path to the perl interpreter is divined using various methods -
372 first $^X is investigated to see if the path ends with something 460 first $^X is investigated to see if the path ends with something
373 that sounds as if it were the perl interpreter. Failing this, the 461 that looks as if it were the perl interpreter. Failing this, the
374 module falls back to using $Config::Config{perlpath}. 462 module falls back to using $Config::Config{perlpath}.
463
464 The path to perl can also be overriden by setting the global
465 variable $AnyEvent::Fork::PERL - it's value will be used for all
466 subsequent invocations.
375 467
376 $pid = $proc->pid 468 $pid = $proc->pid
377 Returns the process id of the process *iff it is a direct child of 469 Returns the process id of the process *iff it is a direct child of
378 the process running AnyEvent::Fork*, and "undef" otherwise. 470 the process running AnyEvent::Fork*, and "undef" otherwise. As a
471 general rule (that you cannot rely upon), processes created via
472 "new_exec", AnyEvent::Fork::Early or AnyEvent::Fork::Template are
473 direct children, while all other processes are not.
379 474
380 Normally, only processes created via "AnyEvent::Fork->new_exec" and 475 Or in other words, you do not normally have to take care of zombies
381 AnyEvent::Fork::Template are direct children, and you are 476 for processes created via "new", but when in doubt, or zombies are a
382 responsible to clean up their zombies when they die. 477 problem, you need to check whether a process is a diretc child by
383 478 calling this method, and possibly creating a child watcher or reap
384 All other processes are not direct children, and will be cleaned up 479 it manually.
385 by AnyEvent::Fork itself.
386 480
387 $proc = $proc->eval ($perlcode, @args) 481 $proc = $proc->eval ($perlcode, @args)
388 Evaluates the given $perlcode as ... Perl code, while setting @_ to 482 Evaluates the given $perlcode as ... Perl code, while setting @_ to
389 the strings specified by @args, in the "main" package. 483 the strings specified by @args, in the "main" package.
390 484
… …
405 See the "use AnyEvent::Fork as a faster fork+exec" example to see it 499 See the "use AnyEvent::Fork as a faster fork+exec" example to see it
406 in action. 500 in action.
407 501
408 Returns the process object for easy chaining of method calls. 502 Returns the process object for easy chaining of method calls.
409 503
504 It's common to want to call an iniitalisation function with some
505 arguments. Make sure you actually pass @_ to that function (for
506 example by using &name syntax), and do not just specify a function
507 name:
508
509 $proc->eval ('&MyModule::init', $string1, $string2);
510
410 $proc = $proc->require ($module, ...) 511 $proc = $proc->require ($module, ...)
411 Tries to load the given module(s) into the process 512 Tries to load the given module(s) into the process
412 513
413 Returns the process object for easy chaining of method calls. 514 Returns the process object for easy chaining of method calls.
414 515
… …
472 Even if not used otherwise, the socket can be a good indicator for 573 Even if not used otherwise, the socket can be a good indicator for
473 the existence of the process - if the other process exits, you get a 574 the existence of the process - if the other process exits, you get a
474 readable event on it, because exiting the process closes the socket 575 readable event on it, because exiting the process closes the socket
475 (if it didn't create any children using fork). 576 (if it didn't create any children using fork).
476 577
578 Compatibility to AnyEvent::Fork::Remote
579 If you want to write code that works with both this module and
580 AnyEvent::Fork::Remote, you need to write your code so that it
581 assumes there are two file handles for communications, which
582 might not be unix domain sockets. The "run" function should
583 start like this:
584
585 sub run {
586 my ($rfh, @args) = @_; # @args is your normal arguments
587 my $wfh = fileno $rfh ? $rfh : *STDOUT;
588
589 # now use $rfh for reading and $wfh for writing
590 }
591
592 This checks whether the passed file handle is, in fact, the
593 process "STDIN" handle. If it is, then the function was invoked
594 visa AnyEvent::Fork::Remote, so STDIN should be used for reading
595 and "STDOUT" should be used for writing.
596
597 In all other cases, the function was called via this module, and
598 there is only one file handle that should be sued for reading
599 and writing.
600
477 Example: create a template for a process pool, pass a few strings, 601 Example: create a template for a process pool, pass a few strings,
478 some file handles, then fork, pass one more string, and run some 602 some file handles, then fork, pass one more string, and run some
479 code. 603 code.
480 604
481 my $pool = AnyEvent::Fork 605 my $pool = AnyEvent::Fork
… …
504 my ($fh, $str1, $str2, $fh1, $fh2, $str3) = @_; 628 my ($fh, $str1, $str2, $fh1, $fh2, $str3) = @_;
505 629
506 print scalar <$fh>; # prints "hi #1\n" and "hi #2\n" in any order 630 print scalar <$fh>; # prints "hi #1\n" and "hi #2\n" in any order
507 } 631 }
508 632
633 CHILD PROCESS INTERFACE
634 This module has a limited API for use in child processes.
635
636 @args = AnyEvent::Fork::Serve::run_args
637 This function, which only exists before the "run" method is called,
638 returns the arguments that would be passed to the run function, and
639 clears them.
640
641 This is mainly useful to get any file handles passed via "send_fh",
642 but works for any arguments passed via "send_*xxx*" methods.
643
644 EXPERIMENTAL METHODS
645 These methods might go away completely or change behaviour, at any time.
646
647 $proc->to_fh ($cb->($fh)) # EXPERIMENTAL, MIGHT BE REMOVED
648 Flushes all commands out to the process and then calls the callback
649 with the communications socket.
650
651 The process object becomes unusable on return from this function -
652 any further method calls result in undefined behaviour.
653
654 The point of this method is to give you a file handle that you can
655 pass to another process. In that other process, you can call
656 "new_from_fh AnyEvent::Fork $fh" to create a new "AnyEvent::Fork"
657 object from it, thereby effectively passing a fork object to another
658 process.
659
660 new_from_fh AnyEvent::Fork $fh # EXPERIMENTAL, MIGHT BE REMOVED
661 Takes a file handle originally rceeived by the "to_fh" method and
662 creates a new "AnyEvent:Fork" object. The child process itself will
663 not change in any way, i.e. it will keep all the modifications done
664 to it before calling "to_fh".
665
666 The new object is very much like the original object, except that
667 the "pid" method will return "undef" even if the process is a direct
668 child.
669
509PERFORMANCE 670PERFORMANCE
510 Now for some unscientific benchmark numbers (all done on an amd64 671 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 672 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 673 performance you can expect, they are not meant to be absolute
513 performance numbers. 674 performance numbers.
… …
519 680
520 2079 new processes per second, using manual socketpair + fork 681 2079 new processes per second, using manual socketpair + fork
521 682
522 Then I did the same thing, but instead of calling fork, I called 683 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 684 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 685 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 686 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 687 process (2440kB), and the socket needs to be passed to the server at the
527 other end of the socket first. 688 other end of the socket first.
528 689
529 2307 new processes per second, using AnyEvent::Fork->new 690 2307 new processes per second, using AnyEvent::Fork->new
… …
629 and sweat to make it so, mostly due to the bloody broken perl that 790 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 791 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 792 yet to see something useful that you can do with it without running into
632 memory corruption issues or other braindamage. Hrrrr. 793 memory corruption issues or other braindamage. Hrrrr.
633 794
795 Since fork is endlessly broken on win32 perls (it doesn't even remotely
796 work within it's documented limits) and quite obviously it's not getting
797 improved any time soon, the best way to proceed on windows would be to
798 always use "new_exec" and thus never rely on perl's fork "emulation".
799
634 Cygwin perl is not supported at the moment due to some hilarious 800 Cygwin perl is not supported at the moment due to some hilarious
635 shortcomings of its API - see IO::FDPoll for more details. 801 shortcomings of its API - see IO::FDPoll for more details. If you never
802 use "send_fh" and always use "new_exec" to create processes, it should
803 work though.
804
805USING AnyEvent::Fork IN SUBPROCESSES
806 AnyEvent::Fork itself cannot generally be used in subprocesses. As long
807 as only one process ever forks new processes, sharing the template
808 processes is possible (you could use a pipe as a lock by writing a byte
809 into it to unlock, and reading the byte to lock for example)
810
811 To make concurrent calls possible after fork, you should get rid of the
812 template and early fork processes. AnyEvent::Fork will create a new
813 template process as needed.
814
815 undef $AnyEvent::Fork::EARLY;
816 undef $AnyEvent::Fork::TEMPLATE;
817
818 It doesn't matter whether you get rid of them in the parent or child
819 after a fork.
636 820
637SEE ALSO 821SEE ALSO
638 AnyEvent::Fork::Early, to avoid executing a perl interpreter at all 822 AnyEvent::Fork::Early, to avoid executing a perl interpreter at all
639 (part of this distribution). 823 (part of this distribution).
640 824
641 AnyEvent::Fork::Template, to create a process by forking the main 825 AnyEvent::Fork::Template, to create a process by forking the main
642 program at a convenient time (part of this distribution). 826 program at a convenient time (part of this distribution).
643 827
828 AnyEvent::Fork::Remote, for another way to create processes that is
829 mostly compatible to this module and modules building on top of it, but
830 works better with remote processes.
831
644 AnyEvent::Fork::RPC, for simple RPC to child processes (on CPAN). 832 AnyEvent::Fork::RPC, for simple RPC to child processes (on CPAN).
833
834 AnyEvent::Fork::Pool, for simple worker process pool (on CPAN).
645 835
646AUTHOR AND CONTACT INFORMATION 836AUTHOR AND CONTACT INFORMATION
647 Marc Lehmann <schmorp@schmorp.de> 837 Marc Lehmann <schmorp@schmorp.de>
648 http://software.schmorp.de/pkg/AnyEvent-Fork 838 http://software.schmorp.de/pkg/AnyEvent-Fork
649 839

Diff Legend

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