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

Comparing Coro/Coro.pm (file contents):
Revision 1.233 by root, Fri Nov 21 06:02:07 2008 UTC vs.
Revision 1.234 by root, Fri Nov 21 06:52:10 2008 UTC

1=head1 NAME 1=head1 NAME
2 2
3Coro - coroutine process abstraction 3Coro - the real perl threads
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 31This module collection manages coroutines, that is, cooperative
32threads but don't (in general) run in parallel at the same time even 32threads. Coroutines are similar to kernel threads but don't (in general)
33on SMP machines. The specific flavor of coroutine used in this module 33run in parallel at the same time even on SMP machines. The specific flavor
34also guarantees you that it will not switch between coroutines unless 34of coroutine used in this module also guarantees you that it will not
35necessary, at easily-identified points in your program, so locking and 35switch between coroutines unless necessary, at easily-identified points
36parallel access are rarely an issue, making coroutine programming much 36in your program, so locking and parallel access are rarely an issue,
37safer and easier than threads programming. 37making coroutine programming much safer and easier than using other thread
38models.
38 39
39Unlike a normal perl program, however, coroutines allow you to have 40Unlike the so-called "Perl threads" (which are not actually real threads
40multiple running interpreters that share data, which is especially useful 41but only the windows process emulation ported to unix), Coro provides a
41to code pseudo-parallel processes and for event-based programming, such as 42full shared address space, which makes communication between coroutines
42multiple HTTP-GET requests running concurrently. See L<Coro::AnyEvent> to 43very easy. And coroutines are fast, too: disabling the Windows process
43learn more. 44emulation code in your perl and using Coro can easily result in a two to
45four times speed increase for your programs.
44 46
45Coroutines are also useful because Perl has no support for threads (the so 47Coro achieves that by supporting multiple running interpreters that share
46called "threads" that perl offers are nothing more than the (bad) process 48data, which is especially useful to code pseudo-parallel processes and
47emulation coming from the Windows platform: On standard operating systems 49for event-based programming, such as multiple HTTP-GET requests running
48they serve no purpose whatsoever, except by making your programs slow and 50concurrently. See L<Coro::AnyEvent> to learn more on how to integrate Coro
49making them use a lot of memory. Best disable them when building perl, or 51into an event-based environment.
50aks your software vendor/distributor to do it for you).
51 52
52In this module, coroutines are defined as "callchain + lexical variables + 53In this module, a coroutines is defined as "callchain + lexical variables
53@_ + $_ + $@ + $/ + C stack), that is, a coroutine has its own callchain, 54+ @_ + $_ + $@ + $/ + C stack), that is, a coroutine has its own
54its own set of lexicals and its own set of perls most important global 55callchain, its own set of lexicals and its own set of perls most important
55variables (see L<Coro::State> for more configuration). 56global variables (see L<Coro::State> for more configuration and background
57info).
58
59See also the C<SEE ALSO> section at the end of this document - the Coro
60module family is quite large.
56 61
57=cut 62=cut
58 63
59package Coro; 64package Coro;
60 65
… …
75our %EXPORT_TAGS = ( 80our %EXPORT_TAGS = (
76 prio => [qw(PRIO_MAX PRIO_HIGH PRIO_NORMAL PRIO_LOW PRIO_IDLE PRIO_MIN)], 81 prio => [qw(PRIO_MAX PRIO_HIGH PRIO_NORMAL PRIO_LOW PRIO_IDLE PRIO_MIN)],
77); 82);
78our @EXPORT_OK = (@{$EXPORT_TAGS{prio}}, qw(nready)); 83our @EXPORT_OK = (@{$EXPORT_TAGS{prio}}, qw(nready));
79 84
85=head1 GLOBAL VARIABLES
86
80=over 4 87=over 4
81 88
82=item $Coro::main 89=item $Coro::main
83 90
84This variable stores the coroutine object that represents the main 91This variable stores the coroutine object that represents the main
… …
153$manager->{desc} = "[coro manager]"; 160$manager->{desc} = "[coro manager]";
154$manager->prio (PRIO_MAX); 161$manager->prio (PRIO_MAX);
155 162
156=back 163=back
157 164
158=head2 SIMPLE COROUTINE CREATION 165=head1 SIMPLE COROUTINE CREATION
159 166
160=over 4 167=over 4
161 168
162=item async { ... } [@args...] 169=item async { ... } [@args...]
163 170
… …
246 } 253 }
247} 254}
248 255
249=back 256=back
250 257
251=head2 STATIC METHODS 258=head1 STATIC METHODS
252 259
253Static methods are actually functions that operate on the current coroutine. 260Static methods are actually functions that implicitly operate on the
261current coroutine.
254 262
255=over 4 263=over 4
256 264
257=item schedule 265=item schedule
258 266
… …
316 } 324 }
317} 325}
318 326
319=back 327=back
320 328
321=head2 COROUTINE METHODS 329=head1 COROUTINE OBJECT METHODS
322 330
323These are the methods you can call on coroutine objects (or to create 331These are the methods you can call on coroutine objects (or to create
324them). 332them).
325 333
326=over 4 334=over 4
… …
505 Carp::croak ("You must not call ->transfer on Coro objects. Use Coro::State objects or the ->schedule_to method. Caught"); 513 Carp::croak ("You must not call ->transfer on Coro objects. Use Coro::State objects or the ->schedule_to method. Caught");
506} 514}
507 515
508=back 516=back
509 517
510=head2 GLOBAL FUNCTIONS 518=head1 GLOBAL FUNCTIONS
511 519
512=over 4 520=over 4
513 521
514=item Coro::nready 522=item Coro::nready
515 523

Diff Legend

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