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.50 by root, Sat Apr 20 19:58:06 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.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
… …
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.
… …
774 847
775 $self->[CB] = $cb; 848 $self->[CB] = $cb;
776 $self->_cmd (r => $func); 849 $self->_cmd (r => $func);
777} 850}
778 851
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 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
779=item $proc->to_fh ($cb->($fh)) # EXPERIMENTAL, MIGHT BE REMOVED 936=item $proc->to_fh ($cb->($fh)) # EXPERIMENTAL, MIGHT BE REMOVED
780 937
781Flushes all commands out to the process and then calls the callback with 938Flushes all commands out to the process and then calls the callback with
782the communications socket. 939the communications socket.
783 940
784The process object becomes unusable on return from this function - any 941The process object becomes unusable on return from this function - any
785further method calls result in undefined behaviour. 942further method calls result in undefined behaviour.
786 943
787The point of this method is to give you a file handle thta you cna pass 944The 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 945to 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, 946AnyEvent::Fork> to create a new C<AnyEvent::Fork> object from it, thereby
790thereby effectively passing a fork object to another process. 947effectively passing a fork object to another process.
791 948
792=cut 949=cut
793 950
794sub to_fh { 951sub to_fh {
795 my ($self, $cb) = @_; 952 my ($self, $cb) = @_;
… …
972L<AnyEvent::Fork::Template>, to create a process by forking the main 1129L<AnyEvent::Fork::Template>, to create a process by forking the main
973program at a convenient time (part of this distribution). 1130program at a convenient time (part of this distribution).
974 1131
975L<AnyEvent::Fork::RPC>, for simple RPC to child processes (on CPAN). 1132L<AnyEvent::Fork::RPC>, for simple RPC to child processes (on CPAN).
976 1133
1134L<AnyEvent::Fork::Pool>, for simple worker process pool (on CPAN).
1135
977=head1 AUTHOR AND CONTACT INFORMATION 1136=head1 AUTHOR AND CONTACT INFORMATION
978 1137
979 Marc Lehmann <schmorp@schmorp.de> 1138 Marc Lehmann <schmorp@schmorp.de>
980 http://software.schmorp.de/pkg/AnyEvent-Fork 1139 http://software.schmorp.de/pkg/AnyEvent-Fork
981 1140

Diff Legend

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