blib/lib/Dancer/Plugin/GearmanXS.pm

filter: Statementstmt 89.4% 17 / 19 Branchbran n/a Conditioncond n/a MC/DCmcdc n/a Subroutinesub 100% 7 / 7 Podpod n/a totaltotal 92.3% 24 / 26 CC 1 SCAR 0.4
CC
1
Cov
89%
BEGIN
1.3
BEGIN
1.0
BEGIN
1.0
CRAP 1.0
↑ Summary
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;
↑ Summary