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.46 by root, Thu Apr 18 11:18:23 2013 UTC vs.
Revision 1.54 by root, Fri Apr 26 17:24:05 2013 UTC

… …
38 38
39If you need some form of RPC, you could use the L<AnyEvent::Fork::RPC> 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 40companion module, which adds simple RPC/job queueing to a process created
41by this module. 41by this module.
42 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
43Or you can implement it yourself in whatever way you like, use some 47Or you can implement it yourself in whatever way you like: use some
44message-passing module such as L<AnyEvent::MP>, some pipe such as 48message-passing module such as L<AnyEvent::MP>, some pipe such as
45L<AnyEvent::ZeroMQ>, use L<AnyEvent::Handle> on both sides to send 49L<AnyEvent::ZeroMQ>, use L<AnyEvent::Handle> on both sides to send
46e.g. JSON or Storable messages, and so on. 50e.g. JSON or Storable messages, and so on.
47 51
48=head2 COMPARISON TO OTHER MODULES 52=head2 COMPARISON TO OTHER MODULES
… …
250 ->send_arg ("/bin/echo", "hi") 254 ->send_arg ("/bin/echo", "hi")
251 ->run ("run", my $cv = AE::cv); 255 ->run ("run", my $cv = AE::cv);
252 256
253 my $stderr = $cv->recv; 257 my $stderr = $cv->recv;
254 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;
327
255=head1 CONCEPTS 328=head1 CONCEPTS
256 329
257This module can create new processes either by executing a new perl 330This module can create new processes either by executing a new perl
258process, or by forking from an existing "template" process. 331process, or by forking from an existing "template" process.
259 332
… …
377use AnyEvent; 450use AnyEvent;
378use AnyEvent::Util (); 451use AnyEvent::Util ();
379 452
380use IO::FDPass; 453use IO::FDPass;
381 454
382our $VERSION = 0.6; 455our $VERSION = '1.0';
383 456
384# the early fork template process 457# the early fork template process
385our $EARLY; 458our $EARLY;
386 459
387# the empty template process 460# the empty template process
… …
412 my $self = shift; 485 my $self = shift;
413 486
414 # ideally, we would want to use "a (w/a)*" as format string, but perl 487 # ideally, we would want to use "a (w/a)*" as format string, but perl
415 # versions from at least 5.8.9 to 5.16.3 are all buggy and can't unpack 488 # versions from at least 5.8.9 to 5.16.3 are all buggy and can't unpack
416 # it. 489 # it.
417 push @{ $self->[QUEUE] }, pack "a L/a*", $_[0], $_[1]; 490 push @{ $self->[QUEUE] }, pack "a N/a*", $_[0], $_[1];
418 491
419 $self->[WW] ||= AE::io $self->[FH], 1, sub { 492 $self->[WW] ||= AE::io $self->[FH], 1, sub {
420 do { 493 do {
421 # send the next "thing" in the queue - either a reference to an fh, 494 # send the next "thing" in the queue - either a reference to an fh,
422 # or a plain string. 495 # or a plain string.
… …
435 # send string 508 # send string
436 my $len = syswrite $self->[FH], $self->[QUEUE][0]; 509 my $len = syswrite $self->[FH], $self->[QUEUE][0];
437 510
438 unless ($len) { 511 unless ($len) {
439 return if $! == Errno::EAGAIN || $! == Errno::EWOULDBLOCK; 512 return if $! == Errno::EAGAIN || $! == Errno::EWOULDBLOCK;
440 undef $self->[3]; 513 undef $self->[WW];
441 die "AnyEvent::Fork: command write failure: $!"; 514 die "AnyEvent::Fork: command write failure: $!";
442 } 515 }
443 516
444 substr $self->[QUEUE][0], 0, $len, ""; 517 substr $self->[QUEUE][0], 0, $len, "";
445 shift @{ $self->[QUEUE] } unless length $self->[QUEUE][0]; 518 shift @{ $self->[QUEUE] } unless length $self->[QUEUE][0];
… …
448 521
449 # everything written 522 # everything written
450 undef $self->[WW]; 523 undef $self->[WW];
451 524
452 # invoke run callback, if any 525 # invoke run callback, if any
526 if ($self->[CB]) {
453 $self->[CB]->($self->[FH]) if $self->[CB]; 527 $self->[CB]->($self->[FH]);
528 @$self = ();
529 }
454 }; 530 };
455 531
456 () # make sure we don't leak the watcher 532 () # make sure we don't leak the watcher
457} 533}
458 534
… …
773 $self->_cmd (r => $func); 849 $self->_cmd (r => $func);
774} 850}
775 851
776=back 852=back
777 853
854=head2 ADVANCED METHODS
855
856=over 4
857
858=item new_from_stdio AnyEvent::Fork $fh
859
860Assume that you have a perl interpreter running (without any special
861options or a program) somewhere and it has it's STDIN and STDOUT connected
862to the C<$fh> somehow. I.e. exactly the state perl is in when you start it
863without any arguments:
864
865 perl
866
867Then you can create an C<AnyEvent::Fork> object out of this perl
868interpreter with this constructor.
869
870When the usefulness of this isn't immediately clear, imagine you manage to
871run a perl interpreter remotely (F<ssh remotemachine perl>), then you can
872manage it mostly like a local C<AnyEvent::Fork> child.
873
874This works without any module support, i.e. the remote F<perl> does not
875need to have any special modules installed.
876
877There are a number of limitations though: C<send_fh> will only work if the
878L<IO::FDPass> module is loadable by the remote perl and the two processes
879are connected in a way that let's L<IO::FDPass> do it's work.
880
881This will therefore not work over a network connection. From this follows
882that C<fork> will also not work under these circumstances, as it relies on
883C<send_fh> internally.
884
885Although not a limitation of this module, keep in mind that the
886"communications socket" is simply C<STDIN>, and depending on how you
887started F<perl> (e.g. via F<ssh>), it might only be half-duplex. This is
888fine for C<AnyEvent::Fork>, but your C<run> function might want to use
889C<STDIN> (or the "communications socket") for input and C<STDOUT> for
890output.
891
892You can support both cases by checking the C<fileno> of the handle passed
893to your run function:
894
895 sub run {
896 my ($rfh) = @_;
897
898 my $wfh = fileno $rfh ? $rfh : *STDOUT;
899
900 # now use $rfh for reading and $wfh for writing
901 }
902
903=cut
904
905sub new_from_stdio {
906 my ($class, $fh) = @_;
907
908 my $self = $class->_new ($fh);
909
910 # send startup code
911 push @{ $self->[QUEUE] },
912 (do "AnyEvent/Fork/serve.pl")
913 . <<'EOF';
914
915$OWNER = "another process";
916$0 = "AnyEvent::Fork/stdio of $OWNER";
917
918serve *STDIN;
919__END__
920EOF
921
922 # the data is only sent when the user requests additional things, which
923 # is likely early enough for our purposes.
924
925 $self
926}
927
928=back
929
930=head2 EXPERIMENTAL METHODS
931
932These methods might go away completely or change behaviour, a any time.
933
934=over 4
935
936=item $proc->to_fh ($cb->($fh)) # EXPERIMENTAL, MIGHT BE REMOVED
937
938Flushes all commands out to the process and then calls the callback with
939the communications socket.
940
941The process object becomes unusable on return from this function - any
942further method calls result in undefined behaviour.
943
944The point of this method is to give you a file handle thta you cna pass
945to another process. In that other process, you can call C<new_from_fh
946AnyEvent::Fork> to create a new C<AnyEvent::Fork> object from it, thereby
947effectively passing a fork object to another process.
948
949=cut
950
951sub to_fh {
952 my ($self, $cb) = @_;
953
954 $self->[CB] = $cb;
955
956 unless ($self->[WW]) {
957 $self->[CB]->($self->[FH]);
958 @$self = ();
959 }
960}
961
962=item new_from_fh AnyEvent::Fork $fh # EXPERIMENTAL, MIGHT BE REMOVED
963
964Takes a file handle originally rceeived by the C<to_fh> method and creates
965a new C<AnyEvent:Fork> object. The child process itself will not change in
966any way, i.e. it will keep all the modifications done to it before calling
967C<to_fh>.
968
969The new object is very much like the original object, except that the
970C<pid> method will return C<undef> even if the process is a direct child.
971
972=cut
973
974sub new_from_fh {
975 my ($class, $fh) = @_;
976
977 $class->_new ($fh)
978}
979
980=back
981
778=head1 PERFORMANCE 982=head1 PERFORMANCE
779 983
780Now for some unscientific benchmark numbers (all done on an amd64 984Now for some unscientific benchmark numbers (all done on an amd64
781GNU/Linux box). These are intended to give you an idea of the relative 985GNU/Linux box). These are intended to give you an idea of the relative
782performance you can expect, they are not meant to be absolute performance 986performance you can expect, they are not meant to be absolute performance
… …
788 992
789 2079 new processes per second, using manual socketpair + fork 993 2079 new processes per second, using manual socketpair + fork
790 994
791Then I did the same thing, but instead of calling fork, I called 995Then I did the same thing, but instead of calling fork, I called
792AnyEvent::Fork->new->run ("CORE::exit") and then again waited for the 996AnyEvent::Fork->new->run ("CORE::exit") and then again waited for the
793socket form the child to close on exit. This does the same thing as manual 997socket from the child to close on exit. This does the same thing as manual
794socket pair + fork, except that what is forked is the template process 998socket pair + fork, except that what is forked is the template process
795(2440kB), and the socket needs to be passed to the server at the other end 999(2440kB), and the socket needs to be passed to the server at the other end
796of the socket first. 1000of the socket first.
797 1001
798 2307 new processes per second, using AnyEvent::Fork->new 1002 2307 new processes per second, using AnyEvent::Fork->new
… …
905to make it so, mostly due to the bloody broken perl that nobody seems to 1109to make it so, mostly due to the bloody broken perl that nobody seems to
906care about. The fork emulation is a bad joke - I have yet to see something 1110care about. The fork emulation is a bad joke - I have yet to see something
907useful that you can do with it without running into memory corruption 1111useful that you can do with it without running into memory corruption
908issues or other braindamage. Hrrrr. 1112issues or other braindamage. Hrrrr.
909 1113
1114Since fork is endlessly broken on win32 perls (it doesn't even remotely
1115work within it's documented limits) and quite obviously it's not getting
1116improved any time soon, the best way to proceed on windows would be to
1117always use C<new_exec> and thus never rely on perl's fork "emulation".
1118
910Cygwin perl is not supported at the moment due to some hilarious 1119Cygwin perl is not supported at the moment due to some hilarious
911shortcomings of its API - see L<IO::FDPoll> for more details. 1120shortcomings of its API - see L<IO::FDPoll> for more details. If you never
1121use C<send_fh> and always use C<new_exec> to create processes, it should
1122work though.
912 1123
913=head1 SEE ALSO 1124=head1 SEE ALSO
914 1125
915L<AnyEvent::Fork::Early>, to avoid executing a perl interpreter at all 1126L<AnyEvent::Fork::Early>, to avoid executing a perl interpreter at all
916(part of this distribution). 1127(part of this distribution).
… …
918L<AnyEvent::Fork::Template>, to create a process by forking the main 1129L<AnyEvent::Fork::Template>, to create a process by forking the main
919program at a convenient time (part of this distribution). 1130program at a convenient time (part of this distribution).
920 1131
921L<AnyEvent::Fork::RPC>, for simple RPC to child processes (on CPAN). 1132L<AnyEvent::Fork::RPC>, for simple RPC to child processes (on CPAN).
922 1133
1134L<AnyEvent::Fork::Pool>, for simple worker process pool (on CPAN).
1135
923=head1 AUTHOR AND CONTACT INFORMATION 1136=head1 AUTHOR AND CONTACT INFORMATION
924 1137
925 Marc Lehmann <schmorp@schmorp.de> 1138 Marc Lehmann <schmorp@schmorp.de>
926 http://software.schmorp.de/pkg/AnyEvent-Fork 1139 http://software.schmorp.de/pkg/AnyEvent-Fork
927 1140

Diff Legend

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