--- cvsroot/AnyEvent-Porttracker/Porttracker.pm	2010/11/16 19:43:15	1.14
+++ cvsroot/AnyEvent-Porttracker/Porttracker.pm	2011/05/20 22:57:52	1.15
@@ -14,16 +14,15 @@
    ;
 
    # Example 1
-   # a simple request: ping the server
+   # a simple request: ping the server synchronously
 
-   $api->req ("ping", sub {
-      my ($api, $ok, $timestamp, $pid) = @_;
-      ...
-   });
+   my ($timestamp, $pid) = $api->req_sync ("ping");
 
    # Example 2
    # find all realms, start a discovery on all of them
    # and wait until all discovery processes have finished
+   # but execute individual discoveries in parallel,
+   # asynchronously
 
    my $cv = AE::cv;
 
@@ -57,6 +56,8 @@
       warn "this just in: poll for realm <$gid> finished.\n";
    });
 
+   AE::cv->recv; # wait forever
+
 =head1 DESCRIPTION
 
 Porttracker (L<http://www.porttracker.com/>) is a product that (among
@@ -95,6 +96,7 @@
 
 use common::sense;
 
+use Carp ();
 use Scalar::Util ();
 
 use AnyEvent ();
@@ -104,7 +106,7 @@
 use Digest::HMAC_MD6 ();
 use JSON ();
 
-our $VERSION = '0.1';
+our $VERSION = '1.0';
 
 sub call {
    my ($self, $type, @args) = @_;
@@ -312,6 +314,26 @@
       : &_req
 }
 
+=item @res = $api->req_sync ($type => @args)
+
+Similar to C<< ->req >>, but waits for the results of the request and on
+success, returns the values instead (without the success flag, and only
+the first value in scalar context). On failure, the method will C<croak>
+with the error message.
+
+=cut
+
+sub req_sync {
+   push @_, my $cv = AE::cv;
+   &req;
+   my ($ok, @res) = $cv->recv;
+
+   $ok
+      or Carp::croak $res[0];
+
+   wantarray ? @res : $res[0]
+}
+
 =item $api->req_failok ($type => @args, $callback->($api, $success, @reply))
 
 Just like C<< ->req >>, with two differences: first, a failure will not