--- AnyEvent/lib/AnyEvent.pm	2009/07/29 12:39:21	1.263
+++ AnyEvent/lib/AnyEvent.pm	2009/07/30 03:41:56	1.266
@@ -183,6 +183,12 @@
 
 =head2 I/O WATCHERS
 
+   $w = AnyEvent->io (
+      fh   => <filehandle_or_fileno>,
+      poll => <"r" or "w">,
+      cb   => <callback>,
+   );
+
 You can create an I/O watcher by calling the C<< AnyEvent->io >> method
 with the following mandatory key-value pairs as arguments:
 
@@ -221,6 +227,14 @@
 
 =head2 TIME WATCHERS
 
+   $w = AnyEvent->timer (after => <seconds>, cb => <callback>);
+
+   $w = AnyEvent->timer (
+      after    => <fractional_seconds>,
+      interval => <fractional_seconds>,
+      cb       => <callback>,
+   );
+
 You can create a time watcher by calling the C<< AnyEvent->timer >>
 method with the following mandatory arguments:
 
@@ -357,6 +371,8 @@
 
 =head2 SIGNAL WATCHERS
 
+   $w = AnyEvent->signal (signal => <uppercase_signal_name>, cb => <callback>);
+
 You can watch for signals using a signal watcher, C<signal> is the signal
 I<name> in uppercase and without any C<SIG> prefix, C<cb> is the Perl
 callback to be invoked whenever a signal occurs.
@@ -400,6 +416,8 @@
 
 =head2 CHILD PROCESS WATCHERS
 
+   $w = AnyEvent->child (pid => <process id>, cb => <callback>);
+
 You can also watch on a child process exit and catch its exit status.
 
 The child process is specified by the C<pid> argument (one some backends,
@@ -457,6 +475,8 @@
 
 =head2 IDLE WATCHERS
 
+   $w = AnyEvent->idle (cb => <callback>);
+
 Sometimes there is a need to do something, but it is not so important
 to do it instantly, but only when there is nothing better to do. This
 "nothing better to do" is usually defined to be "no other events need
@@ -492,6 +512,11 @@
 
 =head2 CONDITION VARIABLES
 
+   $cv = AnyEvent->condvar;
+
+   $cv->send (<list>);
+   my @res = $cv->recv;
+
 If you are familiar with some event loops you will know that all of them
 require you to run some blocking "loop", "run" or similar function that
 will actively watch for new events and call your callbacks.
@@ -1336,126 +1361,131 @@
       unless --$SIG_COUNT;
 }
 
-our %SIGNAME2NUM;
-our @SIGNUM2NAME;
 our $_sig_name_init; $_sig_name_init = sub {
-   undef $_sig_name_init;
-
-   if (_have_async_interrupt) {
-      *sig2num  = \&Async::Interrupt::sig2num;
-      *sig2name = \&Async::Interrupt::sig2name;
-   } else {
-      require Config;
+   eval q{ # poor man's autoloading
+      undef $_sig_name_init;
 
-      @SIGNAME2NUM{ split ' ', $Config::Config{sig_name} }
-                  = split ' ', $Config::Config{sig_num};
-      @SIGNUM2NAME[values %SIGNAME2NUM] = keys %SIGNAME2NUM;
+      if (_have_async_interrupt) {
+         *sig2num  = \&Async::Interrupt::sig2num;
+         *sig2name = \&Async::Interrupt::sig2name;
+      } else {
+         require Config;
 
-      *sig2num = sub($) {
-         $_[0] > 0 ? shift : $SIGNAME2NUM{+shift}
-      };
-      *sig2name = sub ($) {
-         $_[0] > 0 ? $SIGNUM2NAME[+shift] : shift
-      };
-   }
+         my %signame2num;
+         @signame2num{ split ' ', $Config::Config{sig_name} }
+                        = split ' ', $Config::Config{sig_num};
+
+         my @signum2name;
+         @signum2name[values %signame2num] = keys %signame2num;
+
+         *sig2num = sub($) {
+            $_[0] > 0 ? shift : $signame2num{+shift}
+         };
+         *sig2name = sub ($) {
+            $_[0] > 0 ? $signum2name[+shift] : shift
+         };
+      }
+   };
+   die if $@;
 };
 
 sub sig2num ($) { &$_sig_name_init; &sig2num  }
 sub sig2name($) { &$_sig_name_init; &sig2name }
 
-sub _signal {
-   my (undef, %arg) = @_;
-
-   my $signal = uc $arg{signal}
-      or Carp::croak "required option 'signal' is missing";
-
-   if ($HAVE_ASYNC_INTERRUPT) {
-      # async::interrupt
+sub signal {
+   eval q{ # poor man's autoloading {}
+      # probe for availability of Async::Interrupt 
+      if (_have_async_interrupt) {
+         warn "AnyEvent: using Async::Interrupt for race-free signal handling.\n" if $VERBOSE >= 8;
 
-      $signal = sig2num $signal;
-      $SIG_CB{$signal}{$arg{cb}} = $arg{cb};
+         $SIGPIPE_R = new Async::Interrupt::EventPipe;
+         $SIG_IO = AnyEvent->io (fh => $SIGPIPE_R->fileno, poll => "r", cb => \&_signal_exec);
 
-      $SIG_ASY{$signal} ||= new Async::Interrupt
-         cb             => sub { undef $SIG_EV{$signal} },
-         signal         => $signal,
-         pipe           => [$SIGPIPE_R->filenos],
-         pipe_autodrain => 0,
-      ;
+      } else {
+         warn "AnyEvent: using emulated perl signal handling with latency timer.\n" if $VERBOSE >= 8;
 
-   } else {
-      # pure perl
+         require Fcntl;
 
-      # AE::Util has been loaded in signal
-      $signal = sig2name $signal;
-      $SIG_CB{$signal}{$arg{cb}} = $arg{cb};
-
-      $SIG{$signal} ||= sub {
-         local $!;
-         syswrite $SIGPIPE_W, "\x00", 1 unless %SIG_EV;
-         undef $SIG_EV{$signal};
-      };
+         if (AnyEvent::WIN32) {
+            require AnyEvent::Util;
 
-      # can't do signal processing without introducing races in pure perl,
-      # so limit the signal latency.
-      _sig_add;
-   }
+            ($SIGPIPE_R, $SIGPIPE_W) = AnyEvent::Util::portable_pipe ();
+            AnyEvent::Util::fh_nonblocking ($SIGPIPE_R, 1) if $SIGPIPE_R;
+            AnyEvent::Util::fh_nonblocking ($SIGPIPE_W, 1) if $SIGPIPE_W; # just in case
+         } else {
+            pipe $SIGPIPE_R, $SIGPIPE_W;
+            fcntl $SIGPIPE_R, &Fcntl::F_SETFL, &Fcntl::O_NONBLOCK if $SIGPIPE_R;
+            fcntl $SIGPIPE_W, &Fcntl::F_SETFL, &Fcntl::O_NONBLOCK if $SIGPIPE_W; # just in case
+
+            # not strictly required, as $^F is normally 2, but let's make sure...
+            fcntl $SIGPIPE_R, &Fcntl::F_SETFD, &Fcntl::FD_CLOEXEC;
+            fcntl $SIGPIPE_W, &Fcntl::F_SETFD, &Fcntl::FD_CLOEXEC;
+         }
 
-   bless [$signal, $arg{cb}], "AnyEvent::Base::signal"
-}
+         $SIGPIPE_R
+            or Carp::croak "AnyEvent: unable to create a signal reporting pipe: $!\n";
 
-sub signal {
-   # probe for availability of Async::Interrupt
-   if (_have_async_interrupt) {
-      warn "AnyEvent: using Async::Interrupt for race-free signal handling.\n" if $VERBOSE >= 8;
+         $SIG_IO = AnyEvent->io (fh => $SIGPIPE_R, poll => "r", cb => \&_signal_exec);
+      }
 
-      $SIGPIPE_R = new Async::Interrupt::EventPipe;
-      $SIG_IO = AnyEvent->io (fh => $SIGPIPE_R->fileno, poll => "r", cb => \&_signal_exec);
+      *signal = sub {
+         my (undef, %arg) = @_;
 
-   } else {
-      warn "AnyEvent: using emulated perl signal handling with latency timer.\n" if $VERBOSE >= 8;
+         my $signal = uc $arg{signal}
+            or Carp::croak "required option 'signal' is missing";
 
-      require Fcntl;
+         if ($HAVE_ASYNC_INTERRUPT) {
+            # async::interrupt
 
-      if (AnyEvent::WIN32) {
-         require AnyEvent::Util;
+            $signal = sig2num $signal;
+            $SIG_CB{$signal}{$arg{cb}} = $arg{cb};
+
+            $SIG_ASY{$signal} ||= new Async::Interrupt
+               cb             => sub { undef $SIG_EV{$signal} },
+               signal         => $signal,
+               pipe           => [$SIGPIPE_R->filenos],
+               pipe_autodrain => 0,
+            ;
 
-         ($SIGPIPE_R, $SIGPIPE_W) = AnyEvent::Util::portable_pipe ();
-         AnyEvent::Util::fh_nonblocking ($SIGPIPE_R) if $SIGPIPE_R;
-         AnyEvent::Util::fh_nonblocking ($SIGPIPE_W) if $SIGPIPE_W; # just in case
-      } else {
-         pipe $SIGPIPE_R, $SIGPIPE_W;
-         fcntl $SIGPIPE_R, &Fcntl::F_SETFL, &Fcntl::O_NONBLOCK if $SIGPIPE_R;
-         fcntl $SIGPIPE_W, &Fcntl::F_SETFL, &Fcntl::O_NONBLOCK if $SIGPIPE_W; # just in case
-
-         # not strictly required, as $^F is normally 2, but let's make sure...
-         fcntl $SIGPIPE_R, &Fcntl::F_SETFD, &Fcntl::FD_CLOEXEC;
-         fcntl $SIGPIPE_W, &Fcntl::F_SETFD, &Fcntl::FD_CLOEXEC;
-      }
-
-      $SIGPIPE_R
-         or Carp::croak "AnyEvent: unable to create a signal reporting pipe: $!\n";
+         } else {
+            # pure perl
 
-      $SIG_IO = AnyEvent->io (fh => $SIGPIPE_R, poll => "r", cb => \&_signal_exec);
-   }
+            # AE::Util has been loaded in signal
+            $signal = sig2name $signal;
+            $SIG_CB{$signal}{$arg{cb}} = $arg{cb};
+
+            $SIG{$signal} ||= sub {
+               local $!;
+               syswrite $SIGPIPE_W, "\x00", 1 unless %SIG_EV;
+               undef $SIG_EV{$signal};
+            };
+
+            # can't do signal processing without introducing races in pure perl,
+            # so limit the signal latency.
+            _sig_add;
+         }
 
-   *signal = \&_signal;
-   &signal
-}
+         bless [$signal, $arg{cb}], "AnyEvent::Base::signal"
+      };
 
-sub AnyEvent::Base::signal::DESTROY {
-   my ($signal, $cb) = @{$_[0]};
+      *AnyEvent::Base::signal::DESTROY = sub {
+         my ($signal, $cb) = @{$_[0]};
 
-   _sig_del;
+         _sig_del;
 
-   delete $SIG_CB{$signal}{$cb};
+         delete $SIG_CB{$signal}{$cb};
 
-   $HAVE_ASYNC_INTERRUPT
-      ? delete $SIG_ASY{$signal}
-      : # delete doesn't work with older perls - they then
-        # print weird messages, or just unconditionally exit
-        # instead of getting the default action.
-        undef $SIG{$signal}
-      unless keys %{ $SIG_CB{$signal} };
+         $HAVE_ASYNC_INTERRUPT
+            ? delete $SIG_ASY{$signal}
+            : # delete doesn't work with older perls - they then
+              # print weird messages, or just unconditionally exit
+              # instead of getting the default action.
+              undef $SIG{$signal}
+            unless keys %{ $SIG_CB{$signal} };
+      };
+   };
+   die if $@;
+   &signal
 }
 
 # default implementation for ->child
@@ -1620,6 +1650,48 @@
 *broadcast = \&send;
 *wait      = \&_wait;
 
+#############################################################################
+# "new" API, currently only emulation of it
+#############################################################################
+
+package AE;
+
+sub io($$$) {
+   AnyEvent->io (fh => $_[0], poll => $_[1] ? "w" : "r", cb => $_[2])
+}
+
+sub timer($$$) {
+   AnyEvent->timer (after => $_[0], interval => $_[1], cb => $_[2]);
+}
+
+sub signal($$) {
+   AnyEvent->signal (signal => $_[0], cb => $_[1]);
+}
+
+sub child($$) {
+   AnyEvent->child (pid => $_[0], cb => $_[1]);
+}
+
+sub idle($) {
+   AnyEvent->idle (cb => $_[0]);
+}
+
+sub cv() {
+   AnyEvent->condvar
+}
+
+sub now() {
+   AnyEvent->now
+}
+
+sub now_update() {
+   AnyEvent->now_update
+}
+
+sub time() {
+   AnyEvent->time
+}
+
 =head1 ERROR AND EXCEPTION HANDLING
 
 In general, AnyEvent does not do any error handling - it relies on the