[ViewVC] Diff of: cvs/cvsroot/Coro/Coro.pm

Comparing cvsroot/Coro/Coro.pm (file contents):
Revision 1.267 by root, Wed Aug 26 08:14:09 2009 UTC vs.
Revision 1.282 by root, Sun Dec 26 16:23:51 2010 UTC

…		…
67		67
68	=cut	68	=cut
69		69
70	package Coro;	70	package Coro;
71		71
72	use strict qw(vars subs);	72	use common::sense;
73	no warnings "uninitialized";	73
		74	use Carp ();
74		75
75	use Guard ();	76	use Guard ();
76		77
77	use Coro::State;	78	use Coro::State;
78		79
…		…
80		81
81	our $idle; # idle handler	82	our $idle; # idle handler
82	our $main; # main coro	83	our $main; # main coro
83	our $current; # current coro	84	our $current; # current coro
84		85
85	our $VERSION = 5.17;	86	our $VERSION = 5.25;
86		87
87	our @EXPORT = qw(async async_pool cede schedule terminate current unblock_sub);	88	our @EXPORT = qw(async async_pool cede schedule terminate current unblock_sub rouse_cb rouse_wait);
88	our %EXPORT_TAGS = (	89	our %EXPORT_TAGS = (
89	prio => [qw(PRIO_MAX PRIO_HIGH PRIO_NORMAL PRIO_LOW PRIO_IDLE PRIO_MIN)],	90	prio => [qw(PRIO_MAX PRIO_HIGH PRIO_NORMAL PRIO_LOW PRIO_IDLE PRIO_MIN)],
90	);	91	);
91	our @EXPORT_OK = (@{$EXPORT_TAGS{prio}}, qw(nready));	92	our @EXPORT_OK = (@{$EXPORT_TAGS{prio}}, qw(nready));
92		93
…		…
123		124
124	This variable is mainly useful to integrate Coro into event loops. It is	125	This variable is mainly useful to integrate Coro into event loops. It is
125	usually better to rely on L<Coro::AnyEvent> or L<Coro::EV>, as this is	126	usually better to rely on L<Coro::AnyEvent> or L<Coro::EV>, as this is
126	pretty low-level functionality.	127	pretty low-level functionality.
127		128
128	This variable stores either a Coro object or a callback.	129	This variable stores a Coro object that is put into the ready queue when
		130	there are no other ready threads (without invoking any ready hooks).
129		131
130	If it is a callback, the it is called whenever the scheduler finds no	132	The default implementation dies with "FATAL: deadlock detected.", followed
131	ready coros to run. The default implementation prints "FATAL:	133	by a thread listing, because the program has no other way to continue.
132	deadlock detected" and exits, because the program has no other way to
133	continue.
134
135	If it is a coro object, then this object will be readied (without
136	invoking any ready hooks, however) when the scheduler finds no other ready
137	coros to run.
138		134
139	This hook is overwritten by modules such as C<Coro::EV> and	135	This hook is overwritten by modules such as C<Coro::EV> and
140	C<Coro::AnyEvent> to wait on an external event that hopefully wake up a	136	C<Coro::AnyEvent> to wait on an external event that hopefully wake up a
141	coro so the scheduler can run it.	137	coro so the scheduler can run it.
142		138
143	Note that the callback I<must not>, under any circumstances, block
144	the current coro. Normally, this is achieved by having an "idle
145	coro" that calls the event loop and then blocks again, and then
146	readying that coro in the idle handler, or by simply placing the idle
147	coro in this variable.
148
149	See L<Coro::Event> or L<Coro::AnyEvent> for examples of using this	139	See L<Coro::EV> or L<Coro::AnyEvent> for examples of using this technique.
150	technique.
151		140
152	Please note that if your callback recursively invokes perl (e.g. for event
153	handlers), then it must be prepared to be called recursively itself.
154
155	=cut	141	=cut
156		142
157	$idle = sub {	143	# \|\|= because other modules could have provided their own by now
158	require Carp;	144	$idle \|\|= new Coro sub {
159	Carp::croak ("FATAL: deadlock detected");	145	require Coro::Debug;
		146	die "FATAL: deadlock detected.\n"
		147	. Coro::Debug::ps_listing ();
160	};	148	};
161		149
162	# this coro is necessary because a coro	150	# this coro is necessary because a coro
163	# cannot destroy itself.	151	# cannot destroy itself.
164	our @destroy;	152	our @destroy;
…		…
272	=item schedule	260	=item schedule
273		261
274	Calls the scheduler. The scheduler will find the next coro that is	262	Calls the scheduler. The scheduler will find the next coro that is
275	to be run from the ready queue and switches to it. The next coro	263	to be run from the ready queue and switches to it. The next coro
276	to be run is simply the one with the highest priority that is longest	264	to be run is simply the one with the highest priority that is longest
277	in its ready queue. If there is no coro ready, it will clal the	265	in its ready queue. If there is no coro ready, it will call the
278	C<$Coro::idle> hook.	266	C<$Coro::idle> hook.
279		267
280	Please note that the current coro will I<not> be put into the ready	268	Please note that the current coro will I<not> be put into the ready
281	queue, so calling this function usually means you will never be called	269	queue, so calling this function usually means you will never be called
282	again unless something else (e.g. an event handler) calls C<< ->ready >>,	270	again unless something else (e.g. an event handler) calls C<< ->ready >>,
…		…
625	Sets (or gets in case the argument is missing) the description for this	613	Sets (or gets in case the argument is missing) the description for this
626	coro. This is just a free-form string you can associate with a	614	coro. This is just a free-form string you can associate with a
627	coro.	615	coro.
628		616
629	This method simply sets the C<< $coro->{desc} >> member to the given	617	This method simply sets the C<< $coro->{desc} >> member to the given
630	string. You can modify this member directly if you wish.	618	string. You can modify this member directly if you wish, and in fact, this
		619	is often preferred to indicate major processing states that cna then be
		620	seen for example in a L<Coro::Debug> session:
		621
		622	sub my_long_function {
		623	local $Coro::current->{desc} = "now in my_long_function";
		624	...
		625	$Coro::current->{desc} = "my_long_function: phase 1";
		626	...
		627	$Coro::current->{desc} = "my_long_function: phase 2";
		628	...
		629	}
631		630
632	=cut	631	=cut
633		632
634	sub desc {	633	sub desc {
635	my $old = $_[0]{desc};	634	my $old = $_[0]{desc};
…		…
672	returning a new coderef. Unblocking means that calling the new coderef	671	returning a new coderef. Unblocking means that calling the new coderef
673	will return immediately without blocking, returning nothing, while the	672	will return immediately without blocking, returning nothing, while the
674	original code ref will be called (with parameters) from within another	673	original code ref will be called (with parameters) from within another
675	coro.	674	coro.
676		675
677	The reason this function exists is that many event libraries (such as the	676	The reason this function exists is that many event libraries (such as
678	venerable L<Event\|Event> module) are not thread-safe (a weaker form	677	the venerable L<Event\|Event> module) are not thread-safe (a weaker form
679	of reentrancy). This means you must not block within event callbacks,	678	of reentrancy). This means you must not block within event callbacks,
680	otherwise you might suffer from crashes or worse. The only event library	679	otherwise you might suffer from crashes or worse. The only event library
681	currently known that is safe to use without C<unblock_sub> is L<EV>.	680	currently known that is safe to use without C<unblock_sub> is L<EV> (but
		681	you might still run into deadlocks if all event loops are blocked).
		682
		683	Coro will try to catch you when you block in the event loop
		684	("FATAL:$Coro::IDLE blocked itself"), but this is just best effort and
		685	only works when you do not run your own event loop.
682		686
683	This function allows your callbacks to block by executing them in another	687	This function allows your callbacks to block by executing them in another
684	coro where it is safe to block. One example where blocking is handy	688	coro where it is safe to block. One example where blocking is handy
685	is when you use the L<Coro::AIO\|Coro::AIO> functions to save results to	689	is when you use the L<Coro::AIO\|Coro::AIO> functions to save results to
686	disk, for example.	690	disk, for example.
…		…
728	unshift @unblock_queue, [$cb, @_];	732	unshift @unblock_queue, [$cb, @_];
729	$unblock_scheduler->ready;	733	$unblock_scheduler->ready;
730	}	734	}
731	}	735	}
732		736
733	=item $cb = Coro::rouse_cb	737	=item $cb = rouse_cb
734		738
735	Create and return a "rouse callback". That's a code reference that,	739	Create and return a "rouse callback". That's a code reference that,
736	when called, will remember a copy of its arguments and notify the owner	740	when called, will remember a copy of its arguments and notify the owner
737	coro of the callback.	741	coro of the callback.
738		742
739	See the next function.	743	See the next function.
740		744
741	=item @args = Coro::rouse_wait [$cb]	745	=item @args = rouse_wait [$cb]
742		746
743	Wait for the specified rouse callback (or the last one that was created in	747	Wait for the specified rouse callback (or the last one that was created in
744	this coro).	748	this coro).
745		749
746	As soon as the callback is invoked (or when the callback was invoked	750	As soon as the callback is invoked (or when the callback was invoked
…		…
843	the windows process emulation enabled under unix roughly halves perl	847	the windows process emulation enabled under unix roughly halves perl
844	performance, even when not used.	848	performance, even when not used.
845		849
846	=item coro switching is not signal safe	850	=item coro switching is not signal safe
847		851
848	You must not switch to another coro from within a signal handler	852	You must not switch to another coro from within a signal handler (only
849	(only relevant with %SIG - most event libraries provide safe signals).	853	relevant with %SIG - most event libraries provide safe signals), I<unless>
		854	you are sure you are not interrupting a Coro function.
850		855
851	That means you I<MUST NOT> call any function that might "block" the	856	That means you I<MUST NOT> call any function that might "block" the
852	current coro - C<cede>, C<schedule> C<< Coro::Semaphore->down >> or	857	current coro - C<cede>, C<schedule> C<< Coro::Semaphore->down >> or
853	anything that calls those. Everything else, including calling C<ready>,	858	anything that calls those. Everything else, including calling C<ready>,
854	works.	859	works.
…		…
864	ithreads (for example, that memory or files would be shared), showing his	869	ithreads (for example, that memory or files would be shared), showing his
865	lack of understanding of this area - if it is hard to understand for Chip,	870	lack of understanding of this area - if it is hard to understand for Chip,
866	it is probably not obvious to everybody).	871	it is probably not obvious to everybody).
867		872
868	What follows is an ultra-condensed version of my talk about threads in	873	What follows is an ultra-condensed version of my talk about threads in
869	scripting languages given onthe perl workshop 2009:	874	scripting languages given on the perl workshop 2009:
870		875
871	The so-called "ithreads" were originally implemented for two reasons:	876	The so-called "ithreads" were originally implemented for two reasons:
872	first, to (badly) emulate unix processes on native win32 perls, and	877	first, to (badly) emulate unix processes on native win32 perls, and
873	secondly, to replace the older, real thread model ("5.005-threads").	878	secondly, to replace the older, real thread model ("5.005-threads").
874		879

Diff Legend

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

Comparing cvsroot/Coro/Coro.pm (file contents): Revision 1.267 by root, Wed Aug 26 08:14:09 2009 UTC vs. Revision 1.282 by root, Sun Dec 26 16:23:51 2010 UTC

Diff Legend

Comparing cvsroot/Coro/Coro.pm (file contents):
Revision 1.267 by root, Wed Aug 26 08:14:09 2009 UTC vs.
Revision 1.282 by root, Sun Dec 26 16:23:51 2010 UTC