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

Comparing Coro/Coro.pm (file contents):
Revision 1.206 by root, Thu Oct 30 09:57:00 2008 UTC vs.
Revision 1.220 by root, Sun Nov 16 11:12:57 2008 UTC

… …
56 56
57=cut 57=cut
58 58
59package Coro; 59package Coro;
60 60
61use strict; 61use strict qw(vars subs);
62no warnings "uninitialized"; 62no warnings "uninitialized";
63 63
64use Coro::State; 64use Coro::State;
65 65
66use base qw(Coro::State Exporter); 66use base qw(Coro::State Exporter);
67 67
68our $idle; # idle handler 68our $idle; # idle handler
69our $main; # main coroutine 69our $main; # main coroutine
70our $current; # current coroutine 70our $current; # current coroutine
71 71
72our $VERSION = 4.802; 72our $VERSION = 5.0;
73 73
74our @EXPORT = qw(async async_pool cede schedule terminate current unblock_sub); 74our @EXPORT = qw(async async_pool cede schedule terminate current unblock_sub);
75our %EXPORT_TAGS = ( 75our %EXPORT_TAGS = (
76 prio => [qw(PRIO_MAX PRIO_HIGH PRIO_NORMAL PRIO_LOW PRIO_IDLE PRIO_MIN)], 76 prio => [qw(PRIO_MAX PRIO_HIGH PRIO_NORMAL PRIO_LOW PRIO_IDLE PRIO_MIN)],
77); 77);
… …
86coroutines, it is mainly useful to compare again C<$Coro::current>, to see 86coroutines, it is mainly useful to compare again C<$Coro::current>, to see
87whether you are running in the main program or not. 87whether you are running in the main program or not.
88 88
89=cut 89=cut
90 90
91$main = new Coro; 91# $main is now being initialised by Coro::State
92 92
93=item $Coro::current 93=item $Coro::current
94 94
95The coroutine object representing the current coroutine (the last 95The coroutine object representing the current coroutine (the last
96coroutine that the Coro scheduler switched to). The initial value is 96coroutine that the Coro scheduler switched to). The initial value is
97C<$main> (of course). 97C<$Coro::main> (of course).
98 98
99This variable is B<strictly> I<read-only>. You can take copies of the 99This variable is B<strictly> I<read-only>. You can take copies of the
100value stored in it and use it as any other coroutine object, but you must 100value stored in it and use it as any other coroutine object, but you must
101not otherwise modify the variable itself. 101not otherwise modify the variable itself.
102 102
103=cut 103=cut
104
105$main->{desc} = "[main::]";
106
107# maybe some other module used Coro::Specific before...
108$main->{_specific} = $current->{_specific}
109 if $current;
110
111_set_current $main;
112 104
113sub current() { $current } # [DEPRECATED] 105sub current() { $current } # [DEPRECATED]
114 106
115=item $Coro::idle 107=item $Coro::idle
116 108
… …
152 $self->_destroy 144 $self->_destroy
153 or return; 145 or return;
154 146
155 # call all destruction callbacks 147 # call all destruction callbacks
156 $_->(@{$self->{_status}}) 148 $_->(@{$self->{_status}})
157 for @{(delete $self->{_on_destroy}) || []}; 149 for @{ delete $self->{_on_destroy} || [] };
158} 150}
159 151
160# this coroutine is necessary because a coroutine 152# this coroutine is necessary because a coroutine
161# cannot destroy itself. 153# cannot destroy itself.
162my @destroy; 154my @destroy;
… …
168 while @destroy; 160 while @destroy;
169 161
170 &schedule; 162 &schedule;
171 } 163 }
172}; 164};
173$manager->desc ("[coro manager]"); 165$manager->{desc} = "[coro manager]";
174$manager->prio (PRIO_MAX); 166$manager->prio (PRIO_MAX);
175 167
176=back 168=back
177 169
178=head2 SIMPLE COROUTINE CREATION 170=head2 SIMPLE COROUTINE CREATION
… …
275 } 267 }
276 } 268 }
277} 269}
278 270
279sub async_pool(&@) { 271sub async_pool(&@) {
280 # this is also inlined into the unlock_scheduler 272 # this is also inlined into the unblock_scheduler
281 my $coro = (pop @async_pool) || new Coro \&pool_handler; 273 my $coro = (pop @async_pool) || new Coro \&pool_handler;
282 274
283 $coro->{_invoke} = [@_]; 275 $coro->{_invoke} = [@_];
284 $coro->ready; 276 $coro->ready;
285 277
… …
441 } else { 433 } else {
442 $self->_cancel; 434 $self->_cancel;
443 } 435 }
444} 436}
445 437
438=item $coroutine->throw ([$scalar])
439
440If C<$throw> is specified and defined, it will be thrown as an exception
441inside the coroutine at the next convenient point in time (usually after
442it gains control at the next schedule/transfer/cede). Otherwise clears the
443exception object.
444
445The exception object will be thrown "as is" with the specified scalar in
446C<$@>, i.e. if it is a string, no line number or newline will be appended
447(unlike with C<die>).
448
449This can be used as a softer means than C<cancel> to ask a coroutine to
450end itself, although there is no guarantee that the exception will lead to
451termination, and if the exception isn't caught it might well end the whole
452program.
453
454You might also think of C<throw> as being the moral equivalent of
455C<kill>ing a coroutine with a signal (in this case, a scalar).
456
446=item $coroutine->join 457=item $coroutine->join
447 458
448Wait until the coroutine terminates and return any values given to the 459Wait until the coroutine terminates and return any values given to the
449C<terminate> or C<cancel> functions. C<join> can be called concurrently 460C<terminate> or C<cancel> functions. C<join> can be called concurrently
450from multiple coroutines, and all will be resumed and given the status 461from multiple coroutines, and all will be resumed and given the status
… …
511higher values mean lower priority, just as in unix). 522higher values mean lower priority, just as in unix).
512 523
513=item $olddesc = $coroutine->desc ($newdesc) 524=item $olddesc = $coroutine->desc ($newdesc)
514 525
515Sets (or gets in case the argument is missing) the description for this 526Sets (or gets in case the argument is missing) the description for this
516coroutine. This is just a free-form string you can associate with a coroutine. 527coroutine. This is just a free-form string you can associate with a
528coroutine.
517 529
518This method simply sets the C<< $coroutine->{desc} >> member to the given string. You 530This method simply sets the C<< $coroutine->{desc} >> member to the given
519can modify this member directly if you wish. 531string. You can modify this member directly if you wish.
520
521=item $coroutine->throw ([$scalar])
522
523If C<$throw> is specified and defined, it will be thrown as an exception
524inside the coroutine at the next convinient point in time (usually after
525it gains control at the next schedule/transfer/cede). Otherwise clears the
526exception object.
527
528The exception object will be thrown "as is" with the specified scalar in
529C<$@>, i.e. if it is a string, no line number or newline will be appended
530(unlike with C<die>).
531
532This can be used as a softer means than C<cancel> to ask a coroutine to
533end itself, although there is no guarentee that the exception will lead to
534termination, and if the exception isn't caught it might well end the whole
535program.
536 532
537=cut 533=cut
538 534
539sub desc { 535sub desc {
540 my $old = $_[0]{desc}; 536 my $old = $_[0]{desc};
… …
642 cede; # for short-lived callbacks, this reduces pressure on the coro pool 638 cede; # for short-lived callbacks, this reduces pressure on the coro pool
643 } 639 }
644 schedule; # sleep well 640 schedule; # sleep well
645 } 641 }
646}; 642};
647$unblock_scheduler->desc ("[unblock_sub scheduler]"); 643$unblock_scheduler->{desc} = "[unblock_sub scheduler]";
648 644
649sub unblock_sub(&) { 645sub unblock_sub(&) {
650 my $cb = shift; 646 my $cb = shift;
651 647
652 sub { 648 sub {
… …
661 657
6621; 6581;
663 659
664=head1 BUGS/LIMITATIONS 660=head1 BUGS/LIMITATIONS
665 661
662=over 4
663
664=item fork with pthread backend
665
666When Coro is compiled using the pthread backend (which isn't recommended
667but required on many BSDs as their libcs are completely broken), then
668coroutines will not survive a fork. There is no known workaround except to
669fix your libc and use a saner backend.
670
671=item perl process emulation ("threads")
672
666This module is not perl-pseudo-thread-safe. You should only ever use this 673This module is not perl-pseudo-thread-safe. You should only ever use this
667module from the same thread (this requirement might be removed in the 674module from the same thread (this requirement might be removed in the
668future to allow per-thread schedulers, but Coro::State does not yet allow 675future to allow per-thread schedulers, but Coro::State does not yet allow
669this). I recommend disabling thread support and using processes, as this 676this). I recommend disabling thread support and using processes, as having
670is much faster and uses less memory. 677the windows process emulation enabled under unix roughly halves perl
678performance, even when not used.
679
680=item coroutine switching not signal safe
681
682You must not switch to another coroutine from within a signal handler
683(only relevant with %SIG - most event libraries provide safe signals).
684
685That means you I<MUST NOT> call any fucntion that might "block" the
686current coroutine - C<cede>, C<schedule> C<< Coro::Semaphore->down >> or
687anything that calls those. Everything else, including calling C<ready>,
688works.
689
690=back
691
671 692
672=head1 SEE ALSO 693=head1 SEE ALSO
673 694
674Event-Loop integration: L<Coro::AnyEvent>, L<Coro::EV>, L<Coro::Event>. 695Event-Loop integration: L<Coro::AnyEvent>, L<Coro::EV>, L<Coro::Event>.
675 696

Diff Legend

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