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

Comparing AnyEvent-Fork/README (file contents):
Revision 1.5 by root, Sat Apr 6 22:41:56 2013 UTC vs.
Revision 1.6 by root, Thu Apr 18 20:17:35 2013 UTC

… …
30 This module only creates processes and lets you pass file handles and 30 This module only creates processes and lets you pass file handles and
31 strings to it, and run perl code. It does not implement any kind of RPC 31 strings to it, and run perl code. It does not implement any kind of RPC
32 - there is no back channel from the process back to you, and there is no 32 - there is no back channel from the process back to you, and there is no
33 RPC or message passing going on. 33 RPC or message passing going on.
34 34
35 If you need some form of RPC, you can either implement it yourself in 35 If you need some form of RPC, you could use the AnyEvent::Fork::RPC
36 whatever way you like, use some message-passing module such as 36 companion module, which adds simple RPC/job queueing to a process
37 AnyEvent::MP, some pipe such as AnyEvent::ZeroMQ, use AnyEvent::Handle 37 created by this module.
38 on both sides to send e.g. JSON or Storable messages, and so on. 38
39 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
41 AnyEvent::ZeroMQ, use AnyEvent::Handle on both sides to send e.g. JSON
42 or Storable messages, and so on.
39 43
40 COMPARISON TO OTHER MODULES 44 COMPARISON TO OTHER MODULES
41 There is an abundance of modules on CPAN that do "something fork", such 45 There is an abundance of modules on CPAN that do "something fork", such
42 as Parallel::ForkManager, AnyEvent::ForkManager, AnyEvent::Worker or 46 as Parallel::ForkManager, AnyEvent::ForkManager, AnyEvent::Worker or
43 AnyEvent::Subprocess. There are modules that implement their own process 47 AnyEvent::Subprocess. There are modules that implement their own process
… …
202 # do sth. with new socket 206 # do sth. with new socket
203 } 207 }
204 } 208 }
205 209
206 use AnyEvent::Fork as a faster fork+exec 210 use AnyEvent::Fork as a faster fork+exec
207 This runs "/bin/echo hi", with stdandard output redirected to /tmp/log 211 This runs "/bin/echo hi", with standard output redirected to /tmp/log
208 and standard error redirected to the communications socket. It is 212 and standard error redirected to the communications socket. It is
209 usually faster than fork+exec, but still lets you prepare the 213 usually faster than fork+exec, but still lets you prepare the
210 environment. 214 environment.
211 215
212 open my $output, ">/tmp/log" or die "$!"; 216 open my $output, ">/tmp/log" or die "$!";
… …
232 my $stderr = $cv->recv; 236 my $stderr = $cv->recv;
233 237
234CONCEPTS 238CONCEPTS
235 This module can create new processes either by executing a new perl 239 This module can create new processes either by executing a new perl
236 process, or by forking from an existing "template" process. 240 process, or by forking from an existing "template" process.
241
242 All these processes are called "child processes" (whether they are
243 direct children or not), while the process that manages them is called
244 the "parent process".
237 245
238 Each such process comes with its own file handle that can be used to 246 Each such process comes with its own file handle that can be used to
239 communicate with it (it's actually a socket - one end in the new 247 communicate with it (it's actually a socket - one end in the new
240 process, one end in the main process), and among the things you can do 248 process, one end in the main process), and among the things you can do
241 in it are load modules, fork new processes, send file handles to it, and 249 in it are load modules, fork new processes, send file handles to it, and
… …
329 337
330 As long as there is any outstanding work to be done, process objects 338 As long as there is any outstanding work to be done, process objects
331 resist being destroyed, so there is no reason to store them unless you 339 resist being destroyed, so there is no reason to store them unless you
332 need them later - configure and forget works just fine. 340 need them later - configure and forget works just fine.
333 341
334 my $proc = new AnyEvent::Fork 342 my $proc = new AnyEvent::Fork
335
336 Create a new "empty" perl interpreter process and returns its 343 Create a new "empty" perl interpreter process and returns its
337 process object for further manipulation. 344 process object for further manipulation.
338 345
339 The new process is forked from a template process that is kept 346 The new process is forked from a template process that is kept
340 around for this purpose. When it doesn't exist yet, it is created by 347 around for this purpose. When it doesn't exist yet, it is created by
341 a call to "new_exec" first and then stays around for future calls. 348 a call to "new_exec" first and then stays around for future calls.
342 349
343 $new_proc = $proc->fork 350 $new_proc = $proc->fork
344
345 Forks $proc, creating a new process, and returns the process object 351 Forks $proc, creating a new process, and returns the process object
346 of the new process. 352 of the new process.
347 353
348 If any of the "send_" functions have been called before fork, then 354 If any of the "send_" functions have been called before fork, then
349 they will be cloned in the child. For example, in a pre-forked 355 they will be cloned in the child. For example, in a pre-forked
350 server, you might "send_fh" the listening socket into the template 356 server, you might "send_fh" the listening socket into the template
351 process, and then keep calling "fork" and "run". 357 process, and then keep calling "fork" and "run".
352 358
353 my $proc = new_exec AnyEvent::Fork 359 my $proc = new_exec AnyEvent::Fork
354
355 Create a new "empty" perl interpreter process and returns its 360 Create a new "empty" perl interpreter process and returns its
356 process object for further manipulation. 361 process object for further manipulation.
357 362
358 Unlike the "new" method, this method *always* spawns a new perl 363 Unlike the "new" method, this method *always* spawns a new perl
359 process (except in some cases, see AnyEvent::Fork::Early for 364 process (except in some cases, see AnyEvent::Fork::Early for
… …
366 The path to the perl interpreter is divined using various methods - 371 The path to the perl interpreter is divined using various methods -
367 first $^X is investigated to see if the path ends with something 372 first $^X is investigated to see if the path ends with something
368 that sounds as if it were the perl interpreter. Failing this, the 373 that sounds as if it were the perl interpreter. Failing this, the
369 module falls back to using $Config::Config{perlpath}. 374 module falls back to using $Config::Config{perlpath}.
370 375
371 $pid = $proc->pid 376 $pid = $proc->pid
372
373 Returns the process id of the process *iff it is a direct child of 377 Returns the process id of the process *iff it is a direct child of
374 the process running AnyEvent::Fork*, and "undef" otherwise. 378 the process running AnyEvent::Fork*, and "undef" otherwise.
375 379
376 Normally, only processes created via "AnyEvent::Fork->new_exec" and 380 Normally, only processes created via "AnyEvent::Fork->new_exec" and
377 AnyEvent::Fork::Template are direct children, and you are 381 AnyEvent::Fork::Template are direct children, and you are
378 responsible to clean up their zombies when they die. 382 responsible to clean up their zombies when they die.
379 383
380 All other processes are not direct children, and will be cleaned up 384 All other processes are not direct children, and will be cleaned up
381 by AnyEvent::Fork itself. 385 by AnyEvent::Fork itself.
382 386
383 $proc = $proc->eval ($perlcode, @args) 387 $proc = $proc->eval ($perlcode, @args)
384
385 Evaluates the given $perlcode as ... perl code, while setting @_ to 388 Evaluates the given $perlcode as ... Perl code, while setting @_ to
386 the strings specified by @args, in the "main" package. 389 the strings specified by @args, in the "main" package.
387 390
388 This call is meant to do any custom initialisation that might be 391 This call is meant to do any custom initialisation that might be
389 required (for example, the "require" method uses it). It's not 392 required (for example, the "require" method uses it). It's not
390 supposed to be used to completely take over the process, use "run" 393 supposed to be used to completely take over the process, use "run"
… …
402 See the "use AnyEvent::Fork as a faster fork+exec" example to see it 405 See the "use AnyEvent::Fork as a faster fork+exec" example to see it
403 in action. 406 in action.
404 407
405 Returns the process object for easy chaining of method calls. 408 Returns the process object for easy chaining of method calls.
406 409
407 $proc = $proc->require ($module, ...) 410 $proc = $proc->require ($module, ...)
408
409 Tries to load the given module(s) into the process 411 Tries to load the given module(s) into the process
410 412
411 Returns the process object for easy chaining of method calls. 413 Returns the process object for easy chaining of method calls.
412 414
413 $proc = $proc->send_fh ($handle, ...) 415 $proc = $proc->send_fh ($handle, ...)
414
415 Send one or more file handles (*not* file descriptors) to the 416 Send one or more file handles (*not* file descriptors) to the
416 process, to prepare a call to "run". 417 process, to prepare a call to "run".
417 418
418 The process object keeps a reference to the handles until they have 419 The process object keeps a reference to the handles until they have
419 been passed over to the process, so you must not explicitly close 420 been passed over to the process, so you must not explicitly close
… …
428 closing. It will be closed automatically when it is no longer used. 429 closing. It will be closed automatically when it is no longer used.
429 430
430 $proc->send_fh ($my_fh); 431 $proc->send_fh ($my_fh);
431 undef $my_fh; # free the reference if you want, but DO NOT CLOSE IT 432 undef $my_fh; # free the reference if you want, but DO NOT CLOSE IT
432 433
433 $proc = $proc->send_arg ($string, ...) 434 $proc = $proc->send_arg ($string, ...)
434
435 Send one or more argument strings to the process, to prepare a call 435 Send one or more argument strings to the process, to prepare a call
436 to "run". The strings can be any octet strings. 436 to "run". The strings can be any octet strings.
437 437
438 The protocol is optimised to pass a moderate number of relatively 438 The protocol is optimised to pass a moderate number of relatively
439 short strings - while you can pass up to 4GB of data in one go, this 439 short strings - while you can pass up to 4GB of data in one go, this
440 is more meant to pass some ID information or other startup info, not 440 is more meant to pass some ID information or other startup info, not
441 big chunks of data. 441 big chunks of data.
442 442
443 Returns the process object for easy chaining of method calls. 443 Returns the process object for easy chaining of method calls.
444 444
445 $proc->run ($func, $cb->($fh)) 445 $proc->run ($func, $cb->($fh))
446
447 Enter the function specified by the function name in $func in the 446 Enter the function specified by the function name in $func in the
448 process. The function is called with the communication socket as 447 process. The function is called with the communication socket as
449 first argument, followed by all file handles and string arguments 448 first argument, followed by all file handles and string arguments
450 sent earlier via "send_fh" and "send_arg" methods, in the order they 449 sent earlier via "send_fh" and "send_arg" methods, in the order they
451 were called. 450 were called.
… …
537 So how can "AnyEvent->new" be faster than a standard fork, even though 536 So how can "AnyEvent->new" be faster than a standard fork, even though
538 it uses the same operations, but adds a lot of overhead? 537 it uses the same operations, but adds a lot of overhead?
539 538
540 The difference is simply the process size: forking the 5MB process takes 539 The difference is simply the process size: forking the 5MB process takes
541 so much longer than forking the 2.5MB template process that the extra 540 so much longer than forking the 2.5MB template process that the extra
542 overhead introduced is canceled out. 541 overhead is canceled out.
543 542
544 If the benchmark process grows, the normal fork becomes even slower: 543 If the benchmark process grows, the normal fork becomes even slower:
545 544
546 1340 new processes, manual fork of a 20MB process 545 1340 new processes, manual fork of a 20MB process
547 731 new processes, manual fork of a 200MB process 546 731 new processes, manual fork of a 200MB process
… …
603 AnyEvent::Fork::Early or AnyEvent::Fork::Template, or to delay 602 AnyEvent::Fork::Early or AnyEvent::Fork::Template, or to delay
604 initialising them, for example, by calling "init Gtk2" manually. 603 initialising them, for example, by calling "init Gtk2" manually.
605 604
606 exiting calls object destructors 605 exiting calls object destructors
607 This only applies to users of AnyEvent::Fork:Early and 606 This only applies to users of AnyEvent::Fork:Early and
608 AnyEvent::Fork::Template, or when initialiasing code creates objects 607 AnyEvent::Fork::Template, or when initialising code creates objects
609 that reference external resources. 608 that reference external resources.
610 609
611 When a process created by AnyEvent::Fork exits, it might do so by 610 When a process created by AnyEvent::Fork exits, it might do so by
612 calling exit, or simply letting perl reach the end of the program. 611 calling exit, or simply letting perl reach the end of the program.
613 At which point Perl runs all destructors. 612 At which point Perl runs all destructors.
… …
634 633
635 Cygwin perl is not supported at the moment due to some hilarious 634 Cygwin perl is not supported at the moment due to some hilarious
636 shortcomings of its API - see IO::FDPoll for more details. 635 shortcomings of its API - see IO::FDPoll for more details.
637 636
638SEE ALSO 637SEE ALSO
639 AnyEvent::Fork::Early (to avoid executing a perl interpreter), 638 AnyEvent::Fork::Early, to avoid executing a perl interpreter at all
639 (part of this distribution).
640
640 AnyEvent::Fork::Template (to create a process by forking the main 641 AnyEvent::Fork::Template, to create a process by forking the main
641 program at a convenient time). 642 program at a convenient time (part of this distribution).
642 643
643AUTHOR 644 AnyEvent::Fork::RPC, for simple RPC to child processes (on CPAN).
645
646AUTHOR AND CONTACT INFORMATION
644 Marc Lehmann <schmorp@schmorp.de> 647 Marc Lehmann <schmorp@schmorp.de>
645 http://home.schmorp.de/ 648 http://software.schmorp.de/pkg/AnyEvent-Fork
646 649
647POD ERRORS
648 Hey! The above document had some coding errors, which are explained
649 below:
650
651 Around line 360:
652 You can't have =items (as at line 476) unless the first thing after
653 the =over is an =item
654

Diff Legend

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