--- Coro/Coro.pm	2007/10/05 20:11:25	1.148
+++ Coro/Coro.pm	2008/04/19 19:06:02	1.179
@@ -4,19 +4,26 @@
 
 =head1 SYNOPSIS
 
- use Coro;
-
- async {
-    # some asynchronous thread of execution
- };
-
- # alternatively create an async coroutine like this:
-
- sub some_func : Coro {
-    # some more async code
- }
-
- cede;
+  use Coro;
+  
+  async {
+     # some asynchronous thread of execution
+     print "2\n";
+     cede; # yield back to main
+     print "4\n";
+  };
+  print "1\n";
+  cede; # yield to coroutine
+  print "3\n";
+  cede; # and again
+  
+  # use locking
+  my $lock = new Coro::Semaphore;
+  my $locked;
+  
+  $lock->down;
+  $locked = 1;
+  $lock->up;
 
 =head1 DESCRIPTION
 
@@ -35,7 +42,7 @@
 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.
+variables (see L<Coro::State> for more configuration).
 
 =cut
 
@@ -52,7 +59,7 @@
 our $main;    # main coroutine
 our $current; # current coroutine
 
-our $VERSION = '4.01';
+our $VERSION = '4.51';
 
 our @EXPORT = qw(async async_pool cede schedule terminate current unblock_sub);
 our %EXPORT_TAGS = (
@@ -60,40 +67,6 @@
 );
 our @EXPORT_OK = (@{$EXPORT_TAGS{prio}}, qw(nready));
 
-{
-   my @async;
-   my $init;
-
-   # this way of handling attributes simply is NOT scalable ;()
-   sub import {
-      no strict 'refs';
-
-      Coro->export_to_level (1, @_);
-
-      my $old = *{(caller)[0]."::MODIFY_CODE_ATTRIBUTES"}{CODE};
-      *{(caller)[0]."::MODIFY_CODE_ATTRIBUTES"} = sub {
-         my ($package, $ref) = (shift, shift);
-         my @attrs;
-         for (@_) {
-            if ($_ eq "Coro") {
-               push @async, $ref;
-               unless ($init++) {
-                  eval q{
-                     sub INIT {
-                        &async(pop @async) while @async;
-                     }
-                  };
-               }
-            } else {
-               push @attrs, $_;
-            }
-         }
-         return $old ? $old->($package, $ref, @attrs) : @attrs;
-      };
-   }
-
-}
-
 =over 4
 
 =item $main
@@ -136,7 +109,7 @@
 coroutine so the scheduler can run it.
 
 Please note that if your callback recursively invokes perl (e.g. for event
-handlers), then it must be prepared to be called recursively.
+handlers), then it must be prepared to be called recursively itself.
 
 =cut
 
@@ -173,8 +146,6 @@
 $manager->desc ("[coro manager]");
 $manager->prio (PRIO_MAX);
 
-# static methods. not really.
-
 =back
 
 =head2 STATIC METHODS
@@ -190,7 +161,7 @@
 terminated.
 
 See the C<Coro::State::new> constructor for info about the coroutine
-environment.
+environment in which coroutines run.
 
 Calling C<exit> in a coroutine will do the same as calling exit outside
 the coroutine. Likewise, when the coroutine dies, the program will exit,
@@ -257,7 +228,7 @@
          }
       };
 
-      last if $@ eq "\3terminate\2\n";
+      last if $@ eq "\3async_pool terminate\2\n";
       warn $@ if $@;
    }
 }
@@ -304,15 +275,11 @@
 ready queue and calls C<schedule>, which has the effect of giving up the
 current "timeslice" to other coroutines of the same or higher priority.
 
-Returns true if at least one coroutine switch has happened.
-
 =item Coro::cede_notself
 
 Works like cede, but is not exported by default and will cede to any
 coroutine, regardless of priority, once.
 
-Returns true if at least one coroutine switch has happened.
-
 =item terminate [arg...]
 
 Terminates the current coroutine with the given status values (see L<cancel>).
@@ -338,8 +305,6 @@
 
 =back
 
-# dynamic methods
-
 =head2 COROUTINE METHODS
 
 These are the methods you can call on coroutine objects.
@@ -473,6 +438,22 @@
 This method simply sets the C<< $coroutine->{desc} >> member to the given string. You
 can modify this member directly if you wish.
 
+=item $coroutine->throw ([$scalar])
+
+If C<$throw> is specified and defined, it will be thrown as an exception
+inside the coroutine at the next convinient point in time (usually after
+it gains control at the next schedule/transfer/cede). Otherwise clears the
+exception object.
+
+The exception object will be thrown "as is" with the specified scalar in
+C<$@>, i.e. if it is a string, no line number or newline will be appended
+(unlike with C<die>).
+
+This can be used as a softer means than C<cancel> to ask a coroutine to
+end itself, although there is no guarentee that the exception will lead to
+termination, and if the exception isn't caught it might well end the whole
+program.
+
 =cut
 
 sub desc {
@@ -599,13 +580,19 @@
 
 =head1 SEE ALSO
 
-Support/Utility: L<Coro::Specific>, L<Coro::State>, L<Coro::Util>.
+Lower level Configuration, Coroutine Environment: L<Coro::State>.
+
+Debugging: L<Coro::Debug>.
+
+Support/Utility: L<Coro::Specific>, L<Coro::Util>.
 
 Locking/IPC: L<Coro::Signal>, L<Coro::Channel>, L<Coro::Semaphore>, L<Coro::SemaphoreSet>, L<Coro::RWLock>.
 
-Event/IO: L<Coro::Timer>, L<Coro::Event>, L<Coro::Handle>, L<Coro::Socket>, L<Coro::Select>.
+Event/IO: L<Coro::Timer>, L<Coro::Event>, L<Coro::Handle>, L<Coro::Socket>.
+
+Compatibility: L<Coro::LWP>, L<Coro::Storable>, L<Coro::Select>.
 
-Embedding: L<Coro:MakeMaker>
+Embedding: L<Coro::MakeMaker>.
 
 =head1 AUTHOR