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.12 by root, Wed Jan 26 16:44:16 2022 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 overridden 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 (so you can
484 access the args using $_[0] and so on, but not using implicit "shit"
485 as the latter works on @ARGV).
390 486
391 This call is meant to do any custom initialisation that might be 487 This call is meant to do any custom initialisation that might be
392 required (for example, the "require" method uses it). It's not 488 required (for example, the "require" method uses it). It's not
393 supposed to be used to completely take over the process, use "run" 489 supposed to be used to completely take over the process, use "run"
394 for that. 490 for that.
… …
405 See the "use AnyEvent::Fork as a faster fork+exec" example to see it 501 See the "use AnyEvent::Fork as a faster fork+exec" example to see it
406 in action. 502 in action.
407 503
408 Returns the process object for easy chaining of method calls. 504 Returns the process object for easy chaining of method calls.
409 505
506 It's common to want to call an iniitalisation function with some
507 arguments. Make sure you actually pass @_ to that function (for
508 example by using &name syntax), and do not just specify a function
509 name:
510
511 $proc->eval ('&MyModule::init', $string1, $string2);
512
410 $proc = $proc->require ($module, ...) 513 $proc = $proc->require ($module, ...)
411 Tries to load the given module(s) into the process 514 Tries to load the given module(s) into the process
412 515
413 Returns the process object for easy chaining of method calls. 516 Returns the process object for easy chaining of method calls.
414 517
… …
472 Even if not used otherwise, the socket can be a good indicator for 575 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 576 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 577 readable event on it, because exiting the process closes the socket
475 (if it didn't create any children using fork). 578 (if it didn't create any children using fork).
476 579
580 Compatibility to AnyEvent::Fork::Remote
581 If you want to write code that works with both this module and
582 AnyEvent::Fork::Remote, you need to write your code so that it
583 assumes there are two file handles for communications, which
584 might not be unix domain sockets. The "run" function should
585 start like this:
586
587 sub run {
588 my ($rfh, @args) = @_; # @args is your normal arguments
589 my $wfh = fileno $rfh ? $rfh : *STDOUT;
590
591 # now use $rfh for reading and $wfh for writing
592 }
593
594 This checks whether the passed file handle is, in fact, the
595 process "STDIN" handle. If it is, then the function was invoked
596 visa AnyEvent::Fork::Remote, so STDIN should be used for reading
597 and "STDOUT" should be used for writing.
598
599 In all other cases, the function was called via this module, and
600 there is only one file handle that should be sued for reading
601 and writing.
602
477 Example: create a template for a process pool, pass a few strings, 603 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 604 some file handles, then fork, pass one more string, and run some
479 code. 605 code.
480 606
481 my $pool = AnyEvent::Fork 607 my $pool = AnyEvent::Fork
… …
504 my ($fh, $str1, $str2, $fh1, $fh2, $str3) = @_; 630 my ($fh, $str1, $str2, $fh1, $fh2, $str3) = @_;
505 631
506 print scalar <$fh>; # prints "hi #1\n" and "hi #2\n" in any order 632 print scalar <$fh>; # prints "hi #1\n" and "hi #2\n" in any order
507 } 633 }
508 634
635 CHILD PROCESS INTERFACE
636 This module has a limited API for use in child processes.
637
638 @args = AnyEvent::Fork::Serve::run_args
639 This function, which only exists before the "run" method is called,
640 returns the arguments that would be passed to the run function, and
641 clears them.
642
643 This is mainly useful to get any file handles passed via "send_fh",
644 but works for any arguments passed via "send_*xxx*" methods.
645
646 EXPERIMENTAL METHODS
647 These methods might go away completely or change behaviour, at any time.
648
649 $proc->to_fh ($cb->($fh)) # EXPERIMENTAL, MIGHT BE REMOVED
650 Flushes all commands out to the process and then calls the callback
651 with the communications socket.
652
653 The process object becomes unusable on return from this function -
654 any further method calls result in undefined behaviour.
655
656 The point of this method is to give you a file handle that you can
657 pass to another process. In that other process, you can call
658 "new_from_fh AnyEvent::Fork $fh" to create a new "AnyEvent::Fork"
659 object from it, thereby effectively passing a fork object to another
660 process.
661
662 new_from_fh AnyEvent::Fork $fh # EXPERIMENTAL, MIGHT BE REMOVED
663 Takes a file handle originally rceeived by the "to_fh" method and
664 creates a new "AnyEvent:Fork" object. The child process itself will
665 not change in any way, i.e. it will keep all the modifications done
666 to it before calling "to_fh".
667
668 The new object is very much like the original object, except that
669 the "pid" method will return "undef" even if the process is a direct
670 child.
671
509PERFORMANCE 672PERFORMANCE
510 Now for some unscientific benchmark numbers (all done on an amd64 673 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 674 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 675 performance you can expect, they are not meant to be absolute
513 performance numbers. 676 performance numbers.
… …
519 682
520 2079 new processes per second, using manual socketpair + fork 683 2079 new processes per second, using manual socketpair + fork
521 684
522 Then I did the same thing, but instead of calling fork, I called 685 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 686 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 687 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 688 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 689 process (2440kB), and the socket needs to be passed to the server at the
527 other end of the socket first. 690 other end of the socket first.
528 691
529 2307 new processes per second, using AnyEvent::Fork->new 692 2307 new processes per second, using AnyEvent::Fork->new
… …
629 and sweat to make it so, mostly due to the bloody broken perl that 792 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 793 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 794 yet to see something useful that you can do with it without running into
632 memory corruption issues or other braindamage. Hrrrr. 795 memory corruption issues or other braindamage. Hrrrr.
633 796
797 Since fork is endlessly broken on win32 perls (it doesn't even remotely
798 work within it's documented limits) and quite obviously it's not getting
799 improved any time soon, the best way to proceed on windows would be to
800 always use "new_exec" and thus never rely on perl's fork "emulation".
801
634 Cygwin perl is not supported at the moment due to some hilarious 802 Cygwin perl is not supported at the moment due to some hilarious
635 shortcomings of its API - see IO::FDPoll for more details. 803 shortcomings of its API - see IO::FDPoll for more details. If you never
804 use "send_fh" and always use "new_exec" to create processes, it should
805 work though.
806
807USING AnyEvent::Fork IN SUBPROCESSES
808 AnyEvent::Fork itself cannot generally be used in subprocesses. As long
809 as only one process ever forks new processes, sharing the template
810 processes is possible (you could use a pipe as a lock by writing a byte
811 into it to unlock, and reading the byte to lock for example)
812
813 To make concurrent calls possible after fork, you should get rid of the
814 template and early fork processes. AnyEvent::Fork will create a new
815 template process as needed.
816
817 undef $AnyEvent::Fork::EARLY;
818 undef $AnyEvent::Fork::TEMPLATE;
819
820 It doesn't matter whether you get rid of them in the parent or child
821 after a fork.
636 822
637SEE ALSO 823SEE ALSO
638 AnyEvent::Fork::Early, to avoid executing a perl interpreter at all 824 AnyEvent::Fork::Early, to avoid executing a perl interpreter at all
639 (part of this distribution). 825 (part of this distribution).
640 826
641 AnyEvent::Fork::Template, to create a process by forking the main 827 AnyEvent::Fork::Template, to create a process by forking the main
642 program at a convenient time (part of this distribution). 828 program at a convenient time (part of this distribution).
643 829
830 AnyEvent::Fork::Remote, for another way to create processes that is
831 mostly compatible to this module and modules building on top of it, but
832 works better with remote processes.
833
644 AnyEvent::Fork::RPC, for simple RPC to child processes (on CPAN). 834 AnyEvent::Fork::RPC, for simple RPC to child processes (on CPAN).
835
836 AnyEvent::Fork::Pool, for simple worker process pool (on CPAN).
645 837
646AUTHOR AND CONTACT INFORMATION 838AUTHOR AND CONTACT INFORMATION
647 Marc Lehmann <schmorp@schmorp.de> 839 Marc Lehmann <schmorp@schmorp.de>
648 http://software.schmorp.de/pkg/AnyEvent-Fork 840 http://software.schmorp.de/pkg/AnyEvent-Fork
649 841

Diff Legend

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