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

Comparing Coro/Coro.pm (file contents):
Revision 1.234 by root, Fri Nov 21 06:52:10 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 - the real perl threads 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, that is, cooperative 31For a tutorial-style introduction, please read the L<Coro::Intro>
32threads. Coroutines are similar to kernel threads but don't (in general) 32manpage. This manpage mainly contains reference information.
33
34This module collection manages continuations in general, most often
35in the form of cooperative threads (also called coroutines in the
36documentation). They are similar to kernel threads but don't (in general)
33run 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
34of 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
35switch between coroutines unless necessary, at easily-identified points 39switch between threads unless necessary, at easily-identified points in
36in your program, so locking and parallel access are rarely an issue, 40your program, so locking and parallel access are rarely an issue, making
37making coroutine programming much safer and easier than using other thread 41thread programming much safer and easier than using other thread models.
38models.
39 42
40Unlike the so-called "Perl threads" (which are not actually real threads 43Unlike the so-called "Perl threads" (which are not actually real threads
41but only the windows process emulation ported to unix), Coro provides a 44but only the windows process emulation ported to unix), Coro provides a
42full shared address space, which makes communication between coroutines 45full shared address space, which makes communication between threads
43very easy. And coroutines are fast, too: disabling the Windows process 46very easy. And threads are fast, too: disabling the Windows process
44emulation 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
45four times speed increase for your programs. 48four times speed increase for your programs.
46 49
47Coro achieves that by supporting multiple running interpreters that share 50Coro achieves that by supporting multiple running interpreters that share
48data, which is especially useful to code pseudo-parallel processes and 51data, which is especially useful to code pseudo-parallel processes and
49for event-based programming, such as multiple HTTP-GET requests running 52for event-based programming, such as multiple HTTP-GET requests running
50concurrently. 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
51into an event-based environment. 54into an event-based environment.
52 55
53In this module, a coroutines is defined as "callchain + lexical variables 56In this module, a thread is defined as "callchain + lexical variables +
54+ @_ + $_ + $@ + $/ + C stack), that is, a coroutine has its own 57@_ + $_ + $@ + $/ + C stack), that is, a thread has its own callchain,
55callchain, 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
56global variables (see L<Coro::State> for more configuration and background 59variables (see L<Coro::State> for more configuration and background info).
57info).
58 60
59See 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
60module family is quite large. 62module family is quite large.
61 63
62=cut 64=cut
… …
112sub current() { $current } # [DEPRECATED] 114sub current() { $current } # [DEPRECATED]
113 115
114=item $Coro::idle 116=item $Coro::idle
115 117
116This 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
117usually 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
118pretty low-level functionality. 120pretty low-level functionality.
119 121
120This 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
121finds no ready coroutines to run. The default implementation prints 125ready coroutines to run. The default implementation prints "FATAL:
122"FATAL: deadlock detected" and exits, because the program has no other way 126deadlock detected" and exits, because the program has no other way to
123to continue. 127continue.
124 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
125This hook is overwritten by modules such as C<Coro::Timer> and 133This hook is overwritten by modules such as C<Coro::EV> and
126C<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
127coroutine so the scheduler can run it. 135coroutine so the scheduler can run it.
128 136
129Note that the callback I<must not>, under any circumstances, block 137Note that the callback I<must not>, under any circumstances, block
130the current coroutine. Normally, this is achieved by having an "idle 138the current coroutine. Normally, this is achieved by having an "idle
131coroutine" that calls the event loop and then blocks again, and then 139coroutine" that calls the event loop and then blocks again, and then
132readying that coroutine in the idle handler. 140readying that coroutine in the idle handler, or by simply placing the idle
141coroutine in this variable.
133 142
134See 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
135technique. 144technique.
136 145
137Please 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
… …
570original code ref will be called (with parameters) from within another 579original code ref will be called (with parameters) from within another
571coroutine. 580coroutine.
572 581
573The 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
574venerable L<Event|Event> module) are not coroutine-safe (a weaker form 583venerable L<Event|Event> module) are not coroutine-safe (a weaker form
575of thread-safety). This means you must not block within event callbacks, 584of reentrancy). This means you must not block within event callbacks,
576otherwise you might suffer from crashes or worse. The only event library 585otherwise you might suffer from crashes or worse. The only event library
577currently 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>.
578 587
579This function allows your callbacks to block by executing them in another 588This function allows your callbacks to block by executing them in another
580coroutine 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
… …
626 } 635 }
627} 636}
628 637
629=item $cb = Coro::rouse_cb 638=item $cb = Coro::rouse_cb
630 639
631Create and return a "rouse callback". That's a code reference that, when 640Create and return a "rouse callback". That's a code reference that,
632called, will save its arguments and notify the owner coroutine of the 641when called, will remember a copy of its arguments and notify the owner
633callback. 642coroutine of the callback.
634 643
635See the next function. 644See the next function.
636 645
637=item @args = Coro::rouse_wait [$cb] 646=item @args = Coro::rouse_wait [$cb]
638 647
639Wait 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
640this coroutine). 649this coroutine).
641 650
642As 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
643C<rouse_wait>), it will return a copy of the arguments originally passed 652before C<rouse_wait>), it will return the arguments originally passed to
644to the rouse callback. 653the rouse callback.
645 654
646See 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.
647 656
648=back 657=back
649 658
… …
729fix your libc and use a saner backend. 738fix your libc and use a saner backend.
730 739
731=item perl process emulation ("threads") 740=item perl process emulation ("threads")
732 741
733This 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
734module from the same thread (this requirement might be removed in the 743module from the first thread (this requirement might be removed in the
735future 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
736this). I recommend disabling thread support and using processes, as having 745this). I recommend disabling thread support and using processes, as having
737the windows process emulation enabled under unix roughly halves perl 746the windows process emulation enabled under unix roughly halves perl
738performance, even when not used. 747performance, even when not used.
739 748
… …
756 765
757Debugging: L<Coro::Debug>. 766Debugging: L<Coro::Debug>.
758 767
759Support/Utility: L<Coro::Specific>, L<Coro::Util>. 768Support/Utility: L<Coro::Specific>, L<Coro::Util>.
760 769
761Locking/IPC: L<Coro::Signal>, L<Coro::Channel>, L<Coro::Semaphore>, L<Coro::SemaphoreSet>, L<Coro::RWLock>. 770Locking and IPC: L<Coro::Signal>, L<Coro::Channel>, L<Coro::Semaphore>,
771L<Coro::SemaphoreSet>, L<Coro::RWLock>.
762 772
763IO/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>.
764 774
765Compatibility: L<Coro::LWP>, L<Coro::BDB>, L<Coro::Storable>, L<Coro::Select>. 775Compatibility with other modules: L<Coro::LWP> (but see also L<AnyEvent::HTTP> for
776a better-working alternative), L<Coro::BDB>, L<Coro::Storable>,
777L<Coro::Select>.
766 778
767XS API: L<Coro::MakeMaker>. 779XS API: L<Coro::MakeMaker>.
768 780
769Low level Configuration, Coroutine Environment: L<Coro::State>. 781Low level Configuration, Thread Environment, Continuations: L<Coro::State>.
770 782
771=head1 AUTHOR 783=head1 AUTHOR
772 784
773 Marc Lehmann <schmorp@schmorp.de> 785 Marc Lehmann <schmorp@schmorp.de>
774 http://home.schmorp.de/ 786 http://home.schmorp.de/

Diff Legend

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