ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/Coro/Coro.pm
(Generate patch)

Comparing Coro/Coro.pm (file contents):
Revision 1.122 by root, Sat Apr 14 15:06:05 2007 UTC vs.
Revision 1.128 by root, Wed Sep 19 21:39:15 2007 UTC

… …
20 20
21=head1 DESCRIPTION 21=head1 DESCRIPTION
22 22
23This module collection manages coroutines. Coroutines are similar 23This module collection manages coroutines. Coroutines are similar
24to threads but don't run in parallel at the same time even on SMP 24to threads but don't run in parallel at the same time even on SMP
25machines. The specific flavor of coroutine use din this module also 25machines. The specific flavor of coroutine used in this module also
26guarentees you that it will not switch between coroutines unless 26guarantees you that it will not switch between coroutines unless
27necessary, at easily-identified points in your program, so locking and 27necessary, at easily-identified points in your program, so locking and
28parallel access are rarely an issue, making coroutine programming much 28parallel access are rarely an issue, making coroutine programming much
29safer than threads programming. 29safer than threads programming.
30 30
31(Perl, however, does not natively support real threads but instead does a 31(Perl, however, does not natively support real threads but instead does a
… …
50 50
51our $idle; # idle handler 51our $idle; # idle handler
52our $main; # main coroutine 52our $main; # main coroutine
53our $current; # current coroutine 53our $current; # current coroutine
54 54
55our $VERSION = '3.56'; 55our $VERSION = '3.7';
56 56
57our @EXPORT = qw(async async_pool cede schedule terminate current unblock_sub); 57our @EXPORT = qw(async async_pool cede schedule terminate current unblock_sub);
58our %EXPORT_TAGS = ( 58our %EXPORT_TAGS = (
59 prio => [qw(PRIO_MAX PRIO_HIGH PRIO_NORMAL PRIO_LOW PRIO_IDLE PRIO_MIN)], 59 prio => [qw(PRIO_MAX PRIO_HIGH PRIO_NORMAL PRIO_LOW PRIO_IDLE PRIO_MIN)],
60); 60);
… …
108 108
109The current coroutine (the last coroutine switched to). The initial value 109The current coroutine (the last coroutine switched to). The initial value
110is C<$main> (of course). 110is C<$main> (of course).
111 111
112This variable is B<strictly> I<read-only>. It is provided for performance 112This variable is B<strictly> I<read-only>. It is provided for performance
113reasons. If performance is not essentiel you are encouraged to use the 113reasons. If performance is not essential you are encouraged to use the
114C<Coro::current> function instead. 114C<Coro::current> function instead.
115 115
116=cut 116=cut
117 117
118# maybe some other module used Coro::Specific before... 118# maybe some other module used Coro::Specific before...
… …
249 } 249 }
250} 250}
251 251
252sub async_pool(&@) { 252sub async_pool(&@) {
253 # this is also inlined into the unlock_scheduler 253 # this is also inlined into the unlock_scheduler
254 my $coro = (pop @pool) || do {
254 my $coro = (pop @pool or new Coro \&pool_handler); 255 my $coro = new Coro \&pool_handler;
256 $coro->{desc} = "async_pool";
257 $coro
258 };
255 259
256 $coro->{_invoke} = [@_]; 260 $coro->{_invoke} = [@_];
257 $coro->ready; 261 $coro->ready;
258 262
259 $coro 263 $coro
… …
277 # wake up sleeping coroutine 281 # wake up sleeping coroutine
278 $current->ready; 282 $current->ready;
279 undef $current; 283 undef $current;
280 }; 284 };
281 285
282 # call schedule until event occured. 286 # call schedule until event occurred.
283 # in case we are woken up for other reasons 287 # in case we are woken up for other reasons
284 # (current still defined), loop. 288 # (current still defined), loop.
285 Coro::schedule while $current; 289 Coro::schedule while $current;
286 } 290 }
287 291
… …
458=over 4 462=over 4
459 463
460=item Coro::nready 464=item Coro::nready
461 465
462Returns the number of coroutines that are currently in the ready state, 466Returns the number of coroutines that are currently in the ready state,
463i.e. that can be swicthed to. The value C<0> means that the only runnable 467i.e. that can be switched to. The value C<0> means that the only runnable
464coroutine is the currently running one, so C<cede> would have no effect, 468coroutine is the currently running one, so C<cede> would have no effect,
465and C<schedule> would cause a deadlock unless there is an idle handler 469and C<schedule> would cause a deadlock unless there is an idle handler
466that wakes up some coroutines. 470that wakes up some coroutines.
467 471
468=item my $guard = Coro::guard { ... } 472=item my $guard = Coro::guard { ... }
… …
504This utility function takes a BLOCK or code reference and "unblocks" it, 508This utility function takes a BLOCK or code reference and "unblocks" it,
505returning the new coderef. This means that the new coderef will return 509returning the new coderef. This means that the new coderef will return
506immediately without blocking, returning nothing, while the original code 510immediately without blocking, returning nothing, while the original code
507ref will be called (with parameters) from within its own coroutine. 511ref will be called (with parameters) from within its own coroutine.
508 512
509The reason this fucntion exists is that many event libraries (such as the 513The reason this function exists is that many event libraries (such as the
510venerable L<Event|Event> module) are not coroutine-safe (a weaker form 514venerable L<Event|Event> module) are not coroutine-safe (a weaker form
511of thread-safety). This means you must not block within event callbacks, 515of thread-safety). This means you must not block within event callbacks,
512otherwise you might suffer from crashes or worse. 516otherwise you might suffer from crashes or worse.
513 517
514This function allows your callbacks to block by executing them in another 518This function allows your callbacks to block by executing them in another
… …
560 564
561 - you must make very sure that no coro is still active on global 565 - you must make very sure that no coro is still active on global
562 destruction. very bad things might happen otherwise (usually segfaults). 566 destruction. very bad things might happen otherwise (usually segfaults).
563 567
564 - this module is not thread-safe. You should only ever use this module 568 - this module is not thread-safe. You should only ever use this module
565 from the same thread (this requirement might be losened in the future 569 from the same thread (this requirement might be loosened in the future
566 to allow per-thread schedulers, but Coro::State does not yet allow 570 to allow per-thread schedulers, but Coro::State does not yet allow
567 this). 571 this).
568 572
569=head1 SEE ALSO 573=head1 SEE ALSO
570 574

Diff Legend

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