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

Comparing Coro/Coro.pm (file contents):
Revision 1.229 by root, Thu Nov 20 06:32:55 2008 UTC vs.
Revision 1.237 by root, Sat Nov 22 16:37:11 2008 UTC

1=head1 NAME 1=head1 NAME
2 2
3Coro - coroutine process abstraction 3Coro - real threads in perl
4 4
5=head1 SYNOPSIS 5=head1 SYNOPSIS
6 6
7 use Coro; 7 use Coro;
8 8
… …
26 $locked = 1; 26 $locked = 1;
27 $lock->up; 27 $lock->up;
28 28
29=head1 DESCRIPTION 29=head1 DESCRIPTION
30 30
31This module collection manages coroutines. Coroutines are similar to 31For a tutorial-style introduction, please read the L<Coro::Intro>
32threads but don't (in general) run in parallel at the same time even 32manpage. This manpage mainly contains reference information.
33on SMP machines. The specific flavor of coroutine used in this module
34also guarantees you that it will not switch between coroutines unless
35necessary, at easily-identified points in your program, so locking and
36parallel access are rarely an issue, making coroutine programming much
37safer and easier than threads programming.
38 33
39Unlike a normal perl program, however, coroutines allow you to have 34This module collection manages coroutines, that is, cooperative
40multiple running interpreters that share data, which is especially useful 35threads. Coroutines are similar to kernel threads but don't (in general)
41to code pseudo-parallel processes and for event-based programming, such as 36run in parallel at the same time even on SMP machines. The specific flavor
42multiple HTTP-GET requests running concurrently. See L<Coro::AnyEvent> to 37of coroutine used in this module also guarantees you that it will not
43learn more. 38switch between coroutines unless necessary, at easily-identified points
39in your program, so locking and parallel access are rarely an issue,
40making coroutine programming much safer and easier than using other thread
41models.
44 42
45Coroutines are also useful because Perl has no support for threads (the so 43Unlike the so-called "Perl threads" (which are not actually real threads
46called "threads" that perl offers are nothing more than the (bad) process 44but only the windows process emulation ported to unix), Coro provides a
47emulation coming from the Windows platform: On standard operating systems 45full shared address space, which makes communication between coroutines
48they serve no purpose whatsoever, except by making your programs slow and 46very easy. And coroutines are fast, too: disabling the Windows process
49making them use a lot of memory. Best disable them when building perl, or 47emulation code in your perl and using Coro can easily result in a two to
50aks your software vendor/distributor to do it for you). 48four times speed increase for your programs.
51 49
50Coro achieves that by supporting multiple running interpreters that share
51data, which is especially useful to code pseudo-parallel processes and
52for event-based programming, such as multiple HTTP-GET requests running
53concurrently. See L<Coro::AnyEvent> to learn more on how to integrate Coro
54into an event-based environment.
55
52In this module, coroutines are defined as "callchain + lexical variables + 56In this module, a coroutines is defined as "callchain + lexical variables
53@_ + $_ + $@ + $/ + C stack), that is, a coroutine has its own callchain, 57+ @_ + $_ + $@ + $/ + C stack), that is, a coroutine has its own
54its own set of lexicals and its own set of perls most important global 58callchain, its own set of lexicals and its own set of perls most important
55variables (see L<Coro::State> for more configuration). 59global variables (see L<Coro::State> for more configuration and background
60info).
61
62See also the C<SEE ALSO> section at the end of this document - the Coro
63module family is quite large.
56 64
57=cut 65=cut
58 66
59package Coro; 67package Coro;
60 68
… …
67 75
68our $idle; # idle handler 76our $idle; # idle handler
69our $main; # main coroutine 77our $main; # main coroutine
70our $current; # current coroutine 78our $current; # current coroutine
71 79
72our $VERSION = 5.0; 80our $VERSION = "5.0";
73 81
74our @EXPORT = qw(async async_pool cede schedule terminate current unblock_sub); 82our @EXPORT = qw(async async_pool cede schedule terminate current unblock_sub);
75our %EXPORT_TAGS = ( 83our %EXPORT_TAGS = (
76 prio => [qw(PRIO_MAX PRIO_HIGH PRIO_NORMAL PRIO_LOW PRIO_IDLE PRIO_MIN)], 84 prio => [qw(PRIO_MAX PRIO_HIGH PRIO_NORMAL PRIO_LOW PRIO_IDLE PRIO_MIN)],
77); 85);
78our @EXPORT_OK = (@{$EXPORT_TAGS{prio}}, qw(nready)); 86our @EXPORT_OK = (@{$EXPORT_TAGS{prio}}, qw(nready));
79 87
88=head1 GLOBAL VARIABLES
89
80=over 4 90=over 4
81 91
82=item $Coro::main 92=item $Coro::main
83 93
84This variable stores the coroutine object that represents the main 94This variable stores the coroutine object that represents the main
… …
135$idle = sub { 145$idle = sub {
136 require Carp; 146 require Carp;
137 Carp::croak ("FATAL: deadlock detected"); 147 Carp::croak ("FATAL: deadlock detected");
138}; 148};
139 149
140sub _cancel {
141 my ($self) = @_;
142
143 # free coroutine data and mark as destructed
144 $self->_destroy
145 or return;
146
147 # call all destruction callbacks
148 $_->(@{$self->{_status}})
149 for @{ delete $self->{_on_destroy} || [] };
150}
151
152# this coroutine is necessary because a coroutine 150# this coroutine is necessary because a coroutine
153# cannot destroy itself. 151# cannot destroy itself.
154our @destroy; 152our @destroy;
155our $manager; 153our $manager;
156 154
157$manager = new Coro sub { 155$manager = new Coro sub {
158 while () { 156 while () {
159 (shift @destroy)->_cancel 157 Coro::_cancel shift @destroy
160 while @destroy; 158 while @destroy;
161 159
162 &schedule; 160 &schedule;
163 } 161 }
164}; 162};
165$manager->{desc} = "[coro manager]"; 163$manager->{desc} = "[coro manager]";
166$manager->prio (PRIO_MAX); 164$manager->prio (PRIO_MAX);
167 165
168=back 166=back
169 167
170=head2 SIMPLE COROUTINE CREATION 168=head1 SIMPLE COROUTINE CREATION
171 169
172=over 4 170=over 4
173 171
174=item async { ... } [@args...] 172=item async { ... } [@args...]
175 173
… …
237coros as required. 235coros as required.
238 236
239If you are concerned about pooled coroutines growing a lot because a 237If you are concerned about pooled coroutines growing a lot because a
240single C<async_pool> used a lot of stackspace you can e.g. C<async_pool 238single C<async_pool> used a lot of stackspace you can e.g. C<async_pool
241{ terminate }> once per second or so to slowly replenish the pool. In 239{ terminate }> once per second or so to slowly replenish the pool. In
242addition to that, when the stacks used by a handler grows larger than 16kb 240addition to that, when the stacks used by a handler grows larger than 32kb
243(adjustable via $Coro::POOL_RSS) it will also be destroyed. 241(adjustable via $Coro::POOL_RSS) it will also be destroyed.
244 242
245=cut 243=cut
246 244
247our $POOL_SIZE = 8; 245our $POOL_SIZE = 8;
248our $POOL_RSS = 16 * 1024; 246our $POOL_RSS = 32 * 1024;
249our @async_pool; 247our @async_pool;
250 248
251sub pool_handler { 249sub pool_handler {
252 while () { 250 while () {
253 eval { 251 eval {
… …
258 } 256 }
259} 257}
260 258
261=back 259=back
262 260
263=head2 STATIC METHODS 261=head1 STATIC METHODS
264 262
265Static methods are actually functions that operate on the current coroutine. 263Static methods are actually functions that implicitly operate on the
264current coroutine.
266 265
267=over 4 266=over 4
268 267
269=item schedule 268=item schedule
270 269
… …
319you cannot free all of them, so if a coroutine that is not the main 318you cannot free all of them, so if a coroutine that is not the main
320program calls this function, there will be some one-time resource leak. 319program calls this function, there will be some one-time resource leak.
321 320
322=cut 321=cut
323 322
324sub terminate {
325 $current->{_status} = [@_];
326 push @destroy, $current;
327 $manager->ready;
328 do { &schedule } while 1;
329}
330
331sub killall { 323sub killall {
332 for (Coro::State::list) { 324 for (Coro::State::list) {
333 $_->cancel 325 $_->cancel
334 if $_ != $current && UNIVERSAL::isa $_, "Coro"; 326 if $_ != $current && UNIVERSAL::isa $_, "Coro";
335 } 327 }
336} 328}
337 329
338=back 330=back
339 331
340=head2 COROUTINE METHODS 332=head1 COROUTINE OBJECT METHODS
341 333
342These are the methods you can call on coroutine objects (or to create 334These are the methods you can call on coroutine objects (or to create
343them). 335them).
344 336
345=over 4 337=over 4
… …
517 my $old = $_[0]{desc}; 509 my $old = $_[0]{desc};
518 $_[0]{desc} = $_[1] if @_ > 1; 510 $_[0]{desc} = $_[1] if @_ > 1;
519 $old; 511 $old;
520} 512}
521 513
514sub transfer {
515 require Carp;
516 Carp::croak ("You must not call ->transfer on Coro objects. Use Coro::State objects or the ->schedule_to method. Caught");
517}
518
522=back 519=back
523 520
524=head2 GLOBAL FUNCTIONS 521=head1 GLOBAL FUNCTIONS
525 522
526=over 4 523=over 4
527 524
528=item Coro::nready 525=item Coro::nready
529 526
… …
762 759
763Debugging: L<Coro::Debug>. 760Debugging: L<Coro::Debug>.
764 761
765Support/Utility: L<Coro::Specific>, L<Coro::Util>. 762Support/Utility: L<Coro::Specific>, L<Coro::Util>.
766 763
767Locking/IPC: L<Coro::Signal>, L<Coro::Channel>, L<Coro::Semaphore>, L<Coro::SemaphoreSet>, L<Coro::RWLock>. 764Locking/IPC: L<Coro::Signal>, L<Coro::Channel>, L<Coro::Semaphore>,
765L<Coro::SemaphoreSet>, L<Coro::RWLock>.
768 766
769IO/Timers: L<Coro::Timer>, L<Coro::Handle>, L<Coro::Socket>, L<Coro::AIO>. 767IO/Timers: L<Coro::Timer>, L<Coro::Handle>, L<Coro::Socket>, L<Coro::AIO>.
770 768
771Compatibility: L<Coro::LWP>, L<Coro::BDB>, L<Coro::Storable>, L<Coro::Select>. 769Compatibility: L<Coro::LWP> (but see also L<AnyEvent::HTTP> for
770a better-working alternative), L<Coro::BDB>, L<Coro::Storable>,
771L<Coro::Select>.
772 772
773XS API: L<Coro::MakeMaker>. 773XS API: L<Coro::MakeMaker>.
774 774
775Low level Configuration, Coroutine Environment: L<Coro::State>. 775Low level Configuration, Coroutine Environment: L<Coro::State>.
776 776

Diff Legend

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