--- Coro/Coro.pm 2008/11/20 06:32:55 1.229 +++ Coro/Coro.pm 2008/11/22 16:37:11 1.237 @@ -1,6 +1,6 @@ =head1 NAME -Coro - coroutine process abstraction +Coro - real threads in perl =head1 SYNOPSIS @@ -28,31 +28,39 @@ =head1 DESCRIPTION -This module collection manages coroutines. Coroutines are similar to -threads but don't (in general) run in parallel at the same time even -on SMP machines. The specific flavor of coroutine used in this module -also guarantees you that it will not switch between coroutines unless -necessary, at easily-identified points in your program, so locking and -parallel access are rarely an issue, making coroutine programming much -safer and easier than threads programming. - -Unlike a normal perl program, however, coroutines allow you to have -multiple running interpreters that share data, which is especially useful -to code pseudo-parallel processes and for event-based programming, such as -multiple HTTP-GET requests running concurrently. See L to -learn more. - -Coroutines are also useful because Perl has no support for threads (the so -called "threads" that perl offers are nothing more than the (bad) process -emulation coming from the Windows platform: On standard operating systems -they serve no purpose whatsoever, except by making your programs slow and -making them use a lot of memory. Best disable them when building perl, or -aks your software vendor/distributor to do it for you). - -In this module, coroutines are defined as "callchain + lexical variables + -@_ + $_ + $@ + $/ + C stack), that is, a coroutine has its own callchain, -its own set of lexicals and its own set of perls most important global -variables (see L for more configuration). +For a tutorial-style introduction, please read the L +manpage. This manpage mainly contains reference information. + +This module collection manages coroutines, that is, cooperative +threads. Coroutines are similar to kernel threads but don't (in general) +run in parallel at the same time even on SMP machines. The specific flavor +of coroutine used in this module also guarantees you that it will not +switch between coroutines unless necessary, at easily-identified points +in your program, so locking and parallel access are rarely an issue, +making coroutine programming much safer and easier than using other thread +models. + +Unlike the so-called "Perl threads" (which are not actually real threads +but only the windows process emulation ported to unix), Coro provides a +full shared address space, which makes communication between coroutines +very easy. And coroutines are fast, too: disabling the Windows process +emulation code in your perl and using Coro can easily result in a two to +four times speed increase for your programs. + +Coro achieves that by supporting multiple running interpreters that share +data, which is especially useful to code pseudo-parallel processes and +for event-based programming, such as multiple HTTP-GET requests running +concurrently. See L to learn more on how to integrate Coro +into an event-based environment. + +In this module, a coroutines is defined as "callchain + lexical variables ++ @_ + $_ + $@ + $/ + C stack), that is, a coroutine has its own +callchain, its own set of lexicals and its own set of perls most important +global variables (see L for more configuration and background +info). + +See also the C section at the end of this document - the Coro +module family is quite large. =cut @@ -69,7 +77,7 @@ our $main; # main coroutine our $current; # current coroutine -our $VERSION = 5.0; +our $VERSION = "5.0"; our @EXPORT = qw(async async_pool cede schedule terminate current unblock_sub); our %EXPORT_TAGS = ( @@ -77,6 +85,8 @@ ); our @EXPORT_OK = (@{$EXPORT_TAGS{prio}}, qw(nready)); +=head1 GLOBAL VARIABLES + =over 4 =item $Coro::main @@ -137,18 +147,6 @@ Carp::croak ("FATAL: deadlock detected"); }; -sub _cancel { - my ($self) = @_; - - # free coroutine data and mark as destructed - $self->_destroy - or return; - - # call all destruction callbacks - $_->(@{$self->{_status}}) - for @{ delete $self->{_on_destroy} || [] }; -} - # this coroutine is necessary because a coroutine # cannot destroy itself. our @destroy; @@ -156,7 +154,7 @@ $manager = new Coro sub { while () { - (shift @destroy)->_cancel + Coro::_cancel shift @destroy while @destroy; &schedule; @@ -167,7 +165,7 @@ =back -=head2 SIMPLE COROUTINE CREATION +=head1 SIMPLE COROUTINE CREATION =over 4 @@ -239,13 +237,13 @@ If you are concerned about pooled coroutines growing a lot because a single C used a lot of stackspace you can e.g. C once per second or so to slowly replenish the pool. In -addition to that, when the stacks used by a handler grows larger than 16kb +addition to that, when the stacks used by a handler grows larger than 32kb (adjustable via $Coro::POOL_RSS) it will also be destroyed. =cut our $POOL_SIZE = 8; -our $POOL_RSS = 16 * 1024; +our $POOL_RSS = 32 * 1024; our @async_pool; sub pool_handler { @@ -260,9 +258,10 @@ =back -=head2 STATIC METHODS +=head1 STATIC METHODS -Static methods are actually functions that operate on the current coroutine. +Static methods are actually functions that implicitly operate on the +current coroutine. =over 4 @@ -321,13 +320,6 @@ =cut -sub terminate { - $current->{_status} = [@_]; - push @destroy, $current; - $manager->ready; - do { &schedule } while 1; -} - sub killall { for (Coro::State::list) { $_->cancel @@ -337,7 +329,7 @@ =back -=head2 COROUTINE METHODS +=head1 COROUTINE OBJECT METHODS These are the methods you can call on coroutine objects (or to create them). @@ -519,9 +511,14 @@ $old; } +sub transfer { + require Carp; + Carp::croak ("You must not call ->transfer on Coro objects. Use Coro::State objects or the ->schedule_to method. Caught"); +} + =back -=head2 GLOBAL FUNCTIONS +=head1 GLOBAL FUNCTIONS =over 4 @@ -764,11 +761,14 @@ Support/Utility: L, L. -Locking/IPC: L, L, L, L, L. +Locking/IPC: L, L, L, +L, L. IO/Timers: L, L, L, L. -Compatibility: L, L, L, L. +Compatibility: L (but see also L for +a better-working alternative), L, L, +L. XS API: L.