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

Comparing cvsroot/Coro/Coro.pm (file contents):
Revision 1.230 by root, Thu Nov 20 07:02:43 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
… …
153$manager->{desc} = "[coro manager]"; 163$manager->{desc} = "[coro manager]";
154$manager->prio (PRIO_MAX); 164$manager->prio (PRIO_MAX);
155 165
156=back 166=back
157 167
158=head2 SIMPLE COROUTINE CREATION 168=head1 SIMPLE COROUTINE CREATION
159 169
160=over 4 170=over 4
161 171
162=item async { ... } [@args...] 172=item async { ... } [@args...]
163 173
… …
225coros as required. 235coros as required.
226 236
227If you are concerned about pooled coroutines growing a lot because a 237If you are concerned about pooled coroutines growing a lot because a
228single 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
229{ 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
230addition 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
231(adjustable via $Coro::POOL_RSS) it will also be destroyed. 241(adjustable via $Coro::POOL_RSS) it will also be destroyed.
232 242
233=cut 243=cut
234 244
235our $POOL_SIZE = 8; 245our $POOL_SIZE = 8;
236our $POOL_RSS = 16 * 1024; 246our $POOL_RSS = 32 * 1024;
237our @async_pool; 247our @async_pool;
238 248
239sub pool_handler { 249sub pool_handler {
240 while () { 250 while () {
241 eval { 251 eval {
… …
246 } 256 }
247} 257}
248 258
249=back 259=back
250 260
251=head2 STATIC METHODS 261=head1 STATIC METHODS
252 262
253Static methods are actually functions that operate on the current coroutine. 263Static methods are actually functions that implicitly operate on the
264current coroutine.
254 265
255=over 4 266=over 4
256 267
257=item schedule 268=item schedule
258 269
… …
316 } 327 }
317} 328}
318 329
319=back 330=back
320 331
321=head2 COROUTINE METHODS 332=head1 COROUTINE OBJECT METHODS
322 333
323These 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
324them). 335them).
325 336
326=over 4 337=over 4
… …
498 my $old = $_[0]{desc}; 509 my $old = $_[0]{desc};
499 $_[0]{desc} = $_[1] if @_ > 1; 510 $_[0]{desc} = $_[1] if @_ > 1;
500 $old; 511 $old;
501} 512}
502 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
503=back 519=back
504 520
505=head2 GLOBAL FUNCTIONS 521=head1 GLOBAL FUNCTIONS
506 522
507=over 4 523=over 4
508 524
509=item Coro::nready 525=item Coro::nready
510 526
… …
743 759
744Debugging: L<Coro::Debug>. 760Debugging: L<Coro::Debug>.
745 761
746Support/Utility: L<Coro::Specific>, L<Coro::Util>. 762Support/Utility: L<Coro::Specific>, L<Coro::Util>.
747 763
748Locking/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>.
749 766
750IO/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>.
751 768
752Compatibility: 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>.
753 772
754XS API: L<Coro::MakeMaker>. 773XS API: L<Coro::MakeMaker>.
755 774
756Low level Configuration, Coroutine Environment: L<Coro::State>. 775Low level Configuration, Coroutine Environment: L<Coro::State>.
757 776

Diff Legend

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