[ViewVC] Diff of: cvs/AnyEvent-Fork/README

Comparing AnyEvent-Fork/README (file contents):
Revision 1.5 by root, Sat Apr 6 22:41:56 2013 UTC vs.
Revision 1.10 by root, Thu May 12 16:54:01 2016 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	And if you need some automatic process pool management on top of
		40	AnyEvent::Fork::RPC, you can look at the AnyEvent::Fork::Pool companion
		41	module.
		42
		43	Or you can implement it yourself in whatever way you like: use some
		44	message-passing module such as AnyEvent::MP, some pipe such as
		45	AnyEvent::ZeroMQ, use AnyEvent::Handle on both sides to send e.g. JSON
		46	or Storable messages, and so on.
39		47
40	COMPARISON TO OTHER MODULES	48	COMPARISON TO OTHER MODULES
41	There is an abundance of modules on CPAN that do "something fork", such	49	There is an abundance of modules on CPAN that do "something fork", such
42	as Parallel::ForkManager, AnyEvent::ForkManager, AnyEvent::Worker or	50	as Parallel::ForkManager, AnyEvent::ForkManager, AnyEvent::Worker or
43	AnyEvent::Subprocess. There are modules that implement their own process	51	AnyEvent::Subprocess. There are modules that implement their own process
44	management, such as AnyEvent::DBI.	52	management, such as AnyEvent::DBI.
45		53
46	The problems that all these modules try to solve are real, however, none	54	The problems that all these modules try to solve are real, however, none
47	of them (from what I have seen) tackle the very real problems of	55	of them (from what I have seen) tackle the very real problems of
48	unwanted memory sharing, efficiency, not being able to use event	56	unwanted memory sharing, efficiency or not being able to use event
49	processing or similar modules in the processes they create.	57	processing, GUI toolkits or similar modules in the processes they
		58	create.
50		59
51	This module doesn't try to replace any of them - instead it tries to	60	This module doesn't try to replace any of them - instead it tries to
52	solve the problem of creating processes with a minimum of fuss and	61	solve the problem of creating processes with a minimum of fuss and
53	overhead (and also luxury). Ideally, most of these would use	62	overhead (and also luxury). Ideally, most of these would use
54	AnyEvent::Fork internally, except they were written before AnyEvent:Fork	63	AnyEvent::Fork internally, except they were written before AnyEvent:Fork
…		…
71	vfork where possible. This gives the speed of vfork, with the	80	vfork where possible. This gives the speed of vfork, with the
72	flexibility of fork.	81	flexibility of fork.
73		82
74	Forking usually creates a copy-on-write copy of the parent process.	83	Forking usually creates a copy-on-write copy of the parent process.
75	For example, modules or data files that are loaded will not use	84	For example, modules or data files that are loaded will not use
76	additional memory after a fork. When exec'ing a new process, modules	85	additional memory after a fork. Exec'ing a new process, in contrast,
77	and data files might need to be loaded again, at extra CPU and	86	means modules and data files might need to be loaded again, at extra
78	memory cost. But when forking, literally all data structures are	87	CPU and memory cost.
		88
		89	But when forking, you still create a copy of your data structures -
79	copied - if the program frees them and replaces them by new data,	90	if the program frees them and replaces them by new data, the child
80	the child processes will retain the old version even if it isn't	91	processes will retain the old version even if it isn't used, which
81	used, which can suddenly and unexpectedly increase memory usage when	92	can suddenly and unexpectedly increase memory usage when freeing
82	freeing memory.	93	memory.
83		94
		95	For example, Gtk2::CV is an image viewer optimised for large
		96	directories (millions of pictures). It also forks subprocesses for
		97	thumbnail generation, which inherit the data structure that stores
		98	all file information. If the user changes the directory, it gets
		99	freed in the main process, leaving a copy in the thumbnailer
		100	processes. This can lead to many times the memory usage that would
		101	actually be required. The solution is to fork early (and being
		102	unable to dynamically generate more subprocesses or do this from a
		103	module)... or to use <AnyEvent:Fork>.
		104
84	The trade-off is between more sharing with fork (which can be good	105	There is a trade-off between more sharing with fork (which can be
85	or bad), and no sharing with exec.	106	good or bad), and no sharing with exec.
86		107
87	This module allows the main program to do a controlled fork, and	108	This module allows the main program to do a controlled fork, and
88	allows modules to exec processes safely at any time. When creating a	109	allows modules to exec processes safely at any time. When creating a
89	custom process pool you can take advantage of data sharing via fork	110	custom process pool you can take advantage of data sharing via fork
90	without risking to share large dynamic data structures that will	111	without risking to share large dynamic data structures that will
…		…
93	In other words, this module puts you into control over what is being	114	In other words, this module puts you into control over what is being
94	shared and what isn't, at all times.	115	shared and what isn't, at all times.
95		116
96	Exec'ing a new perl process might be difficult.	117	Exec'ing a new perl process might be difficult.
97	For example, it is not easy to find the correct path to the perl	118	For example, it is not easy to find the correct path to the perl
98	interpreter - $^X might not be a perl interpreter at all.	119	interpreter - $^X might not be a perl interpreter at all. Worse,
		120	there might not even be a perl binary installed on the system.
99		121
100	This module tries hard to identify the correct path to the perl	122	This module tries hard to identify the correct path to the perl
101	interpreter. With a cooperative main program, exec'ing the	123	interpreter. With a cooperative main program, exec'ing the
102	interpreter might not even be necessary, but even without help from	124	interpreter might not even be necessary, but even without help from
103	the main program, it will still work when used from a module.	125	the main program, it will still work when used from a module.
…		…
108	and modules are no longer loadable because they refer to a different	130	and modules are no longer loadable because they refer to a different
109	perl version, or parts of a distribution are newer than the ones	131	perl version, or parts of a distribution are newer than the ones
110	already loaded.	132	already loaded.
111		133
112	This module supports creating pre-initialised perl processes to be	134	This module supports creating pre-initialised perl processes to be
113	used as a template for new processes.	135	used as a template for new processes at a later time, e.g. for use
		136	in a process pool.
114		137
115	Forking might be impossible when a program is running.	138	Forking might be impossible when a program is running.
116	For example, POSIX makes it almost impossible to fork from a	139	For example, POSIX makes it almost impossible to fork from a
117	multi-threaded program while doing anything useful in the child - in	140	multi-threaded program while doing anything useful in the child - in
118	fact, if your perl program uses POSIX threads (even indirectly via	141	fact, if your perl program uses POSIX threads (even indirectly via
119	e.g. IO::AIO or threads), you cannot call fork on the perl level	142	e.g. IO::AIO or threads), you cannot call fork on the perl level
120	anymore without risking corruption issues on a number of operating	143	anymore without risking memory corruption or worse on a number of
121	systems.	144	operating systems.
122		145
123	This module can safely fork helper processes at any time, by calling	146	This module can safely fork helper processes at any time, by calling
124	fork+exec in C, in a POSIX-compatible way (via Proc::FastSpawn).	147	fork+exec in C, in a POSIX-compatible way (via Proc::FastSpawn).
125		148
126	Parallel processing with fork might be inconvenient or difficult to	149	Parallel processing with fork might be inconvenient or difficult to
…		…
142	is still safe to do so) - all other processes are created via	165	is still safe to do so) - all other processes are created via
143	fork+exec, which makes it possible to use modules such as event	166	fork+exec, which makes it possible to use modules such as event
144	loops or window interfaces safely.	167	loops or window interfaces safely.
145		168
146	EXAMPLES	169	EXAMPLES
		170	This is where the wall of text ends and code speaks.
		171
147	Create a single new process, tell it to run your worker function.	172	Create a single new process, tell it to run your worker function.
148	AnyEvent::Fork	173	AnyEvent::Fork
149	->new	174	->new
150	->require ("MyModule")	175	->require ("MyModule")
151	->run ("MyModule::worker, sub {	176	->run ("MyModule::worker, sub {
…		…
161		186
162	sub worker {	187	sub worker {
163	my ($slave_filehandle) = @_;	188	my ($slave_filehandle) = @_;
164		189
165	# now $slave_filehandle is connected to the $master_filehandle	190	# now $slave_filehandle is connected to the $master_filehandle
166	# in the original prorcess. have fun!	191	# in the original process. have fun!
167	}	192	}
168		193
169	Create a pool of server processes all accepting on the same socket.	194	Create a pool of server processes all accepting on the same socket.
170	# create listener socket	195	# create listener socket
171	my $listener = ...;	196	my $listener = ...;
…		…
202	# do sth. with new socket	227	# do sth. with new socket
203	}	228	}
204	}	229	}
205		230
206	use AnyEvent::Fork as a faster fork+exec	231	use AnyEvent::Fork as a faster fork+exec
207	This runs "/bin/echo hi", with stdandard output redirected to /tmp/log	232	This runs "/bin/echo hi", with standard output redirected to /tmp/log
208	and standard error redirected to the communications socket. It is	233	and standard error redirected to the communications socket. It is
209	usually faster than fork+exec, but still lets you prepare the	234	usually faster than fork+exec, but still lets you prepare the
210	environment.	235	environment.
211		236
212	open my $output, ">/tmp/log" or die "$!";	237	open my $output, ">/tmp/log" or die "$!";
…		…
229	->send_arg ("/bin/echo", "hi")	254	->send_arg ("/bin/echo", "hi")
230	->run ("run", my $cv = AE::cv);	255	->run ("run", my $cv = AE::cv);
231		256
232	my $stderr = $cv->recv;	257	my $stderr = $cv->recv;
233		258
		259	For stingy users: put the worker code into a "DATA" section.
		260	When you want to be stingy with files, you can put your code into the
		261	"DATA" section of your module (or program):
		262
		263	use AnyEvent::Fork;
		264
		265	AnyEvent::Fork
		266	->new
		267	->eval (do { local $/; <DATA> })
		268	->run ("doit", sub { ... });
		269
		270	__DATA__
		271
		272	sub doit {
		273	... do something!
		274	}
		275
		276	For stingy standalone programs: do not rely on external files at
		277	all.
		278	For single-file scripts it can be inconvenient to rely on external files
		279	- even when using a "DATA" section, you still need to "exec" an external
		280	perl interpreter, which might not be available when using
		281	App::Staticperl, Urlader or PAR::Packer for example.
		282
		283	Two modules help here - AnyEvent::Fork::Early forks a template process
		284	for all further calls to "new_exec", and AnyEvent::Fork::Template forks
		285	the main program as a template process.
		286
		287	Here is how your main program should look like:
		288
		289	#! perl
		290
		291	# optional, as the very first thing.
		292	# in case modules want to create their own processes.
		293	use AnyEvent::Fork::Early;
		294
		295	# next, load all modules you need in your template process
		296	use Example::My::Module
		297	use Example::Whatever;
		298
		299	# next, put your run function definition and anything else you
		300	# need, but do not use code outside of BEGIN blocks.
		301	sub worker_run {
		302	my ($fh, @args) = @_;
		303	...
		304	}
		305
		306	# now preserve everything so far as AnyEvent::Fork object
		307	# in $TEMPLATE.
		308	use AnyEvent::Fork::Template;
		309
		310	# do not put code outside of BEGIN blocks until here
		311
		312	# now use the $TEMPLATE process in any way you like
		313
		314	# for example: create 10 worker processes
		315	my @worker;
		316	my $cv = AE::cv;
		317	for (1..10) {
		318	$cv->begin;
		319	$TEMPLATE->fork->send_arg ($_)->run ("worker_run", sub {
		320	push @worker, shift;
		321	$cv->end;
		322	});
		323	}
		324	$cv->recv;
		325
234	CONCEPTS	326	CONCEPTS
235	This module can create new processes either by executing a new perl	327	This module can create new processes either by executing a new perl
236	process, or by forking from an existing "template" process.	328	process, or by forking from an existing "template" process.
		329
		330	All these processes are called "child processes" (whether they are
		331	direct children or not), while the process that manages them is called
		332	the "parent process".
237		333
238	Each such process comes with its own file handle that can be used to	334	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	335	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	336	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	337	in it are load modules, fork new processes, send file handles to it, and
…		…
329		425
330	As long as there is any outstanding work to be done, process objects	426	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	427	resist being destroyed, so there is no reason to store them unless you
332	need them later - configure and forget works just fine.	428	need them later - configure and forget works just fine.
333		429
334	my $proc = new AnyEvent::Fork	430	my $proc = new AnyEvent::Fork
335
336	Create a new "empty" perl interpreter process and returns its	431	Create a new "empty" perl interpreter process and returns its
337	process object for further manipulation.	432	process object for further manipulation.
338		433
339	The new process is forked from a template process that is kept	434	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	435	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.	436	a call to "new_exec" first and then stays around for future calls.
342		437
343	$new_proc = $proc->fork	438	$new_proc = $proc->fork
344
345	Forks $proc, creating a new process, and returns the process object	439	Forks $proc, creating a new process, and returns the process object
346	of the new process.	440	of the new process.
347		441
348	If any of the "send_" functions have been called before fork, then	442	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	443	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	444	server, you might "send_fh" the listening socket into the template
351	process, and then keep calling "fork" and "run".	445	process, and then keep calling "fork" and "run".
352		446
353	my $proc = new_exec AnyEvent::Fork	447	my $proc = new_exec AnyEvent::Fork
354
355	Create a new "empty" perl interpreter process and returns its	448	Create a new "empty" perl interpreter process and returns its
356	process object for further manipulation.	449	process object for further manipulation.
357		450
358	Unlike the "new" method, this method always spawns a new perl	451	Unlike the "new" method, this method always spawns a new perl
359	process (except in some cases, see AnyEvent::Fork::Early for	452	process (except in some cases, see AnyEvent::Fork::Early for
…		…
363	You should use "new" whenever possible, except when having a	456	You should use "new" whenever possible, except when having a
364	template process around is unacceptable.	457	template process around is unacceptable.
365		458
366	The path to the perl interpreter is divined using various methods -	459	The path to the perl interpreter is divined using various methods -
367	first $^X is investigated to see if the path ends with something	460	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	461	that looks as if it were the perl interpreter. Failing this, the
369	module falls back to using $Config::Config{perlpath}.	462	module falls back to using $Config::Config{perlpath}.
370		463
		464	The path to perl can also be overriden by setting the global
		465	variable $AnyEvent::Fork::PERL - it's value will be used for all
		466	subsequent invocations.
		467
371	$pid = $proc->pid	468	$pid = $proc->pid
372
373	Returns the process id of the process *iff it is a direct child of	469	Returns the process id of the process *iff it is a direct child of
374	the process running AnyEvent::Fork*, and "undef" otherwise.	470	the process running AnyEvent::Fork*, and "undef" otherwise. As a
		471	general rule (that you cannot rely upon), processes created via
		472	"new_exec", AnyEvent::Fork::Early or AnyEvent::Fork::Template are
		473	direct children, while all other processes are not.
375		474
376	Normally, only processes created via "AnyEvent::Fork->new_exec" and	475	Or in other words, you do not normally have to take care of zombies
377	AnyEvent::Fork::Template are direct children, and you are	476	for processes created via "new", but when in doubt, or zombies are a
378	responsible to clean up their zombies when they die.	477	problem, you need to check whether a process is a diretc child by
		478	calling this method, and possibly creating a child watcher or reap
		479	it manually.
379		480
380	All other processes are not direct children, and will be cleaned up
381	by AnyEvent::Fork itself.
382
383	$proc = $proc->eval ($perlcode, @args)	481	$proc = $proc->eval ($perlcode, @args)
384
385	Evaluates the given $perlcode as ... perl code, while setting @_ to	482	Evaluates the given $perlcode as ... Perl code, while setting @_ to
386	the strings specified by @args, in the "main" package.	483	the strings specified by @args, in the "main" package.
387		484
388	This call is meant to do any custom initialisation that might be	485	This call is meant to do any custom initialisation that might be
389	required (for example, the "require" method uses it). It's not	486	required (for example, the "require" method uses it). It's not
390	supposed to be used to completely take over the process, use "run"	487	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	499	See the "use AnyEvent::Fork as a faster fork+exec" example to see it
403	in action.	500	in action.
404		501
405	Returns the process object for easy chaining of method calls.	502	Returns the process object for easy chaining of method calls.
406		503
		504	It's common to want to call an iniitalisation function with some
		505	arguments. Make sure you actually pass @_ to that function (for
		506	example by using &name syntax), and do not just specify a function
		507	name:
		508
		509	$proc->eval ('&MyModule::init', $string1, $string2);
		510
407	$proc = $proc->require ($module, ...)	511	$proc = $proc->require ($module, ...)
408
409	Tries to load the given module(s) into the process	512	Tries to load the given module(s) into the process
410		513
411	Returns the process object for easy chaining of method calls.	514	Returns the process object for easy chaining of method calls.
412		515
413	$proc = $proc->send_fh ($handle, ...)	516	$proc = $proc->send_fh ($handle, ...)
414
415	Send one or more file handles (not file descriptors) to the	517	Send one or more file handles (not file descriptors) to the
416	process, to prepare a call to "run".	518	process, to prepare a call to "run".
417		519
418	The process object keeps a reference to the handles until they have	520	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	521	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.	530	closing. It will be closed automatically when it is no longer used.
429		531
430	$proc->send_fh ($my_fh);	532	$proc->send_fh ($my_fh);
431	undef $my_fh; # free the reference if you want, but DO NOT CLOSE IT	533	undef $my_fh; # free the reference if you want, but DO NOT CLOSE IT
432		534
433	$proc = $proc->send_arg ($string, ...)	535	$proc = $proc->send_arg ($string, ...)
434
435	Send one or more argument strings to the process, to prepare a call	536	Send one or more argument strings to the process, to prepare a call
436	to "run". The strings can be any octet strings.	537	to "run". The strings can be any octet strings.
437		538
438	The protocol is optimised to pass a moderate number of relatively	539	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	540	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	541	is more meant to pass some ID information or other startup info, not
441	big chunks of data.	542	big chunks of data.
442		543
443	Returns the process object for easy chaining of method calls.	544	Returns the process object for easy chaining of method calls.
444		545
445	$proc->run ($func, $cb->($fh))	546	$proc->run ($func, $cb->($fh))
446
447	Enter the function specified by the function name in $func in the	547	Enter the function specified by the function name in $func in the
448	process. The function is called with the communication socket as	548	process. The function is called with the communication socket as
449	first argument, followed by all file handles and string arguments	549	first argument, followed by all file handles and string arguments
450	sent earlier via "send_fh" and "send_arg" methods, in the order they	550	sent earlier via "send_fh" and "send_arg" methods, in the order they
451	were called.	551	were called.
…		…
472		572
473	Even if not used otherwise, the socket can be a good indicator for	573	Even if not used otherwise, the socket can be a good indicator for
474	the existence of the process - if the other process exits, you get a	574	the existence of the process - if the other process exits, you get a
475	readable event on it, because exiting the process closes the socket	575	readable event on it, because exiting the process closes the socket
476	(if it didn't create any children using fork).	576	(if it didn't create any children using fork).
		577
		578	Compatibility to AnyEvent::Fork::Remote
		579	If you want to write code that works with both this module and
		580	AnyEvent::Fork::Remote, you need to write your code so that it
		581	assumes there are two file handles for communications, which
		582	might not be unix domain sockets. The "run" function should
		583	start like this:
		584
		585	sub run {
		586	my ($rfh, @args) = @_; # @args is your normal arguments
		587	my $wfh = fileno $rfh ? $rfh : *STDOUT;
		588
		589	# now use $rfh for reading and $wfh for writing
		590	}
		591
		592	This checks whether the passed file handle is, in fact, the
		593	process "STDIN" handle. If it is, then the function was invoked
		594	visa AnyEvent::Fork::Remote, so STDIN should be used for reading
		595	and "STDOUT" should be used for writing.
		596
		597	In all other cases, the function was called via this module, and
		598	there is only one file handle that should be sued for reading
		599	and writing.
477		600
478	Example: create a template for a process pool, pass a few strings,	601	Example: create a template for a process pool, pass a few strings,
479	some file handles, then fork, pass one more string, and run some	602	some file handles, then fork, pass one more string, and run some
480	code.	603	code.
481		604
…		…
505	my ($fh, $str1, $str2, $fh1, $fh2, $str3) = @_;	628	my ($fh, $str1, $str2, $fh1, $fh2, $str3) = @_;
506		629
507	print scalar <$fh>; # prints "hi #1\n" and "hi #2\n" in any order	630	print scalar <$fh>; # prints "hi #1\n" and "hi #2\n" in any order
508	}	631	}
509		632
		633	EXPERIMENTAL METHODS
		634	These methods might go away completely or change behaviour, at any time.
		635
		636	$proc->to_fh ($cb->($fh)) # EXPERIMENTAL, MIGHT BE REMOVED
		637	Flushes all commands out to the process and then calls the callback
		638	with the communications socket.
		639
		640	The process object becomes unusable on return from this function -
		641	any further method calls result in undefined behaviour.
		642
		643	The point of this method is to give you a file handle that you can
		644	pass to another process. In that other process, you can call
		645	"new_from_fh AnyEvent::Fork $fh" to create a new "AnyEvent::Fork"
		646	object from it, thereby effectively passing a fork object to another
		647	process.
		648
		649	new_from_fh AnyEvent::Fork $fh # EXPERIMENTAL, MIGHT BE REMOVED
		650	Takes a file handle originally rceeived by the "to_fh" method and
		651	creates a new "AnyEvent:Fork" object. The child process itself will
		652	not change in any way, i.e. it will keep all the modifications done
		653	to it before calling "to_fh".
		654
		655	The new object is very much like the original object, except that
		656	the "pid" method will return "undef" even if the process is a direct
		657	child.
		658
510	PERFORMANCE	659	PERFORMANCE
511	Now for some unscientific benchmark numbers (all done on an amd64	660	Now for some unscientific benchmark numbers (all done on an amd64
512	GNU/Linux box). These are intended to give you an idea of the relative	661	GNU/Linux box). These are intended to give you an idea of the relative
513	performance you can expect, they are not meant to be absolute	662	performance you can expect, they are not meant to be absolute
514	performance numbers.	663	performance numbers.
…		…
520		669
521	2079 new processes per second, using manual socketpair + fork	670	2079 new processes per second, using manual socketpair + fork
522		671
523	Then I did the same thing, but instead of calling fork, I called	672	Then I did the same thing, but instead of calling fork, I called
524	AnyEvent::Fork->new->run ("CORE::exit") and then again waited for the	673	AnyEvent::Fork->new->run ("CORE::exit") and then again waited for the
525	socket form the child to close on exit. This does the same thing as	674	socket from the child to close on exit. This does the same thing as
526	manual socket pair + fork, except that what is forked is the template	675	manual socket pair + fork, except that what is forked is the template
527	process (2440kB), and the socket needs to be passed to the server at the	676	process (2440kB), and the socket needs to be passed to the server at the
528	other end of the socket first.	677	other end of the socket first.
529		678
530	2307 new processes per second, using AnyEvent::Fork->new	679	2307 new processes per second, using AnyEvent::Fork->new
…		…
537	So how can "AnyEvent->new" be faster than a standard fork, even though	686	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?	687	it uses the same operations, but adds a lot of overhead?
539		688
540	The difference is simply the process size: forking the 5MB process takes	689	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	690	so much longer than forking the 2.5MB template process that the extra
542	overhead introduced is canceled out.	691	overhead is canceled out.
543		692
544	If the benchmark process grows, the normal fork becomes even slower:	693	If the benchmark process grows, the normal fork becomes even slower:
545		694
546	1340 new processes, manual fork of a 20MB process	695	1340 new processes, manual fork of a 20MB process
547	731 new processes, manual fork of a 200MB process	696	731 new processes, manual fork of a 200MB process
…		…
603	AnyEvent::Fork::Early or AnyEvent::Fork::Template, or to delay	752	AnyEvent::Fork::Early or AnyEvent::Fork::Template, or to delay
604	initialising them, for example, by calling "init Gtk2" manually.	753	initialising them, for example, by calling "init Gtk2" manually.
605		754
606	exiting calls object destructors	755	exiting calls object destructors
607	This only applies to users of AnyEvent::Fork:Early and	756	This only applies to users of AnyEvent::Fork:Early and
608	AnyEvent::Fork::Template, or when initialiasing code creates objects	757	AnyEvent::Fork::Template, or when initialising code creates objects
609	that reference external resources.	758	that reference external resources.
610		759
611	When a process created by AnyEvent::Fork exits, it might do so by	760	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.	761	calling exit, or simply letting perl reach the end of the program.
613	At which point Perl runs all destructors.	762	At which point Perl runs all destructors.
…		…
630	and sweat to make it so, mostly due to the bloody broken perl that	779	and sweat to make it so, mostly due to the bloody broken perl that
631	nobody seems to care about. The fork emulation is a bad joke - I have	780	nobody seems to care about. The fork emulation is a bad joke - I have
632	yet to see something useful that you can do with it without running into	781	yet to see something useful that you can do with it without running into
633	memory corruption issues or other braindamage. Hrrrr.	782	memory corruption issues or other braindamage. Hrrrr.
634		783
		784	Since fork is endlessly broken on win32 perls (it doesn't even remotely
		785	work within it's documented limits) and quite obviously it's not getting
		786	improved any time soon, the best way to proceed on windows would be to
		787	always use "new_exec" and thus never rely on perl's fork "emulation".
		788
635	Cygwin perl is not supported at the moment due to some hilarious	789	Cygwin perl is not supported at the moment due to some hilarious
636	shortcomings of its API - see IO::FDPoll for more details.	790	shortcomings of its API - see IO::FDPoll for more details. If you never
		791	use "send_fh" and always use "new_exec" to create processes, it should
		792	work though.
		793
		794	USING AnyEvent::Fork IN SUBPROCESSES
		795	AnyEvent::Fork itself cannot generally be used in subprocesses. As long
		796	as only one process ever forks new processes, sharing the template
		797	processes is possible (you could use a pipe as a lock by writing a byte
		798	into it to unlock, and reading the byte to lock for example)
		799
		800	To make concurrent calls possible after fork, you should get rid of the
		801	template and early fork processes. AnyEvent::Fork will create a new
		802	template process as needed.
		803
		804	undef $AnyEvent::Fork::EARLY;
		805	undef $AnyEvent::Fork::TEMPLATE;
		806
		807	It doesn't matter whether you get rid of them in the parent or child
		808	after a fork.
637		809
638	SEE ALSO	810	SEE ALSO
639	AnyEvent::Fork::Early (to avoid executing a perl interpreter),	811	AnyEvent::Fork::Early, to avoid executing a perl interpreter at all
		812	(part of this distribution).
		813
640	AnyEvent::Fork::Template (to create a process by forking the main	814	AnyEvent::Fork::Template, to create a process by forking the main
641	program at a convenient time).	815	program at a convenient time (part of this distribution).
642		816
643	AUTHOR	817	AnyEvent::Fork::Remote, for another way to create processes that is
		818	mostly compatible to this module and modules building on top of it, but
		819	works better with remote processes.
		820
		821	AnyEvent::Fork::RPC, for simple RPC to child processes (on CPAN).
		822
		823	AnyEvent::Fork::Pool, for simple worker process pool (on CPAN).
		824
		825	AUTHOR AND CONTACT INFORMATION
644	Marc Lehmann <schmorp@schmorp.de>	826	Marc Lehmann <schmorp@schmorp.de>
645	http://home.schmorp.de/	827	http://software.schmorp.de/pkg/AnyEvent-Fork
646		828
647	POD 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

Comparing AnyEvent-Fork/README (file contents): Revision 1.5 by root, Sat Apr 6 22:41:56 2013 UTC vs. Revision 1.10 by root, Thu May 12 16:54:01 2016 UTC

Diff Legend

Comparing AnyEvent-Fork/README (file contents):
Revision 1.5 by root, Sat Apr 6 22:41:56 2013 UTC vs.
Revision 1.10 by root, Thu May 12 16:54:01 2016 UTC