[ViewVC] Diff of: cvs/AnyEvent-FCP/FCP.pm

Comparing AnyEvent-FCP/FCP.pm (file contents):
Revision 1.11 by root, Fri Aug 7 01:54:00 2015 UTC vs.
Revision 1.12 by root, Sat Aug 8 04:02:48 2015 UTC

       $self->{id}{$kv->{identifier}}($self, $type, $kv, $rdata)
          and delete $self->{id}{$kv->{identifier}};
    }
 }
+=back
+=head2 FCP REQUESTS
+The following methods implement various requests. Most of them map
+directory to the FCP message of the same name. The added benefit of
+these over sending requests yourself is that they handle the necessary
+serialisation, protocol quirks, and replies.
+All of them exist in two versions, the variant shown in this manpage, and
+a variant with an extra C<_> at the end, and an extra C<$cb> argument. The
+version as shown is I<synchronous> - it will wait for any replies, and
+either return the reply, or croak with an error. The underscore variant
+returns immediately and invokes one or more callbacks or condvars later.
+For example, the call
+   $info = $fcp->get_plugin_info ($name, $detailed);
+Also comes in this underscore variant:
+   $fcp->get_plugin_info_ ($name, $detailed, $cb);
+You can thinbk of the underscore as a kind of continuation indicator - the
+normal function waits and returns with the data, the C<_> indicates that
+you pass the continuation yourself, and the continuation will be invoked
+with the results.
+This callback/continuation argument (C<$cb>) can come in three forms itself:
+=over 4
+=item A code reference (or rather anything not matching some other alternative)
+This code reference will be invoked with the result on success. On an
+error, it will die (in the event loop) with a backtrace of the call site.
+This is a popular choice, but it makes handling errors hard - make sure
+you never generate protocol errors!
+=item A condvar (as returned by e.g. C<< AnyEvent->condvar >>)
+When a condvar is passed, it is sent (C<< $cv->send ($results) >>) the
+results when the request has finished. Should an error occur, the error
+will instead result in C<< $cv->croak ($error) >>.
+This is also a popular choice.
+=item An array with two callbacks C<[$success, $failure]>
+The C<$success> callback will be invoked with the results, while the
+C<$failure> callback will be invoked on any errors.
+=item C<undef>
+This is the same thing as specifying C<sub { }> as callback, i.e. on
+success, the results are ignored, while on failure, you the module dies
+with a backtrace.
+This is good for quick scripts, or when you really aren't interested in
+the results.
+=back
+=cut
 our $NOP_CB = sub { };
 sub _txn {
    my ($name, $sub) = @_;
    *{$name} = sub {
-      splice @_, 1, 0, (my $cv = AnyEvent->condvar);
+      my $cv = AE::cv;
+      splice @_, 1, 0, $cv, sub { $cv->throw ($_[0]{extra_description}) };
       &$sub;
       $cv->recv
    };
    *{"$name\_"} = sub {
+      my ($ok, $err) = pop;
+      if (ARRAY:: eq ref $ok) {
+         ($ok, $err) = @$ok;
+      } elsif (UNIVERSAL::isa $ok, AnyEvent::CondVar::) {
+         $err = sub { $ok->throw ($_[0]{extra_description}) };
+      } else {
+         my $bt = Carp::longmess "";
+         $err = sub {
+            die "$_[0]{extra_description}$bt";
+         };
+      }
+      $ok ||= $NOP_CB;
-      splice @_, 1, 0, pop || $NOP_CB;
+      splice @_, 1, 0, $ok, $err;
       &$sub;
    };
 }
+=over 4
 =item $peers = $fcp->list_peers ([$with_metdata[, $with_volatile]])
 =cut
 _txn list_peers => sub {
-   my ($self, $cv, $with_metadata, $with_volatile) = @_;
+   my ($self, $ok, undef, $with_metadata, $with_volatile) = @_;
    my @res;
    $self->send_msg (list_peers =>
       with_metadata => $with_metadata ? "true" : "false",
       with_volatile => $with_volatile ? "true" : "false",
       id_cb         => sub {
          my ($self, $type, $kv, $rdata) = @_;
          if ($type eq "end_list_peers") {
-            $cv->(\@res);
+            $ok->(\@res);
             1
          } else {
             push @res, $kv;
             0
          }
 =item $notes = $fcp->list_peer_notes ($node_identifier)
 =cut
 _txn list_peer_notes => sub {
-   my ($self, $cv, $node_identifier) = @_;
+   my ($self, $ok, undef, $node_identifier) = @_;
    $self->send_msg (list_peer_notes =>
       node_identifier => $node_identifier,
       id_cb           => sub {
          my ($self, $type, $kv, $rdata) = @_;
-         $cv->($kv);
+         $ok->($kv);
          1
       },
    );
 };
 =item $fcp->watch_global ($enabled[, $verbosity_mask])
 =cut
 _txn watch_global => sub {
-   my ($self, $cv, $enabled, $verbosity_mask) = @_;
+   my ($self, $ok, $err, $enabled, $verbosity_mask) = @_;
    $self->send_msg (watch_global =>
       enabled        => $enabled ? "true" : "false",
       defined $verbosity_mask ? (verbosity_mask => $verbosity_mask+0) : (),
    );
-   $cv->();
+   $ok->();
 };
 =item $reqs = $fcp->list_persistent_requests
 =cut
 _txn list_persistent_requests => sub {
-   my ($self, $cv) = @_;
+   my ($self, $ok, $err) = @_;
    $self->serialise (list_persistent_requests => sub {
       my ($self, $guard) = @_;
       my @res;
          my ($self, $type, $kv, $rdata) = @_;
          $guard if 0;
          if ($type eq "end_list_persistent_requests") {
-            $cv->(\@res);
+            $ok->(\@res);
             return;
          } else {
             my $id = $kv->{identifier};
             if ($type =~ /^persistent_(get|put|put_dir)$/) {
          1
       });
    });
 };
-=item $status = $fcp->remove_request ($global, $identifier)
+=item $sync = $fcp->modify_persistent_request ($global, $identifier[, $client_token[, $priority_class]])
-=cut
+Update either the C<client_token> or C<priority_class> of a request
+identified by C<$global> and C<$identifier>, depending on which of
+C<$client_token> and C<$priority_class> are not C<undef>.
-_txn remove_request => sub {
+=cut
-   my ($self, $cv, $global, $identifier) = @_;
+_txn modify_persistent_request => sub {
+   my ($self, $ok, $err, $global, $identifier, $client_token, $priority_class) = @_;
+   $self->serialise ($identifier => sub {
+      my ($self, $guard) = @_;
-   $self->send_msg (remove_request =>
+      $self->send_msg (modify_persistent_request =>
-      global     => $global ? "true" : "false",
+         global     => $global ? "true" : "false",
-      identifier => $identifier,
+         identifier => $identifier,
-      id_cb      => sub {
+         defined $client_token   ? (client_token   => $client_token  ) : (),
+         defined $priority_class ? (priority_class => $priority_class) : (),
+      );
+      $self->on (sub {
-         my ($self, $type, $kv, $rdata) = @_;
+         my ($self, $type, $kv, @extra) = @_;
+         if ($kv->{identifier} eq $identifier) {
+            if ($type eq "persistent_request_modified") {
-         $cv->($kv);
+               $ok->($kv);
+               return;
+            } elsif ($type eq "protocol_error") {
+               $err->($kv);
+               return;
+            }
+         }
          1
-      },
+      });
-   );
+   });
 };
-=item $sync = $fcp->modify_persistent_request ($global, $identifier[, $client_token[, $priority_class]])
-=cut
-_txn modify_persistent_request => sub {
-   my ($self, $cv, $global, $identifier, $client_token, $priority_class) = @_;
-   $self->send_msg (modify_persistent_request =>
-      global     => $global ? "true" : "false",
-      defined $client_token   ? (client_token   => $client_token  ) : (),
-      defined $priority_class ? (priority_class => $priority_class) : (),
-      identifier => $identifier,
-      id_cb      => sub {
-         my ($self, $type, $kv, $rdata) = @_;
-         $cv->($kv);
-         1
-      },
-   );
-};
 =item $info = $fcp->get_plugin_info ($name, $detailed)
 =cut
 _txn get_plugin_info => sub {
-   my ($self, $cv, $name, $detailed) = @_;
+   my ($self, $ok, $err, $name, $detailed) = @_;
    $self->send_msg (get_plugin_info =>
       plugin_name => $name,
       detailed    => $detailed ? "true" : "false",
       id_cb       => sub {
          my ($self, $type, $kv, $rdata) = @_;
-         $cv->($kv);
+         $ok->($kv);
          1
       },
    );
 };
 binary_blob, allowed_mime_types, filename, temp_filename
 =cut
 _txn client_get => sub {
-   my ($self, $cv, $uri, $identifier, %kv) = @_;
+   my ($self, $ok, $err, $uri, $identifier, %kv) = @_;
    $self->send_msg (client_get =>
       %kv,
       uri        => $uri,
       identifier => $identifier,
    );
+   $ok->();
 };
 =item $status = $fcp->remove_request ($identifier[, $global])
 Remove the request with the given isdentifier. Returns true if successful,
 false on error.
 =cut
 _txn remove_request => sub {
-   my ($self, $cv, $identifier, $global) = @_;
+   my ($self, $ok, $err, $identifier, $global) = @_;
    $self->serialise ($identifier => sub {
       my ($self, $guard) = @_;
       $self->send_msg (remove_request =>
       $self->on (sub {
          my ($self, $type, $kv, @extra) = @_;
          if ($kv->{identifier} eq $identifier) {
             if ($type eq "persistent_request_removed") {
-               $cv->(1);
+               $ok->(1);
                return;
             } elsif ($type eq "protocol_error") {
-               $cv->(undef);
+               $err->($kv);
                return;
             }
          }
          1
 directory.
 =cut
 _txn test_dda => sub {
-   my ($self, $cv, $local, $remote, $want_read, $want_write) = @_;
+   my ($self, $ok, $err, $local, $remote, $want_read, $want_write) = @_;
    $self->serialise (test_dda => sub {
       my ($self, $guard) = @_;
       $self->send_msg (test_dda_request =>
                my ($self, $type, $kv) = @_;
                $guard if 0; # reference
                if ($type eq "test_dda_complete") {
-                  $cv->(
+                  $ok->(
                      $kv->{read_directory_allowed} eq "true",
                      $kv->{write_directory_allowed} eq "true",
                   );
                } elsif ($type eq "protocol_error" && $kv->{identifier} eq $remote) {
-                  $cv->croak ($kv->{extra_description});
+                  $err->($kv->{extra_description});
                   return;
                }
                1
             });
             return;
          } elsif ($type eq "protocol_error" && $kv->{identifier} eq $remote) {
-            $cv->croak ($kv->{extra_description});
+            $err->($kv);
             return;
          }
          1
       });

Diff Legend

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

Comparing AnyEvent-FCP/FCP.pm (file contents): Revision 1.11 by root, Fri Aug 7 01:54:00 2015 UTC vs. Revision 1.12 by root, Sat Aug 8 04:02:48 2015 UTC

Diff Legend

Comparing AnyEvent-FCP/FCP.pm (file contents):
Revision 1.11 by root, Fri Aug 7 01:54:00 2015 UTC vs.
Revision 1.12 by root, Sat Aug 8 04:02:48 2015 UTC