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

Comparing Coro/Coro.pm (file contents):
Revision 1.232 by root, Fri Nov 21 02:39:40 2008 UTC vs.
Revision 1.246 by root, Mon Dec 15 00:30:40 2008 UTC

1=head1 NAME 1=head1 NAME
2 2
3Coro - coroutine process abstraction 3Coro - the only 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 continuations in general, most often
40multiple running interpreters that share data, which is especially useful 35in the form of cooperative threads (also called coroutines in the
41to code pseudo-parallel processes and for event-based programming, such as 36documentation). They are similar to kernel threads but don't (in general)
42multiple HTTP-GET requests running concurrently. See L<Coro::AnyEvent> to 37run in parallel at the same time even on SMP machines. The specific flavor
43learn more. 38of thread offered by this module also guarantees you that it will not
39switch between threads unless necessary, at easily-identified points in
40your program, so locking and parallel access are rarely an issue, making
41thread programming much safer and easier than using other thread models.
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 threads
48they serve no purpose whatsoever, except by making your programs slow and 46very easy. And threads 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 thread is defined as "callchain + lexical variables +
53@_ + $_ + $@ + $/ + C stack), that is, a coroutine has its own callchain, 57@_ + $_ + $@ + $/ + C stack), that is, a thread has its own callchain,
54its own set of lexicals and its own set of perls most important global 58its own set of lexicals and its own set of perls most important global
55variables (see L<Coro::State> for more configuration). 59variables (see L<Coro::State> for more configuration and background info).
60
61See also the C<SEE ALSO> section at the end of this document - the Coro
62module family is quite large.
56 63
57=cut 64=cut
58 65
59package Coro; 66package Coro;
60 67
61use strict qw(vars subs); 68use strict qw(vars subs);
62no warnings "uninitialized"; 69no warnings "uninitialized";
70
71use Guard ();
63 72
64use Coro::State; 73use Coro::State;
65 74
66use base qw(Coro::State Exporter); 75use base qw(Coro::State Exporter);
67 76
68our $idle; # idle handler 77our $idle; # idle handler
69our $main; # main coroutine 78our $main; # main coroutine
70our $current; # current coroutine 79our $current; # current coroutine
71 80
72our $VERSION = "5.0"; 81our $VERSION = 5.13;
73 82
74our @EXPORT = qw(async async_pool cede schedule terminate current unblock_sub); 83our @EXPORT = qw(async async_pool cede schedule terminate current unblock_sub);
75our %EXPORT_TAGS = ( 84our %EXPORT_TAGS = (
76 prio => [qw(PRIO_MAX PRIO_HIGH PRIO_NORMAL PRIO_LOW PRIO_IDLE PRIO_MIN)], 85 prio => [qw(PRIO_MAX PRIO_HIGH PRIO_NORMAL PRIO_LOW PRIO_IDLE PRIO_MIN)],
77); 86);
78our @EXPORT_OK = (@{$EXPORT_TAGS{prio}}, qw(nready)); 87our @EXPORT_OK = (@{$EXPORT_TAGS{prio}}, qw(nready));
79 88
89=head1 GLOBAL VARIABLES
90
80=over 4 91=over 4
81 92
82=item $Coro::main 93=item $Coro::main
83 94
84This variable stores the coroutine object that represents the main 95This variable stores the coroutine object that represents the main
… …
105sub current() { $current } # [DEPRECATED] 116sub current() { $current } # [DEPRECATED]
106 117
107=item $Coro::idle 118=item $Coro::idle
108 119
109This variable is mainly useful to integrate Coro into event loops. It is 120This variable is mainly useful to integrate Coro into event loops. It is
110usually better to rely on L<Coro::AnyEvent> or LC<Coro::EV>, as this is 121usually better to rely on L<Coro::AnyEvent> or L<Coro::EV>, as this is
111pretty low-level functionality. 122pretty low-level functionality.
112 123
113This variable stores a callback that is called whenever the scheduler 124This variable stores either a coroutine or a callback.
125
126If it is a callback, the it is called whenever the scheduler finds no
114finds no ready coroutines to run. The default implementation prints 127ready coroutines to run. The default implementation prints "FATAL:
115"FATAL: deadlock detected" and exits, because the program has no other way 128deadlock detected" and exits, because the program has no other way to
116to continue. 129continue.
117 130
131If it is a coroutine object, then this object will be readied (without
132invoking any ready hooks, however) when the scheduler finds no other ready
133coroutines to run.
134
118This hook is overwritten by modules such as C<Coro::Timer> and 135This hook is overwritten by modules such as C<Coro::EV> and
119C<Coro::AnyEvent> to wait on an external event that hopefully wake up a 136C<Coro::AnyEvent> to wait on an external event that hopefully wake up a
120coroutine so the scheduler can run it. 137coroutine so the scheduler can run it.
121 138
122Note that the callback I<must not>, under any circumstances, block 139Note that the callback I<must not>, under any circumstances, block
123the current coroutine. Normally, this is achieved by having an "idle 140the current coroutine. Normally, this is achieved by having an "idle
124coroutine" that calls the event loop and then blocks again, and then 141coroutine" that calls the event loop and then blocks again, and then
125readying that coroutine in the idle handler. 142readying that coroutine in the idle handler, or by simply placing the idle
143coroutine in this variable.
126 144
127See L<Coro::Event> or L<Coro::AnyEvent> for examples of using this 145See L<Coro::Event> or L<Coro::AnyEvent> for examples of using this
128technique. 146technique.
129 147
130Please note that if your callback recursively invokes perl (e.g. for event 148Please note that if your callback recursively invokes perl (e.g. for event
… …
153$manager->{desc} = "[coro manager]"; 171$manager->{desc} = "[coro manager]";
154$manager->prio (PRIO_MAX); 172$manager->prio (PRIO_MAX);
155 173
156=back 174=back
157 175
158=head2 SIMPLE COROUTINE CREATION 176=head1 SIMPLE COROUTINE CREATION
159 177
160=over 4 178=over 4
161 179
162=item async { ... } [@args...] 180=item async { ... } [@args...]
163 181
164Create a new coroutine and return it's coroutine object (usually 182Create a new coroutine and return its coroutine object (usually
165unused). The coroutine will be put into the ready queue, so 183unused). The coroutine will be put into the ready queue, so
166it will start running automatically on the next scheduler run. 184it will start running automatically on the next scheduler run.
167 185
168The first argument is a codeblock/closure that should be executed in the 186The first argument is a codeblock/closure that should be executed in the
169coroutine. When it returns argument returns the coroutine is automatically 187coroutine. When it returns argument returns the coroutine is automatically
… …
246 } 264 }
247} 265}
248 266
249=back 267=back
250 268
251=head2 STATIC METHODS 269=head1 STATIC METHODS
252 270
253Static methods are actually functions that operate on the current coroutine. 271Static methods are actually functions that implicitly operate on the
272current coroutine.
254 273
255=over 4 274=over 4
256 275
257=item schedule 276=item schedule
258 277
… …
298Terminates the current coroutine with the given status values (see L<cancel>). 317Terminates the current coroutine with the given status values (see L<cancel>).
299 318
300=item killall 319=item killall
301 320
302Kills/terminates/cancels all coroutines except the currently running 321Kills/terminates/cancels all coroutines except the currently running
303one. This is useful after a fork, either in the child or the parent, as 322one. This can be useful after a fork, either in the child or the parent,
304usually only one of them should inherit the running coroutines. 323as usually only one of them should inherit the running coroutines.
324
325Note that in the implementation, destructors run as normal, making this
326function not so useful after a fork. Future versions of this function
327might try to free resources without running any code.
305 328
306Note that while this will try to free some of the main programs resources, 329Note that while this will try to free some of the main programs resources,
307you cannot free all of them, so if a coroutine that is not the main 330you cannot free all of them, so if a coroutine that is not the main
308program calls this function, there will be some one-time resource leak. 331program calls this function, there will be some one-time resource leak.
309 332
… …
316 } 339 }
317} 340}
318 341
319=back 342=back
320 343
321=head2 COROUTINE METHODS 344=head1 COROUTINE OBJECT METHODS
322 345
323These are the methods you can call on coroutine objects (or to create 346These are the methods you can call on coroutine objects (or to create
324them). 347them).
325 348
326=over 4 349=over 4
… …
335See C<async> and C<Coro::State::new> for additional info about the 358See C<async> and C<Coro::State::new> for additional info about the
336coroutine environment. 359coroutine environment.
337 360
338=cut 361=cut
339 362
340sub _terminate { 363sub _coro_run {
341 terminate &{+shift}; 364 terminate &{+shift};
342} 365}
343 366
344=item $success = $coroutine->ready 367=item $success = $coroutine->ready
345 368
… …
498 my $old = $_[0]{desc}; 521 my $old = $_[0]{desc};
499 $_[0]{desc} = $_[1] if @_ > 1; 522 $_[0]{desc} = $_[1] if @_ > 1;
500 $old; 523 $old;
501} 524}
502 525
526sub transfer {
527 require Carp;
528 Carp::croak ("You must not call ->transfer on Coro objects. Use Coro::State objects or the ->schedule_to method. Caught");
529}
530
503=back 531=back
504 532
505=head2 GLOBAL FUNCTIONS 533=head1 GLOBAL FUNCTIONS
506 534
507=over 4 535=over 4
508 536
509=item Coro::nready 537=item Coro::nready
510 538
… …
515would cause a deadlock unless there is an idle handler that wakes up some 543would cause a deadlock unless there is an idle handler that wakes up some
516coroutines. 544coroutines.
517 545
518=item my $guard = Coro::guard { ... } 546=item my $guard = Coro::guard { ... }
519 547
520This creates and returns a guard object. Nothing happens until the object 548This function still exists, but is deprecated. Please use the
521gets destroyed, in which case the codeblock given as argument will be 549C<Guard::guard> function instead.
522executed. This is useful to free locks or other resources in case of a
523runtime error or when the coroutine gets canceled, as in both cases the
524guard block will be executed. The guard object supports only one method,
525C<< ->cancel >>, which will keep the codeblock from being executed.
526 550
527Example: set some flag and clear it again when the coroutine gets canceled
528or the function returns:
529
530 sub do_something {
531 my $guard = Coro::guard { $busy = 0 };
532 $busy = 1;
533
534 # do something that requires $busy to be true
535 }
536
537=cut 551=cut
538 552
539sub guard(&) { 553BEGIN { *guard = \&Guard::guard }
540 bless \(my $cb = $_[0]), "Coro::guard"
541}
542
543sub Coro::guard::cancel {
544 ${$_[0]} = sub { };
545}
546
547sub Coro::guard::DESTROY {
548 ${$_[0]}->();
549}
550
551 554
552=item unblock_sub { ... } 555=item unblock_sub { ... }
553 556
554This utility function takes a BLOCK or code reference and "unblocks" it, 557This utility function takes a BLOCK or code reference and "unblocks" it,
555returning a new coderef. Unblocking means that calling the new coderef 558returning a new coderef. Unblocking means that calling the new coderef
… …
557original code ref will be called (with parameters) from within another 560original code ref will be called (with parameters) from within another
558coroutine. 561coroutine.
559 562
560The reason this function exists is that many event libraries (such as the 563The reason this function exists is that many event libraries (such as the
561venerable L<Event|Event> module) are not coroutine-safe (a weaker form 564venerable L<Event|Event> module) are not coroutine-safe (a weaker form
562of thread-safety). This means you must not block within event callbacks, 565of reentrancy). This means you must not block within event callbacks,
563otherwise you might suffer from crashes or worse. The only event library 566otherwise you might suffer from crashes or worse. The only event library
564currently known that is safe to use without C<unblock_sub> is L<EV>. 567currently known that is safe to use without C<unblock_sub> is L<EV>.
565 568
566This function allows your callbacks to block by executing them in another 569This function allows your callbacks to block by executing them in another
567coroutine where it is safe to block. One example where blocking is handy 570coroutine where it is safe to block. One example where blocking is handy
… …
613 } 616 }
614} 617}
615 618
616=item $cb = Coro::rouse_cb 619=item $cb = Coro::rouse_cb
617 620
618Create and return a "rouse callback". That's a code reference that, when 621Create and return a "rouse callback". That's a code reference that,
619called, will save its arguments and notify the owner coroutine of the 622when called, will remember a copy of its arguments and notify the owner
620callback. 623coroutine of the callback.
621 624
622See the next function. 625See the next function.
623 626
624=item @args = Coro::rouse_wait [$cb] 627=item @args = Coro::rouse_wait [$cb]
625 628
626Wait for the specified rouse callback (or the last one tht was created in 629Wait for the specified rouse callback (or the last one that was created in
627this coroutine). 630this coroutine).
628 631
629As soon as the callback is invoked (or when the calback was invoked before 632As soon as the callback is invoked (or when the callback was invoked
630C<rouse_wait>), it will return a copy of the arguments originally passed 633before C<rouse_wait>), it will return the arguments originally passed to
631to the rouse callback. 634the rouse callback.
632 635
633See the section B<HOW TO WAIT FOR A CALLBACK> for an actual usage example. 636See the section B<HOW TO WAIT FOR A CALLBACK> for an actual usage example.
634 637
635=back 638=back
636 639
… …
659 662
660Coro offers two functions specifically designed to make this easy, 663Coro offers two functions specifically designed to make this easy,
661C<Coro::rouse_cb> and C<Coro::rouse_wait>. 664C<Coro::rouse_cb> and C<Coro::rouse_wait>.
662 665
663The first function, C<rouse_cb>, generates and returns a callback that, 666The first function, C<rouse_cb>, generates and returns a callback that,
664when invoked, will save it's arguments and notify the coroutine that 667when invoked, will save its arguments and notify the coroutine that
665created the callback. 668created the callback.
666 669
667The second function, C<rouse_wait>, waits for the callback to be called 670The second function, C<rouse_wait>, waits for the callback to be called
668(by calling C<schedule> to go to sleep) and returns the arguments 671(by calling C<schedule> to go to sleep) and returns the arguments
669originally passed to the callback. 672originally passed to the callback.
… …
716fix your libc and use a saner backend. 719fix your libc and use a saner backend.
717 720
718=item perl process emulation ("threads") 721=item perl process emulation ("threads")
719 722
720This module is not perl-pseudo-thread-safe. You should only ever use this 723This module is not perl-pseudo-thread-safe. You should only ever use this
721module from the same thread (this requirement might be removed in the 724module from the first thread (this requirement might be removed in the
722future to allow per-thread schedulers, but Coro::State does not yet allow 725future to allow per-thread schedulers, but Coro::State does not yet allow
723this). I recommend disabling thread support and using processes, as having 726this). I recommend disabling thread support and using processes, as having
724the windows process emulation enabled under unix roughly halves perl 727the windows process emulation enabled under unix roughly halves perl
725performance, even when not used. 728performance, even when not used.
726 729
… …
743 746
744Debugging: L<Coro::Debug>. 747Debugging: L<Coro::Debug>.
745 748
746Support/Utility: L<Coro::Specific>, L<Coro::Util>. 749Support/Utility: L<Coro::Specific>, L<Coro::Util>.
747 750
748Locking/IPC: L<Coro::Signal>, L<Coro::Channel>, L<Coro::Semaphore>, L<Coro::SemaphoreSet>, L<Coro::RWLock>. 751Locking and IPC: L<Coro::Signal>, L<Coro::Channel>, L<Coro::Semaphore>,
752L<Coro::SemaphoreSet>, L<Coro::RWLock>.
749 753
750IO/Timers: L<Coro::Timer>, L<Coro::Handle>, L<Coro::Socket>, L<Coro::AIO>. 754I/O and Timers: L<Coro::Timer>, L<Coro::Handle>, L<Coro::Socket>, L<Coro::AIO>.
751 755
752Compatibility: L<Coro::LWP>, L<Coro::BDB>, L<Coro::Storable>, L<Coro::Select>. 756Compatibility with other modules: L<Coro::LWP> (but see also L<AnyEvent::HTTP> for
757a better-working alternative), L<Coro::BDB>, L<Coro::Storable>,
758L<Coro::Select>.
753 759
754XS API: L<Coro::MakeMaker>. 760XS API: L<Coro::MakeMaker>.
755 761
756Low level Configuration, Coroutine Environment: L<Coro::State>. 762Low level Configuration, Thread Environment, Continuations: L<Coro::State>.
757 763
758=head1 AUTHOR 764=head1 AUTHOR
759 765
760 Marc Lehmann <schmorp@schmorp.de> 766 Marc Lehmann <schmorp@schmorp.de>
761 http://home.schmorp.de/ 767 http://home.schmorp.de/

Diff Legend

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