Coro
view release on metacpan or search on metacpan
objects - speeds up everything a bit.
- implement Coro->cancel in XS for a 20% speed improvement, and to
be able to implement mutual cancellation.
- speed up context switches by a percent or two by more efficiently
allocating context stack entries.
- implement Coro->join and Coro->on_destroy in XS for a speedup and
a reduction in memory use.
- cancelling a coro while it itself is cancelling another coro is
now supported and working, instead of triggering an assertion.
- be a bit more crash-resistant when calling (buggy) on_destroy
callbacks (best effort).
- move on_destroy into the slf_frame, to allow extension slf
functions to have destructors.
- get rid if coro refcounting - simply crash in other interpreter
threads by nulling the pointers on clone.
- simplify warn/die hook handling when loading Coro - the convoluted
logic seems to be no longer neccessary.
- use libecb instead of our own home-grown gcc hacks.
- document alternatives to Coro::LWP. Please use them :)
- work around another mindless idiotic NEEDLESS bug in openbsd/mirbsds
sigaltstack. Really. wine suffers from it, erlang suffers from it,
- export rouse_cb and rouse_wait by default now.
- fix various prototype mismatches in Coro::AnyEvent and Coro::Handle.
- new method $state->swap_sv.
- added section on "windows process emulation" to the manpage,
after a not-so-fruitful (nor-friendly) "discussion" with chip
salzenberg (discussion implies arguments, but his only arguments
were ad-hominems, one wonders why he started it in the first
place). I hope this explains it well enough for him to understand,
and maybe well enough for others to understand.
- use common::sense everywhere now.
- idle callbacks are no longer supported, use idle coros instead.
- print a thread listing when a deadlock is detected.
5.17 Sat Aug 22 23:09:31 CEST 2009
- work around a bug in the perl debugger causing crashes
when running under the debugger by marking _pool_handler as nodebug.
- speed up Coro::async considerably.
- try some hacks to get netbsd to work "more often" - their broken
setjmp/longjmp, ucontext *and* phtreads are really hard on Coro.
- convert Coro to AE 5.0 API.
correct, but mostly allows sharing of cctxs between coro and state
objects, for added memory savings and speed increases.
- bumped $Coro::POOL_RSS up to 32kb by default.
- no longer set the optype to OP_CUSTOM, as B::* understandably
doesn't like this very much (and we *are* a type of entersub).
- implement state cloning, just to prove that call/cc can be done.
- automatically load Coro::AnyEvent in Coro::Handle.
- wrap ->cancel calls in eval inside Coro::Handle as EV watchers
do not have this method (and don't need it either).
- speed up generic anyevent methods in Coro::Handle by using rouse
callbacks.
- allow coroutines in $Coro::IDLE, speeding up Coro::AnyEvent and
others. It also makes the debugger happier, as you can trace
through the idle threads now.
- add comppad_name* and hints ($^H, %^H) to per-thread variables.
- eg/event was pretty broken.
- better 5.8.6 compatibility.
5.0 Thu Nov 20 10:35:05 CET 2008
- NEW ARCHITECTURE: use the latest 4.x version if you experience
stability issues.
thus waking you up.
This makes C<schedule> I<the> generic method to use to block the current
coro and wait for events: first you remember the current coro in
a variable, then arrange for some callback of yours to call C<< ->ready
>> on that once some event happens, and last you call C<schedule> to put
yourself to sleep. Note that a lot of things can wake your coro up,
so you need to check whether the event indeed happened, e.g. by storing the
status in a variable.
See B<HOW TO WAIT FOR A CALLBACK>, below, for some ways to wait for callbacks.
=item cede
"Cede" to other coros. This function puts the current coro into
the ready queue and calls C<schedule>, which has the effect of giving
up the current "timeslice" to other coros of the same or higher
priority. Once your coro gets its turn again it will automatically be
resumed.
This function is often called C<yield> in other languages.
from multiple threads, and all will be resumed and given the status
return once the C<$coro> terminates.
=item $coro->on_destroy (\&cb)
Registers a callback that is called when this coro thread gets destroyed,
that is, after it's resources have been freed but before it is joined. The
callback gets passed the terminate/cancel arguments, if any, and I<must
not> die, under any circumstances.
There can be any number of C<on_destroy> callbacks per coro, and there is
currently no way to remove a callback once added.
=item $oldprio = $coro->prio ($newprio)
Sets (or gets, if the argument is missing) the priority of the
coro thread. Higher priority coro get run before lower priority
coros. Priorities are small signed integers (currently -4 .. +3),
that you can refer to using PRIO_xxx constants (use the import tag :prio
to get then):
=item unblock_sub { ... }
This utility function takes a BLOCK or code reference and "unblocks" it,
returning a new coderef. Unblocking means that calling the new coderef
will return immediately without blocking, returning nothing, while the
original code ref will be called (with parameters) from within another
coro.
The reason this function exists is that many event libraries (such as
the venerable L<Event|Event> module) are not thread-safe (a weaker form
of reentrancy). This means you must not block within event callbacks,
otherwise you might suffer from crashes or worse. The only event library
currently known that is safe to use without C<unblock_sub> is L<EV> (but
you might still run into deadlocks if all event loops are blocked).
Coro will try to catch you when you block in the event loop
("FATAL: $Coro::idle blocked itself"), but this is just best effort and
only works when you do not run your own event loop.
This function allows your callbacks to block by executing them in another
coro where it is safe to block. One example where blocking is handy
is when you use the L<Coro::AIO|Coro::AIO> functions to save results to
disk, for example.
In short: simply use C<unblock_sub { ... }> instead of C<sub { ... }> when
creating event callbacks that want to block.
If your handler does not plan to block (e.g. simply sends a message to
another coro, or puts some other coro into the ready queue), there is
no reason to use C<unblock_sub>.
Note that you also need to use C<unblock_sub> for any other callbacks that
are indirectly executed by any C-based event loop. For example, when you
use a module that uses L<AnyEvent> (and you use L<Coro::AnyEvent>) and it
provides callbacks that are the result of some event callback, then you
must not block either, or use C<unblock_sub>.
=cut
our @unblock_queue;
# we create a special coro because we want to cede,
# to reduce pressure on the coro pool (because most callbacks
# return immediately and can be reused) and because we cannot cede
# inside an event callback.
our $unblock_scheduler = new Coro sub {
while () {
while (my $cb = pop @unblock_queue) {
&async_pool (@$cb);
# for short-lived callbacks, this reduces pressure on the coro pool
# as the chance is very high that the async_poll coro will be back
# in the idle state when cede returns
cede;
}
schedule; # sleep well
}
};
$unblock_scheduler->{desc} = "[unblock_sub scheduler]";
sub unblock_sub(&) {
Coro/AIO.pm view on Meta::CPAN
the functions that expect a callback are being wrapped by this module.
The API is exactly the same as that of the corresponding IO::AIO
routines, except that you have to specify I<all> arguments, even the
ones optional in IO::AIO, I<except> the callback argument. Instead of
calling a callback, the routines return the values normally passed to the
callback. Everything else, including C<$!> and perls stat cache, are set
as expected after these functions return.
You can mix calls to C<IO::AIO> functions with calls to this module. You
I<must not>, however, call these routines from within IO::AIO callbacks,
as this causes a deadlock. Start a coro inside the callback instead.
This module also loads L<AnyEvent::AIO> to integrate into the event loop
in use, so please refer to its (and L<AnyEvent>'s) documentation on how it
selects an appropriate event module.
All other functions exported by default by IO::AIO (e.g. C<aioreq_pri>)
will be exported by default by Coro::AIO, too.
Functions that can be optionally imported from IO::AIO can be imported
Coro/AnyEvent.pm view on Meta::CPAN
=item * lead to data corruption or worse
As C<unblock_sub> cannot be used by this module (as it is the module
that implements it, basically), you must not call into the event
loop recursively from any coroutine. This is not usually a difficult
restriction to live with, just use condvars, C<unblock_sub> or other means
of inter-coroutine-communications.
If you use a module that supports AnyEvent (or uses the same event
loop as AnyEvent, making it implicitly compatible), and it offers
callbacks of any kind, then you must not block in them, either (or use
e.g. C<unblock_sub>), see the description of C<unblock_sub> in the
L<Coro> module.
This also means that you should load the module as early as possible,
as only condvars created after this module has been loaded will work
correctly.
=back
=head1 SEE ALSO
Coro/Intro.pod view on Meta::CPAN
use AnyEvent::HTTP;
# do not pass control for long - http_get immediately returns
http_get "http://example.org/", sub {
print $_[0];
};
# we stay in control and can do other things
Event based programming can be nice, but sometimes it's just easier to
write down some processing in "linear" fashion, without callbacks. Coro
provides some special functions to reduce typing:
use AnyEvent::HTTP;
# do not pass control for long - http_get immediately returns
http_get "http://example.org/", Coro::rouse_cb;
# we stay in control and can do other things...
# ...such as wait for the result
my ($res) = Coro::rouse_wait;
Coro/State.xs view on Meta::CPAN
int flags; /* CF_ flags */
HV *hv; /* the perl hash associated with this coro, if any */
/* statistics */
int usecount; /* number of transfers to this coro */
/* coro process data */
int prio;
SV *except; /* exception to be thrown */
SV *rouse_cb; /* last rouse callback */
AV *on_destroy; /* callbacks or coros to notify on destroy */
AV *status; /* the exit status list */
/* async_pool */
SV *saved_deffh;
SV *invoke_cb;
AV *invoke_av;
/* on_enter/on_leave */
AV *on_enter; AV *on_enter_xs;
AV *on_leave; AV *on_leave_xs;
Event/Event.pm view on Meta::CPAN
Your application should just create all necessary threads and then call
C<Event::loop>.
Please note that even programs or modules (such as L<Coro::Handle>) that
use "traditional" event-based/continuation style will run more efficient
with this module then when using only Event.
=head1 WARNING
Please note that Event does not support multithreading. That means that
you B<MUST NOT> block in an event callback. Again: In Event callbacks,
you I<must never ever> call a Coro function that blocks the current
thread.
While this seems to work superficially, it will eventually cause memory
corruption and often results in deadlocks.
Best practise is to always use B<Coro::unblock_sub> for your callbacks.
=head1 SEMANTICS
Whenever Event blocks (e.g. in a call to C<one_event>, C<loop> etc.),
this module cede's to all other threads with the same or higher
priority. When any threads of lower priority are ready, it will not
block but run one of them and then check for events.
The effect is that coroutines with the same or higher priority than
the blocking coroutine will keep Event from checking for events, while
This makes "schedule" *the* generic method to use to block the
current coro and wait for events: first you remember the current
coro in a variable, then arrange for some callback of yours to call
"->ready" on that once some event happens, and last you call
"schedule" to put yourself to sleep. Note that a lot of things can
wake your coro up, so you need to check whether the event indeed
happened, e.g. by storing the status in a variable.
See HOW TO WAIT FOR A CALLBACK, below, for some ways to wait for
callbacks.
cede
"Cede" to other coros. This function puts the current coro into the
ready queue and calls "schedule", which has the effect of giving up
the current "timeslice" to other coros of the same or higher
priority. Once your coro gets its turn again it will automatically
be resumed.
This function is often called "yield" in other languages.
"terminate" or "cancel" functions. "join" can be called concurrently
from multiple threads, and all will be resumed and given the status
return once the $coro terminates.
$coro->on_destroy (\&cb)
Registers a callback that is called when this coro thread gets
destroyed, that is, after it's resources have been freed but before
it is joined. The callback gets passed the terminate/cancel
arguments, if any, and *must not* die, under any circumstances.
There can be any number of "on_destroy" callbacks per coro, and
there is currently no way to remove a callback once added.
$oldprio = $coro->prio ($newprio)
Sets (or gets, if the argument is missing) the priority of the coro
thread. Higher priority coro get run before lower priority coros.
Priorities are small signed integers (currently -4 .. +3), that you
can refer to using PRIO_xxx constants (use the import tag :prio to
get then):
PRIO_MAX > PRIO_HIGH > PRIO_NORMAL > PRIO_LOW > PRIO_IDLE > PRIO_MIN
unblock_sub { ... }
This utility function takes a BLOCK or code reference and "unblocks"
it, returning a new coderef. Unblocking means that calling the new
coderef will return immediately without blocking, returning nothing,
while the original code ref will be called (with parameters) from
within another coro.
The reason this function exists is that many event libraries (such
as the venerable Event module) are not thread-safe (a weaker form of
reentrancy). This means you must not block within event callbacks,
otherwise you might suffer from crashes or worse. The only event
library currently known that is safe to use without "unblock_sub" is
EV (but you might still run into deadlocks if all event loops are
blocked).
Coro will try to catch you when you block in the event loop ("FATAL:
$Coro::idle blocked itself"), but this is just best effort and only
works when you do not run your own event loop.
This function allows your callbacks to block by executing them in
another coro where it is safe to block. One example where blocking
is handy is when you use the Coro::AIO functions to save results to
disk, for example.
In short: simply use "unblock_sub { ... }" instead of "sub { ... }"
when creating event callbacks that want to block.
If your handler does not plan to block (e.g. simply sends a message
to another coro, or puts some other coro into the ready queue),
there is no reason to use "unblock_sub".
Note that you also need to use "unblock_sub" for any other callbacks
that are indirectly executed by any C-based event loop. For example,
when you use a module that uses AnyEvent (and you use
Coro::AnyEvent) and it provides callbacks that are the result of
some event callback, then you must not block either, or use
"unblock_sub".
$cb = rouse_cb
Create and return a "rouse callback". That's a code reference that,
when called, will remember a copy of its arguments and notify the
owner coro of the callback.
See the next function.
( run in 1.548 second using v1.01-cache-2.11-cpan-9b1e4054eb1 )