ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/AnyEvent-FCP/FCP.pm
(Generate patch)

Comparing AnyEvent-FCP/FCP.pm (file contents):
Revision 1.19 by root, Tue Jun 7 18:53:23 2016 UTC vs.
Revision 1.21 by root, Sun Jun 12 01:48:05 2016 UTC

… …
61 61
62use common::sense; 62use common::sense;
63 63
64use Carp; 64use Carp;
65 65
66our $VERSION = 0.4; 66our $VERSION = 0.5;
67 67
68use Scalar::Util (); 68use Scalar::Util ();
69 69
70use AnyEvent; 70use AnyEvent;
71use AnyEvent::Handle; 71use AnyEvent::Handle;
… …
86 1 while s/([^_])(SVK|CHK|URI|FCP|DS|MIME|DDA)/$1\_$2/; 86 1 while s/([^_])(SVK|CHK|URI|FCP|DS|MIME|DDA)/$1\_$2/;
87 s/(?<=[a-z])(?=[A-Z])/_/g; 87 s/(?<=[a-z])(?=[A-Z])/_/g;
88 lc 88 lc
89} 89}
90 90
91=item $fcp = new AnyEvent::FCP [host => $host][, port => $port][, name => $name] 91=item $fcp = new AnyEvent::FCP key => value...;
92 92
93Create a new FCP connection to the given host and port (default 93Create a new FCP connection to the given host and port (default
94127.0.0.1:9481, or the environment variables C<FREDHOST> and C<FREDPORT>). 94127.0.0.1:9481, or the environment variables C<FREDHOST> and C<FREDPORT>).
95 95
96If no C<name> was specified, then AnyEvent::FCP will generate a 96If no C<name> was specified, then AnyEvent::FCP will generate a
97(hopefully) unique client name for you. 97(hopefully) unique client name for you.
98
99The following keys can be specified (they are all optional):
100
101=over 4
102
103=item name => $string
104
105A unique name to identify this client. If none is specified, a randomly
106generated name will be used.
107
108=item host => $hostname
109
110The hostname or IP address of the freenet node. Default is C<$ENV{FREDHOST}>
111or C<127.0.0.1>.
112
113=item port => $portnumber
114
115The port number of the FCP port. Default is C<$ENV{FREDPORT}> or C<9481>.
116
117=item timeout => $seconds
118
119The timeout, in seconds, after which a connection error is assumed when
120there is no activity. Default is C<7200>, i.e. two hours.
121
122=item keepalive => $seconds
123
124The interval, in seconds, at which keepalive messages will be
125sent. Default is C<540>, i.e. nine minutes.
126
127These keepalive messages are useful both to detect that a connection is
128no longer working and to keep any (home) routers from expiring their
129masquerading entry.
130
131=item on_eof => $callback->($fcp)
132
133Invoked when the underlying L<AnyEvent::Handle> signals EOF, currently
134regardless of whether the EOF was expected or not.
135
136=item on_error => $callback->($fcp, $message)
137
138Invoked on any (fatal) errors, such as unexpected connection close. The
139callback receives the FCP object and a textual error message.
140
141=item on_failure => $callback->($fcp, $type, $backtrace, $args, $error)
142
143Invoked when an FCP request fails that didn't have a failure callback. See
144L<FCP REQUESTS> for details.
145
146=back
98 147
99=cut 148=cut
100 149
101sub new { 150sub new {
102 my $class = shift; 151 my $class = shift;
… …
190 239
191 $self->{hdl} = new AnyEvent::Handle 240 $self->{hdl} = new AnyEvent::Handle
192 connect => [$self->{host} => $self->{port}], 241 connect => [$self->{host} => $self->{port}],
193 timeout => $self->{timeout}, 242 timeout => $self->{timeout},
194 on_read => $on_read, 243 on_read => $on_read,
195 on_eof => $self->{on_eof}, 244 on_eof => sub {
245 if ($self->{on_eof}) {
246 $self->{on_eof}($self);
247 } else {
248 $self->fatal ("EOF");
249 }
250 },
196 on_error => sub { 251 on_error => sub {
197 $self->fatal ($_[2]); 252 $self->fatal ($_[2]);
198 }, 253 },
199 ; 254 ;
200 255
… …
214 269
215 $self->{hdl}->shutdown; 270 $self->{hdl}->shutdown;
216 delete $self->{kw}; 271 delete $self->{kw};
217 272
218 if ($self->{on_error}) { 273 if ($self->{on_error}) {
219 $self->{on_error}->($msg); 274 $self->{on_error}->($self, $msg);
220 } else { 275 } else {
221 die $msg; 276 die $msg;
222 } 277 }
223} 278}
224 279
… …
382=over 4 437=over 4
383 438
384=item A code reference (or rather anything not matching some other alternative) 439=item A code reference (or rather anything not matching some other alternative)
385 440
386This code reference will be invoked with the result on success. On an 441This code reference will be invoked with the result on success. On an
442error, it will invoke the C<on_failure> callback of the FCP object, or,
387error, it will die (in the event loop) with a backtrace of the call site. 443if none was defined, will die (in the event loop) with a backtrace of the
444call site.
388 445
389This is a popular choice, but it makes handling errors hard - make sure 446This is a popular choice, but it makes handling errors hard - make sure
390you never generate protocol errors! 447you never generate protocol errors!
448
449If an C<on_failure> hook exists, it will be invoked with the FCP object,
450the request type (the name of the method), a (textual) backtrace as
451generated by C<Carp::longmess>, and arrayref containing the arguments from
452the original request invocation and the error object from the server, in
453this order, e.g.:
454
455 on_failure => sub {
456 my ($fcp, $request_type, $backtrace, $orig_args, $error_object) = @_;
457
458 warn "FCP failure ($type), $error_object->{code_description} ($error_object->{extra_description})$backtrace";
459 exit 1;
460 },
391 461
392=item A condvar (as returned by e.g. C<< AnyEvent->condvar >>) 462=item A condvar (as returned by e.g. C<< AnyEvent->condvar >>)
393 463
394When a condvar is passed, it is sent (C<< $cv->send ($results) >>) the 464When a condvar is passed, it is sent (C<< $cv->send ($results) >>) the
395results when the request has finished. Should an error occur, the error 465results when the request has finished. Should an error occur, the error
… …
400=item An array with two callbacks C<[$success, $failure]> 470=item An array with two callbacks C<[$success, $failure]>
401 471
402The C<$success> callback will be invoked with the results, while the 472The C<$success> callback will be invoked with the results, while the
403C<$failure> callback will be invoked on any errors. 473C<$failure> callback will be invoked on any errors.
404 474
475The C<$failure> callback will be invoked with the error object from the
476server.
477
405=item C<undef> 478=item C<undef>
406 479
407This is the same thing as specifying C<sub { }> as callback, i.e. on 480This is the same thing as specifying C<sub { }> as callback, i.e. on
408success, the results are ignored, while on failure, you the module dies 481success, the results are ignored, while on failure, the C<on_failure> hook
409with a backtrace. 482is invoked or the module dies with a backtrace.
410 483
411This is good for quick scripts, or when you really aren't interested in 484This is good for quick scripts, or when you really aren't interested in
412the results. 485the results.
413 486
414=back 487=back
… …
434 if (ARRAY:: eq ref $ok) { 507 if (ARRAY:: eq ref $ok) {
435 ($ok, $err) = @$ok; 508 ($ok, $err) = @$ok;
436 } elsif (UNIVERSAL::isa $ok, AnyEvent::CondVar::) { 509 } elsif (UNIVERSAL::isa $ok, AnyEvent::CondVar::) {
437 $err = sub { $ok->croak ($_[0]{extra_description}) }; 510 $err = sub { $ok->croak ($_[0]{extra_description}) };
438 } else { 511 } else {
439 my $bt = Carp::longmess ""; 512 my $bt = Carp::longmess "AnyEvent::FCP request $name";
513 Scalar::Util::weaken (my $self = $_[0]);
514 my $args = [@_]; shift @$args;
440 $err = sub { 515 $err = sub {
516 if ($self->{on_failure}) {
517 $self->{on_failure}($self, $name, $args, $bt, $_[0]);
518 } else {
441 die "$_[0]{code_description} ($_[0]{extra_description})$bt"; 519 die "$_[0]{code_description} ($_[0]{extra_description})$bt";
520 }
442 }; 521 };
443 } 522 }
444 523
445 $ok ||= $NOP_CB; 524 $ok ||= $NOP_CB;
446 525

Diff Legend

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