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.49 by root, Fri Apr 19 12:56:53 2013 UTC vs.
Revision 1.53 by root, Fri Apr 26 15:44:44 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.7; 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
… …
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];
… …
774 847
775 $self->[CB] = $cb; 848 $self->[CB] = $cb;
776 $self->_cmd (r => $func); 849 $self->_cmd (r => $func);
777} 850}
778 851
779=item $proc->to_fh ($cb->($fh)) 852=back
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 conenction. From this follows
882that C<fork> will also not work under these circumstances, as it relies on
883C<send_fh> internally.
884
885=cut
886
887sub new_from_stdio {
888 my ($class, $fh) = @_;
889
890 my $self = $class->_new ($fh);
891
892 # send startup code
893 push @{ $self->[QUEUE] },
894 (do "AnyEvent/Fork/serve.pl")
895 . <<'EOF';
896{
897 open my $fh, "+<&0"
898 or die "AnyEvent::Fork::Serve::stdio: unable to open communications socket: $!\n";
899 open STDIN , ">&2";
900 open STDOUT, ">&2";
901
902 $OWNER = "another process";
903 $0 = "AnyEvent::Fork/stdio of $OWNER";
904
905 @_ = $fh;
906}
907
908&serve;
909__END__
910EOF
911
912 # the data is only sent when the user requests additional things, which
913 # is likely early enough for our purposes.
914
915 $self
916}
917
918=back
919
920=head2 EXPERIMENTAL METHODS
921
922These methods might go away completely or change behaviour, a any time.
923
924=over 4
925
926=item $proc->to_fh ($cb->($fh)) # EXPERIMENTAL, MIGHT BE REMOVED
780 927
781Flushes all commands out to the process and then calls the callback with 928Flushes all commands out to the process and then calls the callback with
782the communications socket. 929the communications socket.
783 930
784The process object becomes unusable on return from this function - any 931The process object becomes unusable on return from this function - any
785further method calls result in undefined behaviour. 932further method calls result in undefined behaviour.
786 933
787The point of this method is to give you a file handle thta you cna pass 934The point of this method is to give you a file handle thta you cna pass
788to another process. In that other process, you can call C<new_from_fh 935to another process. In that other process, you can call C<new_from_fh
789AnyEvent::Fork::RPC> to create a new C<AnyEvent::Fork> object from it, 936AnyEvent::Fork> to create a new C<AnyEvent::Fork> object from it, thereby
790thereby effectively passing a fork object to another process. 937effectively passing a fork object to another process.
791 938
792=cut 939=cut
793 940
794sub to_fh { 941sub to_fh {
795 my ($self, $cb) = @_; 942 my ($self, $cb) = @_;
… …
800 $self->[CB]->($self->[FH]); 947 $self->[CB]->($self->[FH]);
801 @$self = (); 948 @$self = ();
802 } 949 }
803} 950}
804 951
805=item new_from_fh AnyEvent::Fork $fh 952=item new_from_fh AnyEvent::Fork $fh # EXPERIMENTAL, MIGHT BE REMOVED
806 953
807Takes a file handle originally rceeived by the C<to_fh> method and creates 954Takes a file handle originally rceeived by the C<to_fh> method and creates
808a new C<AnyEvent:Fork> object. The child process itself will not change in 955a new C<AnyEvent:Fork> object. The child process itself will not change in
809any way, i.e. it will keep all the modifications done to it before calling 956any way, i.e. it will keep all the modifications done to it before calling
810C<to_fh>. 957C<to_fh>.
… …
972L<AnyEvent::Fork::Template>, to create a process by forking the main 1119L<AnyEvent::Fork::Template>, to create a process by forking the main
973program at a convenient time (part of this distribution). 1120program at a convenient time (part of this distribution).
974 1121
975L<AnyEvent::Fork::RPC>, for simple RPC to child processes (on CPAN). 1122L<AnyEvent::Fork::RPC>, for simple RPC to child processes (on CPAN).
976 1123
1124L<AnyEvent::Fork::Pool>, for simple worker process pool (on CPAN).
1125
977=head1 AUTHOR AND CONTACT INFORMATION 1126=head1 AUTHOR AND CONTACT INFORMATION
978 1127
979 Marc Lehmann <schmorp@schmorp.de> 1128 Marc Lehmann <schmorp@schmorp.de>
980 http://software.schmorp.de/pkg/AnyEvent-Fork 1129 http://software.schmorp.de/pkg/AnyEvent-Fork
981 1130

Diff Legend

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