Merge pull request #45 from andk/document_on_exception

Document on exception

lib/Gearman/Task.pm

@@ -64,6 +64,15 @@ process.
 
 =item
 
+on_exception
+
+A subroutine reference to be invoked when the task fails. The client
+needs to be configured to support exception handling by setting the
+attribute C<exceptions> to a true value. The subroutine will be passed
+the stringified value of the exception.
+
+=item
+
 on_fail
 
 A subroutine reference to be invoked when the task fails (or fails for

t/04-task.t

@@ -2,6 +2,7 @@ use strict;
 use warnings;
 
 use Storable;
+use String::CRC32 ();
 use Test::More;
 use Test::Exception;
 
@@ -132,11 +133,11 @@ subtest "hook", sub {
     plan tests => 4;
 
     my $cb = sub { 2 * shift };
-    ok($t->add_hook($f, $cb));
-    is($t->{hooks}->{$f}, $cb);
+    ok($t->add_hook($f, $cb), "add hook");
+    is($t->{hooks}->{$f}, $cb, "is hooks");
     $t->run_hook($f, 2);
-    ok($t->add_hook($f));
-    is($t->{hooks}->{$f}, undef);
+    ok($t->add_hook($f), "add hook");
+    is($t->{hooks}->{$f}, undef, "no hook");
 };
 
 subtest "taskset", sub {
@@ -148,20 +149,20 @@ subtest "taskset", sub {
 
     my $c = new_ok("Gearman::Client");
     my $ts = new_ok("Gearman::Taskset", [$c]);
-    ok($t->taskset($ts));
-    is($t->taskset(), $ts);
-    is($t->hash(),    $t->hash());
+    ok($t->taskset($ts), "taskset true");
+    is($t->taskset(), $ts, "is taskset");
+    is($t->hash(),  (String::CRC32::crc32($t->{uniq}) >> 16) & 0x7fff, "hash for uniq: $t->{uniq}");
 
     $t->{uniq} = '-';
     is($t->taskset(), $ts);
-    is($t->hash(),    $t->hash());
+    is($t->hash(),   (String::CRC32::crc32($arg) >> 16) & 0x7fff, "hash for uniq: -");
 };
 
 subtest "fail", sub {
     plan tests => 2 * scalar(@h) - 1;
 
     $t->{is_finished} = 1;
-    is($t->fail(), undef);
+    is($t->fail(), undef, "fail returns undef");
 
     $t->{is_finished}  = undef;
     $t->{on_retry}     = sub { is(shift, $t->{retry_count}, "on_retry") };
@@ -173,7 +174,7 @@ subtest "fail", sub {
     $t->{is_finished} = undef;
     $t->{on_fail} = sub { is(shift, $f, "on_fail") };
     $t->final_fail($f);
-    is($t->{is_finished}, $f);
+    is($t->{is_finished}, $f, "is_finished '$f'");
 
     is($t->{$_}, undef, $_) for @h;
 };
@@ -182,17 +183,17 @@ subtest "exception", sub {
     plan tests => 2;
 
     my $exc = Storable::freeze(\$f);
-    $t->{on_exception} = sub { is(shift, $f) };
-    is($t->exception(\$exc), undef);
+    $t->{on_exception} = sub { is(shift, $f, "within on_exception") };
+    is($t->exception(\$exc), undef, "exception returns undef");
 };
 
 subtest "complete", sub {
     plan tests => 2;
 
     $t->{is_finished} = undef;
-    $t->{on_complete} = sub { is(shift, $f) };
+    $t->{on_complete} = sub { is(shift, $f, "within on_complete") };
     $t->complete($f);
-    is($t->{is_finished}, "complete");
+    is($t->{is_finished}, "complete", "is complete");
 };
 
 subtest "status", sub {
@@ -203,30 +204,30 @@ subtest "status", sub {
         is(shift, $f,   "func");
         is(shift, $arg, "arg");
     };
-    ok $t->status($f, $arg), "status";
+    ok $t->status($f, $arg), "status true";
 };
 
 subtest "data", sub {
     plan tests => 2;
 
     $t->{is_finished} = undef;
     $t->{on_data} = sub { is(shift, $f, "func") };
-    ok $t->data($f), "data";
+    ok $t->data($f), "data true";
 };
 
 subtest "warning", sub {
     plan tests => 2;
 
     $t->{is_finished} = undef;
     $t->{on_warning} = sub { is(shift, $f, "func") };
-    ok $t->warning($f), "warning";
+    ok $t->warning($f), "warning true";
 };
 
 subtest "handle", sub {
     plan tests => 2;
 
-    ok($t->handle($f));
-    is($t->{handle}, $f);
+    ok($t->handle($f), "handle true");
+    is($t->{handle}, $f, "is handle '$f'");
 };
 
 subtest "pack_submit_packet", sub {
@@ -235,15 +236,15 @@ subtest "pack_submit_packet", sub {
     my $v = Gearman::Util::pack_req_command($t->mode,
         join("\0", $t->func, $t->{uniq}, ${ $t->{argref} }));
 
-    is $t->pack_submit_packet($c), $v;
-    is $t->pack_submit_packet(), $v;
+    is $t->pack_submit_packet($c), $v, "is pack_submit_packet(\$c) \$v";
+    is $t->pack_submit_packet(), $v, "is pack_submit_packet() \$v";
 
     $v = Gearman::Util::pack_req_command($t->mode,
         join("\0", $t->func, '', ''));
     ${ $t->{argref} } = undef;
     $t->{uniq} = undef;
-    is $t->pack_submit_packet($c), $v;
-    is $t->pack_submit_packet(), $v;
+    is $t->pack_submit_packet($c), $v, "is pack_submit_packet(\$c) \$v";
+    is $t->pack_submit_packet(), $v, "is pack_submit_packet() \$v";
 };
 
 done_testing();

t/13-fail.t

@@ -25,7 +25,7 @@ my $client = new_ok(
 
 ## Test some failure conditions:
 ## Normal failure (worker returns undef or dies within eval).
-subtest "wokrker process fails", sub {
+subtest "worker process fails", sub {
     plan tests => 7;
     my $func    = "fail";
     my @workers = map(new_worker(
@@ -77,7 +77,8 @@ subtest "wokrker process fails", sub {
 };
 
 subtest "worker process dies", sub {
-    plan skip_all => "subtest fails with gearman v1.1.12";
+    $ENV{GEARMAN_SUPPORTS_EXCEPTIONS} or
+        plan skip_all => "subtest fails with gearman v1.1.12 (set GEARMAN_SUPPORTS_EXCEPTIONS=1 to run this test)";
 
     my $func   = "fail_die";
     my $worker = new_worker(
@@ -101,7 +102,7 @@ subtest "worker process dies", sub {
     like(
         $msg,
         qr/test reason/,
-        "the die message is available in the on_fail sub"
+        "the die message is available in the on_exception sub"
     );
 
 };

t/18-ssl.t

@@ -193,8 +193,8 @@ sub _echo {
     my $len = length($req);
     ok(my $rv = $sock->write($req, $len), "write to socket");
     my $err;
-    ok(my $res = Gearman::Util::read_res_packet($sock, \$err), "read respose");
-    is(ref($res),            "HASH",     "respose is a hash");
+    ok(my $res = Gearman::Util::read_res_packet($sock, \$err), "read response");
+    is(ref($res),            "HASH",     "response is a hash");
     is($res->{type},         "echo_res", "response type");
     is(${ $res->{blobref} }, $msg,       "response blobref");
 } ## end sub _echo