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

Comparing cvsroot/Coro/Coro.pm (file contents):
Revision 1.270 by root, Thu Oct 1 23:50:23 2009 UTC vs.
Revision 1.283 by root, Sat Feb 5 21:20:47 2011 UTC

 our $idle;    # idle handler
 our $main;    # main coro
 our $current; # current coro
-our $VERSION = 5.17;
+our $VERSION = 5.25;
-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));
 See L<Coro::EV> or L<Coro::AnyEvent> for examples of using this technique.
 =cut
+# ||= because other modules could have provided their own by now
-$idle = new Coro sub {
+$idle ||= new Coro sub {
    require Coro::Debug;
    die "FATAL: deadlock detected.\n"
        . Coro::Debug::ps_listing ();
 };
 Sets (or gets in case the argument is missing) the description for this
 coro. This is just a free-form string you can associate with a
 coro.
 This method simply sets the C<< $coro->{desc} >> member to the given
-string. You can modify this member directly if you wish.
+string. You can modify this member directly if you wish, and in fact, this
+is often preferred to indicate major processing states that cna then be
+seen for example in a L<Coro::Debug> session:
+   sub my_long_function {
+      local $Coro::current->{desc} = "now in my_long_function";
+      ...
+      $Coro::current->{desc} = "my_long_function: phase 1";
+      ...
+      $Coro::current->{desc} = "my_long_function: phase 2";
+      ...
+   }
 =cut
 sub desc {
    my $old = $_[0]{desc};
 returning a new coderef. Unblocking means that calling the new coderef
 will return immediately without blocking, returning nothing, while the
 original code ref will be called (with parameters) from within another
 coro.
-The reason this function exists is that many event libraries (such as the
+The reason this function exists is that many event libraries (such as
-venerable L<Event|Event> module) are not thread-safe (a weaker form
+the 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>.
+currently known that is safe to use without C<unblock_sub> is L<EV> (but
+you might still run into deadlocks if all event loops are blocked).
+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
 See the section B<HOW TO WAIT FOR A CALLBACK> for an actual usage example.
 =back
 =cut
+for my $module (qw(Channel RWLock Semaphore SemaphoreSet Signal Specific)) {
+   my $old = defined &{"Coro::$module\::new"} && \&{"Coro::$module\::new"};
+   *{"Coro::$module\::new"} = sub {
+      require "Coro/$module.pm";
+      # some modules have their new predefined in State.xs, some don't
+      *{"Coro::$module\::new"} = $old
+         if $old;
+      goto &{"Coro::$module\::new"};
+   };
+}
 1;
 =head1 HOW TO WAIT FOR A CALLBACK
 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.
 ithreads (for example, that memory or files would be shared), showing his
 lack of understanding of this area - if it is hard to understand for Chip,
 it is probably not obvious to everybody).
 What follows is an ultra-condensed version of my talk about threads in
-scripting languages given onthe perl workshop 2009:
+scripting languages given on the perl workshop 2009:
 The so-called "ithreads" were originally implemented for two reasons:
 first, to (badly) emulate unix processes on native win32 perls, and
 secondly, to replace the older, real thread model ("5.005-threads").

Diff Legend

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

Comparing cvsroot/Coro/Coro.pm (file contents): Revision 1.270 by root, Thu Oct 1 23:50:23 2009 UTC vs. Revision 1.283 by root, Sat Feb 5 21:20:47 2011 UTC

Diff Legend

Comparing cvsroot/Coro/Coro.pm (file contents):
Revision 1.270 by root, Thu Oct 1 23:50:23 2009 UTC vs.
Revision 1.283 by root, Sat Feb 5 21:20:47 2011 UTC