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

Comparing Coro/Coro.pm (file contents):
Revision 1.237 by root, Sat Nov 22 16:37:11 2008 UTC vs.
Revision 1.238 by root, Mon Nov 24 04:56:38 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
… …
115sub current() { $current } # [DEPRECATED] 114sub current() { $current } # [DEPRECATED]
116 115
117=item $Coro::idle 116=item $Coro::idle
118 117
119This variable is mainly useful to integrate Coro into event loops. It is 118This 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 119usually better to rely on L<Coro::AnyEvent> or L<Coro::EV>, as this is
121pretty low-level functionality. 120pretty low-level functionality.
122 121
123This variable stores a callback that is called whenever the scheduler 122This variable stores either a coroutine or a callback.
123
124If it is a callback, the it is called whenever the scheduler finds no
124finds no ready coroutines to run. The default implementation prints 125ready coroutines to run. The default implementation prints "FATAL:
125"FATAL: deadlock detected" and exits, because the program has no other way 126deadlock detected" and exits, because the program has no other way to
126to continue. 127continue.
127 128
129If it is a coroutine object, then this object will be readied (without
130invoking any ready hooks, however) when the scheduler finds no other ready
131coroutines to run.
132
128This hook is overwritten by modules such as C<Coro::Timer> and 133This 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 134C<Coro::AnyEvent> to wait on an external event that hopefully wake up a
130coroutine so the scheduler can run it. 135coroutine so the scheduler can run it.
131 136
132Note that the callback I<must not>, under any circumstances, block 137Note that the callback I<must not>, under any circumstances, block
133the current coroutine. Normally, this is achieved by having an "idle 138the current coroutine. Normally, this is achieved by having an "idle
134coroutine" that calls the event loop and then blocks again, and then 139coroutine" that calls the event loop and then blocks again, and then
135readying that coroutine in the idle handler. 140readying that coroutine in the idle handler, or by simply placing the idle
141coroutine in this variable.
136 142
137See L<Coro::Event> or L<Coro::AnyEvent> for examples of using this 143See L<Coro::Event> or L<Coro::AnyEvent> for examples of using this
138technique. 144technique.
139 145
140Please note that if your callback recursively invokes perl (e.g. for event 146Please note that if your callback recursively invokes perl (e.g. for event
… …
573original code ref will be called (with parameters) from within another 579original code ref will be called (with parameters) from within another
574coroutine. 580coroutine.
575 581
576The reason this function exists is that many event libraries (such as the 582The reason this function exists is that many event libraries (such as the
577venerable L<Event|Event> module) are not coroutine-safe (a weaker form 583venerable L<Event|Event> module) are not coroutine-safe (a weaker form
578of thread-safety). This means you must not block within event callbacks, 584of reentrancy). This means you must not block within event callbacks,
579otherwise you might suffer from crashes or worse. The only event library 585otherwise 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>. 586currently known that is safe to use without C<unblock_sub> is L<EV>.
581 587
582This function allows your callbacks to block by executing them in another 588This function allows your callbacks to block by executing them in another
583coroutine where it is safe to block. One example where blocking is handy 589coroutine where it is safe to block. One example where blocking is handy
… …
629 } 635 }
630} 636}
631 637
632=item $cb = Coro::rouse_cb 638=item $cb = Coro::rouse_cb
633 639
634Create and return a "rouse callback". That's a code reference that, when 640Create and return a "rouse callback". That's a code reference that,
635called, will save its arguments and notify the owner coroutine of the 641when called, will remember a copy of its arguments and notify the owner
636callback. 642coroutine of the callback.
637 643
638See the next function. 644See the next function.
639 645
640=item @args = Coro::rouse_wait [$cb] 646=item @args = Coro::rouse_wait [$cb]
641 647
642Wait for the specified rouse callback (or the last one tht was created in 648Wait for the specified rouse callback (or the last one that was created in
643this coroutine). 649this coroutine).
644 650
645As soon as the callback is invoked (or when the calback was invoked before 651As 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 652before C<rouse_wait>), it will return the arguments originally passed to
647to the rouse callback. 653the rouse callback.
648 654
649See the section B<HOW TO WAIT FOR A CALLBACK> for an actual usage example. 655See the section B<HOW TO WAIT FOR A CALLBACK> for an actual usage example.
650 656
651=back 657=back
652 658
… …
732fix your libc and use a saner backend. 738fix your libc and use a saner backend.
733 739
734=item perl process emulation ("threads") 740=item perl process emulation ("threads")
735 741
736This module is not perl-pseudo-thread-safe. You should only ever use this 742This 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 743module from the first thread (this requirement might be removed in the
738future to allow per-thread schedulers, but Coro::State does not yet allow 744future to allow per-thread schedulers, but Coro::State does not yet allow
739this). I recommend disabling thread support and using processes, as having 745this). I recommend disabling thread support and using processes, as having
740the windows process emulation enabled under unix roughly halves perl 746the windows process emulation enabled under unix roughly halves perl
741performance, even when not used. 747performance, even when not used.
742 748
… …
759 765
760Debugging: L<Coro::Debug>. 766Debugging: L<Coro::Debug>.
761 767
762Support/Utility: L<Coro::Specific>, L<Coro::Util>. 768Support/Utility: L<Coro::Specific>, L<Coro::Util>.
763 769
764Locking/IPC: L<Coro::Signal>, L<Coro::Channel>, L<Coro::Semaphore>, 770Locking and IPC: L<Coro::Signal>, L<Coro::Channel>, L<Coro::Semaphore>,
765L<Coro::SemaphoreSet>, L<Coro::RWLock>. 771L<Coro::SemaphoreSet>, L<Coro::RWLock>.
766 772
767IO/Timers: L<Coro::Timer>, L<Coro::Handle>, L<Coro::Socket>, L<Coro::AIO>. 773I/O and Timers: L<Coro::Timer>, L<Coro::Handle>, L<Coro::Socket>, L<Coro::AIO>.
768 774
769Compatibility: L<Coro::LWP> (but see also L<AnyEvent::HTTP> for 775Compatibility with other modules: L<Coro::LWP> (but see also L<AnyEvent::HTTP> for
770a better-working alternative), L<Coro::BDB>, L<Coro::Storable>, 776a better-working alternative), L<Coro::BDB>, L<Coro::Storable>,
771L<Coro::Select>. 777L<Coro::Select>.
772 778
773XS API: L<Coro::MakeMaker>. 779XS API: L<Coro::MakeMaker>.
774 780
775Low level Configuration, Coroutine Environment: L<Coro::State>. 781Low level Configuration, Thread Environment, Continuations: L<Coro::State>.
776 782
777=head1 AUTHOR 783=head1 AUTHOR
778 784
779 Marc Lehmann <schmorp@schmorp.de> 785 Marc Lehmann <schmorp@schmorp.de>
780 http://home.schmorp.de/ 786 http://home.schmorp.de/

Diff Legend

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