--- Coro/Coro.pm	2008/11/03 16:05:37	1.207
+++ Coro/Coro.pm	2008/11/18 10:44:07	1.223
@@ -58,7 +58,7 @@
 
 package Coro;
 
-use strict;
+use strict qw(vars subs);
 no warnings "uninitialized";
 
 use Coro::State;
@@ -69,7 +69,7 @@
 our $main;    # main coroutine
 our $current; # current coroutine
 
-our $VERSION = 4.803;
+our $VERSION = 5.0;
 
 our @EXPORT = qw(async async_pool cede schedule terminate current unblock_sub);
 our %EXPORT_TAGS = (
@@ -88,13 +88,13 @@
 
 =cut
 
-$main = new Coro;
+# $main is now being initialised by Coro::State
 
 =item $Coro::current
 
 The coroutine object representing the current coroutine (the last
 coroutine that the Coro scheduler switched to). The initial value is
-C<$main> (of course).
+C<$Coro::main> (of course).
 
 This variable is B<strictly> I<read-only>. You can take copies of the
 value stored in it and use it as any other coroutine object, but you must
@@ -102,14 +102,6 @@
 
 =cut
 
-$main->{desc} = "[main::]";
-
-# maybe some other module used Coro::Specific before...
-$main->{_specific} = $current->{_specific}
-   if $current;
-
-_set_current $main;
-
 sub current() { $current } # [DEPRECATED]
 
 =item $Coro::idle
@@ -154,7 +146,7 @@
 
    # call all destruction callbacks
    $_->(@{$self->{_status}})
-      for @{(delete $self->{_on_destroy}) || []};
+      for @{ delete $self->{_on_destroy} || [] };
 }
 
 # this coroutine is necessary because a coroutine
@@ -170,7 +162,7 @@
       &schedule;
    }
 };
-$manager->desc ("[coro manager]");
+$manager->{desc} = "[coro manager]";
 $manager->prio (PRIO_MAX);
 
 =back
@@ -277,7 +269,7 @@
 }
 
 sub async_pool(&@) {
-   # this is also inlined into the unlock_scheduler
+   # this is also inlined into the unblock_scheduler
    my $coro = (pop @async_pool) || new Coro \&pool_handler;
 
    $coro->{_invoke} = [@_];
@@ -443,6 +435,29 @@
    }
 }
 
+=item $coroutine->throw ([$scalar])
+
+If C<$throw> is specified and defined, it will be thrown as an exception
+inside the coroutine at the next convenient point in time. Otherwise
+clears the exception object.
+
+Coro will check for the exception each time a schedule-like-function
+returns, i.e. after each C<schedule>, C<cede>, C<< Coro::Semaphore->down
+>>, C<< Coro::Handle->readable >> and so on. Most of these functions
+detect this case and return early in case an exception is pending.
+
+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 guarantee that the exception will lead to
+termination, and if the exception isn't caught it might well end the whole
+program.
+
+You might also think of C<throw> as being the moral equivalent of
+C<kill>ing a coroutine with a signal (in this case, a scalar).
+
 =item $coroutine->join
 
 Wait until the coroutine terminates and return any values given to the
@@ -513,26 +528,11 @@
 =item $olddesc = $coroutine->desc ($newdesc)
 
 Sets (or gets in case the argument is missing) the description for this
-coroutine. This is just a free-form string you can associate with a coroutine.
-
-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.
+coroutine. This is just a free-form string you can associate with a
+coroutine.
 
-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.
+This method simply sets the C<< $coroutine->{desc} >> member to the given
+string. You can modify this member directly if you wish.
 
 =cut
 
@@ -644,7 +644,7 @@
       schedule; # sleep well
    }
 };
-$unblock_scheduler->desc ("[unblock_sub scheduler]");
+$unblock_scheduler->{desc} = "[unblock_sub scheduler]";
 
 sub unblock_sub(&) {
    my $cb = shift;
@@ -663,11 +663,36 @@
 
 =head1 BUGS/LIMITATIONS
 
+=over 4
+
+=item fork with pthread backend
+
+When Coro is compiled using the pthread backend (which isn't recommended
+but required on many BSDs as their libcs are completely broken), then
+coroutines will not survive a fork. There is no known workaround except to
+fix your libc and use a saner backend.
+
+=item perl process emulation ("threads")
+
 This module is not perl-pseudo-thread-safe. You should only ever use this
 module from the same thread (this requirement might be removed in the
 future to allow per-thread schedulers, but Coro::State does not yet allow
-this). I recommend disabling thread support and using processes, as this
-is much faster and uses less memory.
+this). I recommend disabling thread support and using processes, as having
+the windows process emulation enabled under unix roughly halves perl
+performance, even when not used.
+
+=item coroutine switching not signal safe
+
+You must not switch to another coroutine from within a signal handler
+(only relevant with %SIG - most event libraries provide safe signals).
+
+That means you I<MUST NOT> call any function that might "block" the
+current coroutine - C<cede>, C<schedule> C<< Coro::Semaphore->down >> or
+anything that calls those. Everything else, including calling C<ready>,
+works.
+
+=back
+
 
 =head1 SEE ALSO