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.237 by root, Sat Nov 22 16:37:11 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 - real threads in perl 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
… …
29=head1 DESCRIPTION 29=head1 DESCRIPTION
30 30
31For a tutorial-style introduction, please read the L<Coro::Intro> 31For a tutorial-style introduction, please read the L<Coro::Intro>
32manpage. This manpage mainly contains reference information. 32manpage. This manpage mainly contains reference information.
33 33
34This module collection manages coroutines, that is, cooperative 34This module collection manages continuations in general, most often
35threads. Coroutines are similar to kernel threads but don't (in general) 35in the form of cooperative threads (also called coroutines in the
36documentation). They are similar to kernel threads but don't (in general)
36run in parallel at the same time even on SMP machines. The specific flavor 37run in parallel at the same time even on SMP machines. The specific flavor
37of coroutine used in this module also guarantees you that it will not 38of thread offered by this module also guarantees you that it will not
38switch between coroutines unless necessary, at easily-identified points 39switch between threads unless necessary, at easily-identified points in
39in your program, so locking and parallel access are rarely an issue, 40your program, so locking and parallel access are rarely an issue, making
40making coroutine programming much safer and easier than using other thread 41thread programming much safer and easier than using other thread models.
41models.
42 42
43Unlike the so-called "Perl threads" (which are not actually real threads 43Unlike the so-called "Perl threads" (which are not actually real threads
44but only the windows process emulation ported to unix), Coro provides a 44but only the windows process emulation ported to unix), Coro provides a
45full shared address space, which makes communication between coroutines 45full shared address space, which makes communication between threads
46very easy. And coroutines are fast, too: disabling the Windows process 46very easy. And threads are fast, too: disabling the Windows process
47emulation code in your perl and using Coro can easily result in a two to 47emulation code in your perl and using Coro can easily result in a two to
48four times speed increase for your programs. 48four times speed increase for your programs.
49 49
50Coro achieves that by supporting multiple running interpreters that share 50Coro achieves that by supporting multiple running interpreters that share
51data, which is especially useful to code pseudo-parallel processes and 51data, which is especially useful to code pseudo-parallel processes and
52for event-based programming, such as multiple HTTP-GET requests running 52for event-based programming, such as multiple HTTP-GET requests running
53concurrently. See L<Coro::AnyEvent> to learn more on how to integrate Coro 53concurrently. See L<Coro::AnyEvent> to learn more on how to integrate Coro
54into an event-based environment. 54into an event-based environment.
55 55
56In this module, a coroutines is defined as "callchain + lexical variables 56In this module, a thread is defined as "callchain + lexical variables +
57+ @_ + $_ + $@ + $/ + C stack), that is, a coroutine has its own 57@_ + $_ + $@ + $/ + C stack), that is, a thread has its own callchain,
58callchain, its own set of lexicals and its own set of perls most important 58its own set of lexicals and its own set of perls most important global
59global variables (see L<Coro::State> for more configuration and background 59variables (see L<Coro::State> for more configuration and background info).
60info).
61 60
62See also the C<SEE ALSO> section at the end of this document - the Coro 61See also the C<SEE ALSO> section at the end of this document - the Coro
63module family is quite large. 62module family is quite large.
64 63
65=cut 64=cut
66 65
67package Coro; 66package Coro;
68 67
69use strict qw(vars subs); 68use strict qw(vars subs);
70no warnings "uninitialized"; 69no warnings "uninitialized";
70
71use Guard ();
71 72
72use Coro::State; 73use Coro::State;
73 74
74use base qw(Coro::State Exporter); 75use base qw(Coro::State Exporter);
75 76
76our $idle; # idle handler 77our $idle; # idle handler
77our $main; # main coroutine 78our $main; # main coroutine
78our $current; # current coroutine 79our $current; # current coroutine
79 80
80our $VERSION = "5.0"; 81our $VERSION = 5.13;
81 82
82our @EXPORT = qw(async async_pool cede schedule terminate current unblock_sub); 83our @EXPORT = qw(async async_pool cede schedule terminate current unblock_sub);
83our %EXPORT_TAGS = ( 84our %EXPORT_TAGS = (
84 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)],
85); 86);
… …
115sub current() { $current } # [DEPRECATED] 116sub current() { $current } # [DEPRECATED]
116 117
117=item $Coro::idle 118=item $Coro::idle
118 119
119This 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
120usually 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
121pretty low-level functionality. 122pretty low-level functionality.
122 123
123This 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
124finds no ready coroutines to run. The default implementation prints 127ready coroutines to run. The default implementation prints "FATAL:
125"FATAL: deadlock detected" and exits, because the program has no other way 128deadlock detected" and exits, because the program has no other way to
126to continue. 129continue.
127 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
128This hook is overwritten by modules such as C<Coro::Timer> and 135This hook is overwritten by modules such as C<Coro::EV> and
129C<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
130coroutine so the scheduler can run it. 137coroutine so the scheduler can run it.
131 138
132Note that the callback I<must not>, under any circumstances, block 139Note that the callback I<must not>, under any circumstances, block
133the current coroutine. Normally, this is achieved by having an "idle 140the current coroutine. Normally, this is achieved by having an "idle
134coroutine" that calls the event loop and then blocks again, and then 141coroutine" that calls the event loop and then blocks again, and then
135readying that coroutine in the idle handler. 142readying that coroutine in the idle handler, or by simply placing the idle
143coroutine in this variable.
136 144
137See 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
138technique. 146technique.
139 147
140Please 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
… …
169 177
170=over 4 178=over 4
171 179
172=item async { ... } [@args...] 180=item async { ... } [@args...]
173 181
174Create a new coroutine and return it's coroutine object (usually 182Create a new coroutine and return its coroutine object (usually
175unused). The coroutine will be put into the ready queue, so 183unused). The coroutine will be put into the ready queue, so
176it will start running automatically on the next scheduler run. 184it will start running automatically on the next scheduler run.
177 185
178The 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
179coroutine. When it returns argument returns the coroutine is automatically 187coroutine. When it returns argument returns the coroutine is automatically
… …
309Terminates the current coroutine with the given status values (see L<cancel>). 317Terminates the current coroutine with the given status values (see L<cancel>).
310 318
311=item killall 319=item killall
312 320
313Kills/terminates/cancels all coroutines except the currently running 321Kills/terminates/cancels all coroutines except the currently running
314one. 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,
315usually 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.
316 328
317Note 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,
318you 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
319program calls this function, there will be some one-time resource leak. 331program calls this function, there will be some one-time resource leak.
320 332
… …
346See 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
347coroutine environment. 359coroutine environment.
348 360
349=cut 361=cut
350 362
351sub _terminate { 363sub _coro_run {
352 terminate &{+shift}; 364 terminate &{+shift};
353} 365}
354 366
355=item $success = $coroutine->ready 367=item $success = $coroutine->ready
356 368
… …
531would 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
532coroutines. 544coroutines.
533 545
534=item my $guard = Coro::guard { ... } 546=item my $guard = Coro::guard { ... }
535 547
536This creates and returns a guard object. Nothing happens until the object 548This function still exists, but is deprecated. Please use the
537gets destroyed, in which case the codeblock given as argument will be 549C<Guard::guard> function instead.
538executed. This is useful to free locks or other resources in case of a
539runtime error or when the coroutine gets canceled, as in both cases the
540guard block will be executed. The guard object supports only one method,
541C<< ->cancel >>, which will keep the codeblock from being executed.
542 550
543Example: set some flag and clear it again when the coroutine gets canceled
544or the function returns:
545
546 sub do_something {
547 my $guard = Coro::guard { $busy = 0 };
548 $busy = 1;
549
550 # do something that requires $busy to be true
551 }
552
553=cut 551=cut
554 552
555sub guard(&) { 553BEGIN { *guard = \&Guard::guard }
556 bless \(my $cb = $_[0]), "Coro::guard"
557}
558
559sub Coro::guard::cancel {
560 ${$_[0]} = sub { };
561}
562
563sub Coro::guard::DESTROY {
564 ${$_[0]}->();
565}
566
567 554
568=item unblock_sub { ... } 555=item unblock_sub { ... }
569 556
570This utility function takes a BLOCK or code reference and "unblocks" it, 557This utility function takes a BLOCK or code reference and "unblocks" it,
571returning a new coderef. Unblocking means that calling the new coderef 558returning a new coderef. Unblocking means that calling the new coderef
… …
573original code ref will be called (with parameters) from within another 560original code ref will be called (with parameters) from within another
574coroutine. 561coroutine.
575 562
576The 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
577venerable L<Event|Event> module) are not coroutine-safe (a weaker form 564venerable L<Event|Event> module) are not coroutine-safe (a weaker form
578of thread-safety). This means you must not block within event callbacks, 565of reentrancy). This means you must not block within event callbacks,
579otherwise you might suffer from crashes or worse. The only event library 566otherwise you might suffer from crashes or worse. The only event library
580currently 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>.
581 568
582This function allows your callbacks to block by executing them in another 569This function allows your callbacks to block by executing them in another
583coroutine 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
… …
629 } 616 }
630} 617}
631 618
632=item $cb = Coro::rouse_cb 619=item $cb = Coro::rouse_cb
633 620
634Create and return a "rouse callback". That's a code reference that, when 621Create and return a "rouse callback". That's a code reference that,
635called, will save its arguments and notify the owner coroutine of the 622when called, will remember a copy of its arguments and notify the owner
636callback. 623coroutine of the callback.
637 624
638See the next function. 625See the next function.
639 626
640=item @args = Coro::rouse_wait [$cb] 627=item @args = Coro::rouse_wait [$cb]
641 628
642Wait 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
643this coroutine). 630this coroutine).
644 631
645As 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
646C<rouse_wait>), it will return a copy of the arguments originally passed 633before C<rouse_wait>), it will return the arguments originally passed to
647to the rouse callback. 634the rouse callback.
648 635
649See 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.
650 637
651=back 638=back
652 639
… …
675 662
676Coro offers two functions specifically designed to make this easy, 663Coro offers two functions specifically designed to make this easy,
677C<Coro::rouse_cb> and C<Coro::rouse_wait>. 664C<Coro::rouse_cb> and C<Coro::rouse_wait>.
678 665
679The first function, C<rouse_cb>, generates and returns a callback that, 666The first function, C<rouse_cb>, generates and returns a callback that,
680when invoked, will save it's arguments and notify the coroutine that 667when invoked, will save its arguments and notify the coroutine that
681created the callback. 668created the callback.
682 669
683The 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
684(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
685originally passed to the callback. 672originally passed to the callback.
… …
732fix your libc and use a saner backend. 719fix your libc and use a saner backend.
733 720
734=item perl process emulation ("threads") 721=item perl process emulation ("threads")
735 722
736This 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
737module from the same thread (this requirement might be removed in the 724module from the first thread (this requirement might be removed in the
738future 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
739this). I recommend disabling thread support and using processes, as having 726this). I recommend disabling thread support and using processes, as having
740the windows process emulation enabled under unix roughly halves perl 727the windows process emulation enabled under unix roughly halves perl
741performance, even when not used. 728performance, even when not used.
742 729
… …
759 746
760Debugging: L<Coro::Debug>. 747Debugging: L<Coro::Debug>.
761 748
762Support/Utility: L<Coro::Specific>, L<Coro::Util>. 749Support/Utility: L<Coro::Specific>, L<Coro::Util>.
763 750
764Locking/IPC: L<Coro::Signal>, L<Coro::Channel>, L<Coro::Semaphore>, 751Locking and IPC: L<Coro::Signal>, L<Coro::Channel>, L<Coro::Semaphore>,
765L<Coro::SemaphoreSet>, L<Coro::RWLock>. 752L<Coro::SemaphoreSet>, L<Coro::RWLock>.
766 753
767IO/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>.
768 755
769Compatibility: L<Coro::LWP> (but see also L<AnyEvent::HTTP> for 756Compatibility with other modules: L<Coro::LWP> (but see also L<AnyEvent::HTTP> for
770a better-working alternative), L<Coro::BDB>, L<Coro::Storable>, 757a better-working alternative), L<Coro::BDB>, L<Coro::Storable>,
771L<Coro::Select>. 758L<Coro::Select>.
772 759
773XS API: L<Coro::MakeMaker>. 760XS API: L<Coro::MakeMaker>.
774 761
775Low level Configuration, Coroutine Environment: L<Coro::State>. 762Low level Configuration, Thread Environment, Continuations: L<Coro::State>.
776 763
777=head1 AUTHOR 764=head1 AUTHOR
778 765
779 Marc Lehmann <schmorp@schmorp.de> 766 Marc Lehmann <schmorp@schmorp.de>
780 http://home.schmorp.de/ 767 http://home.schmorp.de/

Diff Legend

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