| 1 | 2 | ▶ | use strict; |
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||
| 2 | 2 | ▶ | use warnings; |
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||
| 3 | |||
| 4 | package Dancer::Plugin::GearmanXS; | ||
| 5 | 2 | ▶ | BEGIN { |
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||
| 6 | 2 | $Dancer::Plugin::GearmanXS::VERSION = '0.110570'; | |
| 7 | } | ||
| 8 | |||
| 9 | 2 | ▶ | use Dancer ':syntax'; |
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||
| 10 | 2 | ▶ | use Dancer::Plugin; |
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||
| 11 | |||
| 12 | 2 | ▶ | use Storable qw( nfreeze ); |
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||
| 13 | |||
| 14 | 0 | ▶ | use Gearman::XS qw/:constants/; |
|
Subroutine
BEGIN: called CC=1 SCAR=2.6
| |||
| 15 | use Gearman::XS::Client; | ||
| 16 | |||
| 17 | my $gearman_client = Gearman::XS::Client->new(); | ||
| 18 | $gearman_client->add_servers( | ||
| 19 | join( ',', @{ plugin_setting->{job_servers} || ['127.0.0.1:4730'] } ) ); | ||
| 20 | |||
| 21 | my $gearman_serializer = sub { nfreeze(@_) }; | ||
| 22 | |||
| 23 | =head1 NAME | ||
| 24 | |||
| 25 | Dancer::Plugin::GearmanXS - a Dancer Gearman::XS client | ||
| 26 | |||
| 27 | =head1 SYNOPSIS | ||
| 28 | |||
| 29 | This plugin allows Dancer to communicate with Gearman servers, | ||
| 30 | requesting they perform a task and return the result. | ||
| 31 | |||
| 32 | By default, task parameters are serialised using Storable's C<nfreeze> method. | ||
| 33 | Your Gearman workers will need to agree on the method used to serialize data. | ||
| 34 | |||
| 35 | You will need to configure a list of Gearman servers the plugin will be | ||
| 36 | contacting. In your configuration file: | ||
| 37 | |||
| 38 | plugins: | ||
| 39 | GearmanXS: | ||
| 40 | job_servers: | ||
| 41 | - 127.0.0.1 | ||
| 42 | - 192.168.1.100:12345 | ||
| 43 | |||
| 44 | The job servers list defaults to C<127.0.0.1:4730> if not specified. | ||
| 45 | |||
| 46 | In your package/app: | ||
| 47 | |||
| 48 | package MyApp; | ||
| 49 | use Dancer; | ||
| 50 | use Dancer::Plugin::GearmanXS; | ||
| 51 | use YAML; | ||
| 52 | |||
| 53 | # use YAML as serializer rather than Storable | ||
| 54 | gearman_serializer => sub { | ||
| 55 | Dump(@_); | ||
| 56 | }; | ||
| 57 | |||
| 58 | get '/' => sub { | ||
| 59 | |||
| 60 | ## using the underlying Gearman::XS interface | ||
| 61 | my ($retval,$result) = | ||
| 62 | gearman->do( | ||
| 63 | 'task_name', | ||
| 64 | { arg1 => 'val1' }, | ||
| 65 | ); | ||
| 66 | ); | ||
| 67 | # check $retval and use gearman_client->error() | ||
| 68 | |||
| 69 | ## using the simplified interface which serializes for you | ||
| 70 | my $res = gearman_do( 'task_name', { arg1 => 'val1' } ); | ||
| 71 | |||
| 72 | template index => { result => $result } | ||
| 73 | }; | ||
| 74 | |||
| 75 | Error management can be done via either C<gearman-E<gt>error> | ||
| 76 | or C<gearman_error>. | ||
| 77 | |||
| 78 | If you need access to advanced features like C<add_task_high_background> or | ||
| 79 | C<set_fail_fn>, use the L<gearman> function: it's a L<Gearman::XS::Client> | ||
| 80 | object. | ||
| 81 | |||
| 82 | =head1 KEYWORDS | ||
| 83 | |||
| 84 | =head2 gearman | ||
| 85 | |||
| 86 | This method gives you direct access to the L<Gearman::XS::Client> instance. | ||
| 87 | See the module's POD for what you could do with it. | ||
| 88 | The other methods are shorthand for more common tasks, but do not provide | ||
| 89 | the same degree of control as accessing the client object directly. | ||
| 90 | |||
| 91 | =cut | ||
| 92 | |||
| 93 | register gearman => sub { $gearman_client }; | ||
| 94 | |||
| 95 | =head2 gearman_error | ||
| 96 | |||
| 97 | Accesses the C<error> method for the L<Gearman::XS::Client>. | ||
| 98 | |||
| 99 | =cut | ||
| 100 | |||
| 101 | register gearman_error => sub { $gearman_client->error }; | ||
| 102 | |||
| 103 | =head2 gearman_serializer | ||
| 104 | |||
| 105 | This method returns the current serializer subroutine reference. You can pass | ||
| 106 | it a subroutine reference if you would like to use a serializer other than | ||
| 107 | L<Storable>'s C<nfreeze>. | ||
| 108 | |||
| 109 | =cut | ||
| 110 | |||
| 111 | register gearman_serializer => sub { | ||
| 112 | return $gearman_serializer unless $_[0] and ref $_[0] eq 'CODE'; | ||
| 113 | $gearman_serializer = $_[0]; | ||
| 114 | }; | ||
| 115 | |||
| 116 | =head2 gearman_do | ||
| 117 | |||
| 118 | Creates, dispatches and waits on a task to complete, | ||
| 119 | returning the result (scalar reference on success, | ||
| 120 | or undef on failure). Uses the L<gearman_serializer> | ||
| 121 | to serialize the argument(s) given. | ||
| 122 | Use L<gearman_error> in case the of failure. | ||
| 123 | |||
| 124 | my $result = gearman_do('add', [1,2]); | ||
| 125 | return template error => { error => gearman_error } unless $result; | ||
| 126 | |||
| 127 | =cut | ||
| 128 | |||
| 129 | register gearman_do => sub { | ||
| 130 | my ( $task_name, @args ) = @_; | ||
| 131 | my $serialized_args = $gearman_serializer->(@args); | ||
| 132 | my ( $ret, $result ) = $gearman_client->do( $task_name, $serialized_args ); | ||
| 133 | return if $ret ne GEARMAN_SUCCESS; | ||
| 134 | return $result; | ||
| 135 | }; | ||
| 136 | |||
| 137 | =head2 gearman_background | ||
| 138 | |||
| 139 | Creates and dispatches a job to be run in the background, | ||
| 140 | not waiting for any result. Returns undef on failure, | ||
| 141 | or the job handle. | ||
| 142 | |||
| 143 | my $task = gearman_background('update_minicpan', | ||
| 144 | ['/opt/minicpan','0755'] | ||
| 145 | ); | ||
| 146 | return template error => { error => gearman_error } unless $task; | ||
| 147 | |||
| 148 | =cut | ||
| 149 | |||
| 150 | register gearman_background => sub { | ||
| 151 | my ( $task_name, @args ) = @_; | ||
| 152 | my $serialized_args = $gearman_serializer->(@args); | ||
| 153 | my ( $ret, $job_handle ) = $gearman_client->do_background( $task_name, $serialized_args ); | ||
| 154 | return if $ret ne GEARMAN_SUCCESS; | ||
| 155 | return $job_handle; | ||
| 156 | }; | ||
| 157 | |||
| 158 | =head2 gearman_add_task | ||
| 159 | |||
| 160 | Adds a task to be run in parallel, returning a task object. It does not | ||
| 161 | start executing the task: you will need to call L<gearman_run_tasks> | ||
| 162 | in order to do that. Returns undef on failure, or the task object. | ||
| 163 | |||
| 164 | # fetches these sites are up, in parallel | ||
| 165 | for my $site ( 'http://google.com', 'http://yahoo.com' ) { | ||
| 166 | my $task = gearman_add_task('fetch_site', $site); | ||
| 167 | return template error => { error => gearman_error } unless $task; | ||
| 168 | } | ||
| 169 | my $ret = gearman_run_tasks; | ||
| 170 | return template error => { error => gearman_error } unless $ret; | ||
| 171 | ## Tasks have completed | ||
| 172 | |||
| 173 | =cut | ||
| 174 | |||
| 175 | register gearman_add_task => sub { | ||
| 176 | my ( $task_name, @args ) = @_; | ||
| 177 | my $serialized_args = $gearman_serializer->(@args); | ||
| 178 | my ( $ret, $job_handle ) = $gearman_client->add_task( $task_name, $serialized_args ); | ||
| 179 | return if $ret ne GEARMAN_SUCCESS; | ||
| 180 | return $job_handle; | ||
| 181 | }; | ||
| 182 | |||
| 183 | =head2 gearman_run_tasks | ||
| 184 | |||
| 185 | Once a number of tasks have been queued via L<gearman_add_tasks>, this method | ||
| 186 | allows them to run in parallel, and returns whether there has been a failure. | ||
| 187 | See L<gearman_add_task> for an example. | ||
| 188 | |||
| 189 | =cut | ||
| 190 | |||
| 191 | register gearman_run_tasks => sub { | ||
| 192 | my ($ret) = $gearman_client->run_tasks(); | ||
| 193 | return ( $ret eq GEARMAN_SUCCESS ); | ||
| 194 | }; | ||
| 195 | |||
| 196 | register_plugin; | ||
| 197 | |||
| 198 | =head1 AUTHOR | ||
| 199 | |||
| 200 | Marco Fontani - C<< <MFONTANI at cpan.org> >> | ||
| 201 | |||
| 202 | =head1 BUGS | ||
| 203 | |||
| 204 | Please report any bugs via e-mail. | ||
| 205 | |||
| 206 | =head1 SEE ALSO | ||
| 207 | |||
| 208 | Dancer - L<Dancer> | ||
| 209 | |||
| 210 | Gearman::XS - L<Gearman::XS> | ||
| 211 | |||
| 212 | Gearman site - L<http://www.gearman.org> | ||
| 213 | |||
| 214 | Yosemite National Park: it's worth visiting. | ||
| 215 | |||
| 216 | =head1 LICENSE AND COPYRIGHT | ||
| 217 | |||
| 218 | Copyright 2011 Marco Fontani. | ||
| 219 | |||
| 220 | This program is free software; you can redistribute it and/or modify it | ||
| 221 | under the terms of either: the GNU General Public License as published | ||
| 222 | by the Free Software Foundation; or the Artistic License. | ||
| 223 | |||
| 224 | See http://dev.perl.org/licenses/ for more information. | ||
| 225 | |||
| 226 | =cut | ||
| 227 | |||
| 228 | 1; | ||