[ViewVC] Diff of: cvs/AnyEvent-Fork/Fork.pm

Comparing AnyEvent-Fork/Fork.pm (file contents):
Revision 1.54 by root, Fri Apr 26 17:24:05 2013 UTC vs.
Revision 1.62 by root, Mon Nov 25 20:21:09 2013 UTC

…		…
256		256
257	my $stderr = $cv->recv;	257	my $stderr = $cv->recv;
258		258
259	=head2 For stingy users: put the worker code into a C<DATA> section.	259	=head2 For stingy users: put the worker code into a C<DATA> section.
260		260
261	When you want to be stingy with files, you cna put your code into the	261	When you want to be stingy with files, you can put your code into the
262	C<DATA> section of your module (or program):	262	C<DATA> section of your module (or program):
263		263
264	use AnyEvent::Fork;	264	use AnyEvent::Fork;
265		265
266	AnyEvent::Fork	266	AnyEvent::Fork
…		…
276		276
277	=head2 For stingy standalone programs: do not rely on external files at	277	=head2 For stingy standalone programs: do not rely on external files at
278	all.	278	all.
279		279
280	For single-file scripts it can be inconvenient to rely on external	280	For single-file scripts it can be inconvenient to rely on external
281	files - even when using < C<DATA> section, you still need to C<exec>	281	files - even when using a C<DATA> section, you still need to C<exec> an
282	an external perl interpreter, which might not be available when using	282	external perl interpreter, which might not be available when using
283	L<App::Staticperl>, L<Urlader> or L<PAR::Packer> for example.	283	L<App::Staticperl>, L<Urlader> or L<PAR::Packer> for example.
284		284
285	Two modules help here - L<AnyEvent::Fork::Early> forks a template process	285	Two modules help here - L<AnyEvent::Fork::Early> forks a template process
286	for all further calls to C<new_exec>, and L<AnyEvent::Fork::Template>	286	for all further calls to C<new_exec>, and L<AnyEvent::Fork::Template>
287	forks the main program as a template process.	287	forks the main program as a template process.
…		…
304	my ($fh, @args) = @_;	304	my ($fh, @args) = @_;
305	...	305	...
306	}	306	}
307		307
308	# now preserve everything so far as AnyEvent::Fork object	308	# now preserve everything so far as AnyEvent::Fork object
309	# in §TEMPLATE.	309	# in $TEMPLATE.
310	use AnyEvent::Fork::Template;	310	use AnyEvent::Fork::Template;
311		311
312	# do not put code outside of BEGIN blocks until here	312	# do not put code outside of BEGIN blocks until here
313		313
314	# now use the $TEMPLATE process in any way you like	314	# now use the $TEMPLATE process in any way you like
…		…
450	use AnyEvent;	450	use AnyEvent;
451	use AnyEvent::Util ();	451	use AnyEvent::Util ();
452		452
453	use IO::FDPass;	453	use IO::FDPass;
454		454
455	our $VERSION = '1.0';	455	our $VERSION = 1.2;
456		456
457	# the early fork template process	457	# the early fork template process
458	our $EARLY;	458	our $EARLY;
459		459
460	# the empty template process	460	# the empty template process
…		…
485	my $self = shift;	485	my $self = shift;
486		486
487	# 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
488	# 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
489	# it.	489	# it.
490	push @{ $self->[QUEUE] }, pack "a N/a*", $_[0], $_[1];	490	push @{ $self->[QUEUE] }, pack "a L/a*", $_[0], $_[1];
491		491
492	$self->[WW] \|\|= AE::io $self->[FH], 1, sub {	492	$self->[WW] \|\|= AE::io $self->[FH], 1, sub {
493	do {	493	do {
494	# 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,
495	# or a plain string.	495	# or a plain string.
…		…
605		605
606	You should use C<new> whenever possible, except when having a template	606	You should use C<new> whenever possible, except when having a template
607	process around is unacceptable.	607	process around is unacceptable.
608		608
609	The path to the perl interpreter is divined using various methods - first	609	The path to the perl interpreter is divined using various methods - first
610	C<$^X> is investigated to see if the path ends with something that sounds	610	C<$^X> is investigated to see if the path ends with something that looks
611	as if it were the perl interpreter. Failing this, the module falls back to	611	as if it were the perl interpreter. Failing this, the module falls back to
612	using C<$Config::Config{perlpath}>.	612	using C<$Config::Config{perlpath}>.
613		613
		614	The path to perl can also be overriden by setting the global variable
		615	C<$AnyEvent::Fork::PERL> - it's value will be used for all subsequent
		616	invocations.
		617
614	=cut	618	=cut
		619
		620	our $PERL;
615		621
616	sub new_exec {	622	sub new_exec {
617	my ($self) = @_;	623	my ($self) = @_;
618		624
619	return $EARLY->fork	625	return $EARLY->fork
620	if $EARLY;	626	if $EARLY;
621		627
		628	unless (defined $PERL) {
622	# first find path of perl	629	# first find path of perl
623	my $perl = $;	630	my $perl = $^X;
624		631
625	# first we try $^X, but the path must be absolute (always on win32), and end in sth.	632	# first we try $^X, but the path must be absolute (always on win32), and end in sth.
626	# that looks like perl. this obviously only works for posix and win32	633	# that looks like perl. this obviously only works for posix and win32
627	unless (	634	unless (
628	($^O eq "MSWin32" \|\| $perl =~ m%^/%)	635	($^O eq "MSWin32" \|\| $perl =~ m%^/%)
629	&& $perl =~ m%[/\\]perl(?:[0-9]+(\.[0-9]+)+)?(\.exe)?$%i	636	&& $perl =~ m%[/\\]perl(?:[0-9]+(\.[0-9]+)+)?(\.exe)?$%i
630	) {	637	) {
631	# if it doesn't look perlish enough, try Config	638	# if it doesn't look perlish enough, try Config
632	require Config;	639	require Config;
633	$perl = $Config::Config{perlpath};	640	$perl = $Config::Config{perlpath};
634	$perl =~ s/(?:\Q$Config::Config{_exe}\E)?$/$Config::Config{_exe}/;	641	$perl =~ s/(?:\Q$Config::Config{_exe}\E)?$/$Config::Config{_exe}/;
		642	}
		643
		644	$PERL = $perl;
635	}	645	}
636		646
637	require Proc::FastSpawn;	647	require Proc::FastSpawn;
638		648
639	my ($fh, $slave) = AnyEvent::Util::portable_socketpair;	649	my ($fh, $slave) = AnyEvent::Util::portable_socketpair;
…		…
647	#local $ENV{PERL5LIB} = join ":", grep !ref, @INC;	657	#local $ENV{PERL5LIB} = join ":", grep !ref, @INC;
648	my %env = %ENV;	658	my %env = %ENV;
649	$env{PERL5LIB} = join +($^O eq "MSWin32" ? ";" : ":"), grep !ref, @INC;	659	$env{PERL5LIB} = join +($^O eq "MSWin32" ? ";" : ":"), grep !ref, @INC;
650		660
651	my $pid = Proc::FastSpawn::spawn (	661	my $pid = Proc::FastSpawn::spawn (
652	$perl,	662	$PERL,
653	["perl", "-MAnyEvent::Fork::Serve", "-e", "AnyEvent::Fork::Serve::me", fileno $slave, $$],	663	["perl", "-MAnyEvent::Fork::Serve", "-e", "AnyEvent::Fork::Serve::me", fileno $slave, $$],
654	[map "$_=$env{$_}", keys %env],	664	[map "$_=$env{$_}", keys %env],
655	) or die "unable to spawn AnyEvent::Fork server: $!";	665	) or die "unable to spawn AnyEvent::Fork server: $!";
656		666
657	$self->_new ($fh, $pid)	667	$self->_new ($fh, $pid)
658	}	668	}
659		669
660	=item $pid = $proc->pid	670	=item $pid = $proc->pid
661		671
662	Returns the process id of the process I<iff it is a direct child of the	672	Returns the process id of the process I<iff it is a direct child of the
663	process running AnyEvent::Fork>, and C<undef> otherwise.	673	process running AnyEvent::Fork>, and C<undef> otherwise. As a general
		674	rule (that you cannot rely upon), processes created via C<new_exec>,
		675	L<AnyEvent::Fork::Early> or L<AnyEvent::Fork::Template> are direct
		676	children, while all other processes are not.
664		677
665	Normally, only processes created via C<< AnyEvent::Fork->new_exec >> and	678	Or in other words, you do not normally have to take care of zombies for
666	L<AnyEvent::Fork::Template> are direct children, and you are responsible	679	processes created via C<new>, but when in doubt, or zombies are a problem,
667	to clean up their zombies when they die.	680	you need to check whether a process is a diretc child by calling this
668		681	method, and possibly creating a child watcher or reap it manually.
669	All other processes are not direct children, and will be cleaned up by
670	AnyEvent::Fork itself.
671		682
672	=cut	683	=cut
673		684
674	sub pid {	685	sub pid {
675	$_[0][PID]	686	$_[0][PID]
…		…
806		817
807	Even if not used otherwise, the socket can be a good indicator for the	818	Even if not used otherwise, the socket can be a good indicator for the
808	existence of the process - if the other process exits, you get a readable	819	existence of the process - if the other process exits, you get a readable
809	event on it, because exiting the process closes the socket (if it didn't	820	event on it, because exiting the process closes the socket (if it didn't
810	create any children using fork).	821	create any children using fork).
		822
		823	=over 4
		824
		825	=item Compatibility to L<AnyEvent::Fork::Remote>
		826
		827	If you want to write code that works with both this module and
		828	L<AnyEvent::Fork::Remote>, you need to write your code so that it assumes
		829	there are two file handles for communications, which might not be unix
		830	domain sockets. The C<run> function should start like this:
		831
		832	sub run {
		833	my ($rfh, @args) = @_; # @args is your normal arguments
		834	my $wfh = fileno $rfh ? $rfh : *STDOUT;
		835
		836	# now use $rfh for reading and $wfh for writing
		837	}
		838
		839	This checks whether the passed file handle is, in fact, the process
		840	C<STDIN> handle. If it is, then the function was invoked visa
		841	L<AnyEvent::Fork::Remote>, so STDIN should be used for reading and
		842	C<STDOUT> should be used for writing.
		843
		844	In all other cases, the function was called via this module, and there is
		845	only one file handle that should be sued for reading and writing.
		846
		847	=back
811		848
812	Example: create a template for a process pool, pass a few strings, some	849	Example: create a template for a process pool, pass a few strings, some
813	file handles, then fork, pass one more string, and run some code.	850	file handles, then fork, pass one more string, and run some code.
814		851
815	my $pool = AnyEvent::Fork	852	my $pool = AnyEvent::Fork
…		…
849	$self->_cmd (r => $func);	886	$self->_cmd (r => $func);
850	}	887	}
851		888
852	=back	889	=back
853		890
854	=head2 ADVANCED METHODS
855
856	=over 4
857
858	=item new_from_stdio AnyEvent::Fork $fh
859
860	Assume that you have a perl interpreter running (without any special
861	options or a program) somewhere and it has it's STDIN and STDOUT connected
862	to the C<$fh> somehow. I.e. exactly the state perl is in when you start it
863	without any arguments:
864
865	perl
866
867	Then you can create an C<AnyEvent::Fork> object out of this perl
868	interpreter with this constructor.
869
870	When the usefulness of this isn't immediately clear, imagine you manage to
871	run a perl interpreter remotely (F<ssh remotemachine perl>), then you can
872	manage it mostly like a local C<AnyEvent::Fork> child.
873
874	This works without any module support, i.e. the remote F<perl> does not
875	need to have any special modules installed.
876
877	There are a number of limitations though: C<send_fh> will only work if the
878	L<IO::FDPass> module is loadable by the remote perl and the two processes
879	are connected in a way that let's L<IO::FDPass> do it's work.
880
881	This will therefore not work over a network connection. From this follows
882	that C<fork> will also not work under these circumstances, as it relies on
883	C<send_fh> internally.
884
885	Although not a limitation of this module, keep in mind that the
886	"communications socket" is simply C<STDIN>, and depending on how you
887	started F<perl> (e.g. via F<ssh>), it might only be half-duplex. This is
888	fine for C<AnyEvent::Fork>, but your C<run> function might want to use
889	C<STDIN> (or the "communications socket") for input and C<STDOUT> for
890	output.
891
892	You can support both cases by checking the C<fileno> of the handle passed
893	to 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
905	sub 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
918	serve *STDIN;
919	__END__
920	EOF
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	891	=head2 EXPERIMENTAL METHODS
931		892
932	These methods might go away completely or change behaviour, a any time.	893	These methods might go away completely or change behaviour, at any time.
933		894
934	=over 4	895	=over 4
935		896
936	=item $proc->to_fh ($cb->($fh)) # EXPERIMENTAL, MIGHT BE REMOVED	897	=item $proc->to_fh ($cb->($fh)) # EXPERIMENTAL, MIGHT BE REMOVED
937		898
…		…
939	the communications socket.	900	the communications socket.
940		901
941	The process object becomes unusable on return from this function - any	902	The process object becomes unusable on return from this function - any
942	further method calls result in undefined behaviour.	903	further method calls result in undefined behaviour.
943		904
944	The point of this method is to give you a file handle thta you cna pass	905	The point of this method is to give you a file handle that you can pass
945	to another process. In that other process, you can call C<new_from_fh	906	to another process. In that other process, you can call C<new_from_fh
946	AnyEvent::Fork> to create a new C<AnyEvent::Fork> object from it, thereby	907	AnyEvent::Fork $fh> to create a new C<AnyEvent::Fork> object from it,
947	effectively passing a fork object to another process.	908	thereby effectively passing a fork object to another process.
948		909
949	=cut	910	=cut
950		911
951	sub to_fh {	912	sub to_fh {
952	my ($self, $cb) = @_;	913	my ($self, $cb) = @_;
…		…
1127	(part of this distribution).	1088	(part of this distribution).
1128		1089
1129	L<AnyEvent::Fork::Template>, to create a process by forking the main	1090	L<AnyEvent::Fork::Template>, to create a process by forking the main
1130	program at a convenient time (part of this distribution).	1091	program at a convenient time (part of this distribution).
1131		1092
		1093	L<AnyEvent::Fork::Remote>, for another way to create processes that is
		1094	mostly compatible to this module and modules building on top of it, but
		1095	works better with remote processes.
		1096
1132	L<AnyEvent::Fork::RPC>, for simple RPC to child processes (on CPAN).	1097	L<AnyEvent::Fork::RPC>, for simple RPC to child processes (on CPAN).
1133		1098
1134	L<AnyEvent::Fork::Pool>, for simple worker process pool (on CPAN).	1099	L<AnyEvent::Fork::Pool>, for simple worker process pool (on CPAN).
1135		1100
1136	=head1 AUTHOR AND CONTACT INFORMATION	1101	=head1 AUTHOR AND CONTACT INFORMATION

Diff Legend

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

Comparing AnyEvent-Fork/Fork.pm (file contents): Revision 1.54 by root, Fri Apr 26 17:24:05 2013 UTC vs. Revision 1.62 by root, Mon Nov 25 20:21:09 2013 UTC

Diff Legend

Comparing AnyEvent-Fork/Fork.pm (file contents):
Revision 1.54 by root, Fri Apr 26 17:24:05 2013 UTC vs.
Revision 1.62 by root, Mon Nov 25 20:21:09 2013 UTC