[ViewVC] Diff of: cvs/cvsroot/Coro/Coro.pm

Comparing cvsroot/Coro/Coro.pm (file contents):
Revision 1.269 by root, Thu Oct 1 23:25:03 2009 UTC vs.
Revision 1.274 by root, Sat Dec 12 01:30:26 2009 UTC

 our $idle;    # idle handler
 our $main;    # main coro
 our $current; # current coro
-our $VERSION = 5.17;
+our $VERSION = 5.21;
-our @EXPORT = qw(async async_pool cede schedule terminate current unblock_sub);
+our @EXPORT = qw(async async_pool cede schedule terminate current unblock_sub rouse_cb rouse_wait);
 our %EXPORT_TAGS = (
       prio => [qw(PRIO_MAX PRIO_HIGH PRIO_NORMAL PRIO_LOW PRIO_IDLE PRIO_MIN)],
 );
 our @EXPORT_OK = (@{$EXPORT_TAGS{prio}}, qw(nready));
 This variable is mainly useful to integrate Coro into event loops. It is
 usually better to rely on L<Coro::AnyEvent> or L<Coro::EV>, as this is
 pretty low-level functionality.
-This variable stores either a Coro object or a callback.
+This variable stores a Coro object that is put into the ready queue when
+there are no other ready threads (without invoking any ready hooks).
-If it is a callback, the it is called whenever the scheduler finds no
+The default implementation dies with "FATAL: deadlock detected.", followed
-ready coros to run. The default implementation prints "FATAL:
+by a thread listing, because the program has no other way to continue.
-deadlock detected" and exits, because the program has no other way to
-continue.
-If it is a coro object, then this object will be readied (without
-invoking any ready hooks, however) when the scheduler finds no other ready
-coros to run.
 This hook is overwritten by modules such as C<Coro::EV> and
 C<Coro::AnyEvent> to wait on an external event that hopefully wake up a
 coro so the scheduler can run it.
-Note that the callback I<must not>, under any circumstances, block
-the current coro. Normally, this is achieved by having an "idle
-coro" that calls the event loop and then blocks again, and then
-readying that coro in the idle handler, or by simply placing the idle
-coro in this variable.
-See L<Coro::Event> or L<Coro::AnyEvent> for examples of using this
+See L<Coro::EV> or L<Coro::AnyEvent> for examples of using this technique.
-technique.
-Please note that if your callback recursively invokes perl (e.g. for event
-handlers), then it must be prepared to be called recursively itself.
 =cut
-$idle = sub {
+$idle = new Coro sub {
-   Carp::confess ("FATAL: deadlock detected");
+   require Coro::Debug;
+   die "FATAL: deadlock detected.\n"
+       . Coro::Debug::ps_listing ();
 };
 # this coro is necessary because a coro
 # cannot destroy itself.
 our @destroy;
 =item schedule
 Calls the scheduler. The scheduler will find the next coro that is
 to be run from the ready queue and switches to it. The next coro
 to be run is simply the one with the highest priority that is longest
-in its ready queue. If there is no coro ready, it will clal the
+in its ready queue. If there is no coro ready, it will call the
 C<$Coro::idle> hook.
 Please note that the current coro will I<not> be put into the ready
 queue, so calling this function usually means you will never be called
 again unless something else (e.g. an event handler) calls C<< ->ready >>,
 venerable L<Event|Event> module) are not thread-safe (a weaker form
 of reentrancy). This means you must not block within event callbacks,
 otherwise you might suffer from crashes or worse. The only event library
 currently known that is safe to use without C<unblock_sub> is L<EV>.
+Coro will try to catch you when you block in the event loop
+("FATAL:$Coro::IDLE blocked itself"), but this is just best effort and
+only works when you do not run your own event loop.
 This function allows your callbacks to block by executing them in another
 coro where it is safe to block. One example where blocking is handy
 is when you use the L<Coro::AIO|Coro::AIO> functions to save results to
 disk, for example.
       unshift @unblock_queue, [$cb, @_];
       $unblock_scheduler->ready;
    }
 }
-=item $cb = Coro::rouse_cb
+=item $cb = rouse_cb
 Create and return a "rouse callback". That's a code reference that,
 when called, will remember a copy of its arguments and notify the owner
 coro of the callback.
 See the next function.
-=item @args = Coro::rouse_wait [$cb]
+=item @args = rouse_wait [$cb]
 Wait for the specified rouse callback (or the last one that was created in
 this coro).
 As soon as the callback is invoked (or when the callback was invoked
 the windows process emulation enabled under unix roughly halves perl
 performance, even when not used.
 =item coro switching is not signal safe
-You must not switch to another coro from within a signal handler
+You must not switch to another coro from within a signal handler (only
-(only relevant with %SIG - most event libraries provide safe signals).
+relevant with %SIG - most event libraries provide safe signals), I<unless>
+you are sure you are not interrupting a Coro function.
 That means you I<MUST NOT> call any function that might "block" the
 current coro - C<cede>, C<schedule> C<< Coro::Semaphore->down >> or
 anything that calls those. Everything else, including calling C<ready>,
 works.

Diff Legend

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

Comparing cvsroot/Coro/Coro.pm (file contents): Revision 1.269 by root, Thu Oct 1 23:25:03 2009 UTC vs. Revision 1.274 by root, Sat Dec 12 01:30:26 2009 UTC

Diff Legend

Comparing cvsroot/Coro/Coro.pm (file contents):
Revision 1.269 by root, Thu Oct 1 23:25:03 2009 UTC vs.
Revision 1.274 by root, Sat Dec 12 01:30:26 2009 UTC