File Coverage

lib/MediaCloud/JobManager/Broker.pm
Criterion Covered Total %
statement 15 15 100.0
branch n/a
condition n/a
subroutine 5 5 100.0
pod n/a
total 20 20 100.0


line stmt bran cond sub pod time code
1             package MediaCloud::JobManager::Broker;
2              
3             #
4             # Abstract job broker
5             #
6              
7 1     1   9 use strict;
  1         3  
  1         46  
8 1     1   9 use warnings;
  1         2  
  1         64  
9 1     1   9 use Modern::Perl "2012";
  1         2  
  1         11  
10              
11 1     1   213 use Moose::Role;
  1         2  
  1         12  
12              
13             =head2 C<$self-E<gt>start_worker($function_name)>
14            
15             Start a worker.
16            
17             Should call C<$function_name-E<gt>run_locally( $args, $job )> to do the actual
18             work. C<$job> is job handle or identifier used by helpers (e.g.
19             C<set_job_progress()>).
20            
21             Parameters:
22            
23             =over 4
24            
25             =item * Function name (e.g. "NinetyNineBottlesOfBeer")
26            
27             =back
28            
29             =cut
30              
31             requires 'start_worker';
32              
33             =head2 C<$self-E<gt>run_job_sync($function_name, $args, $priority)>
34            
35             Run a job synchronously (wait for the job to complete and return the result).
36            
37             Parameters:
38            
39             =over 4
40            
41             =item * Function name (e.g. "NinetyNineBottlesOfBeer")
42            
43             =item * Hashref with arguments or undef
44            
45             =back
46            
47             Returns job result (whatever the job subroutine returned).
48            
49             =cut
50              
51             requires 'run_job_sync';
52              
53             =head2 C<$self-E<gt>run_job_async($function_name, $args, $priority)>
54            
55             Run a job asynchronously (add job to the job queue and return instantly).
56            
57             Parameters:
58            
59             =over 4
60            
61             =item * Function name (e.g. "NinetyNineBottlesOfBeer")
62            
63             =item * Hashref with arguments or undef
64            
65             =back
66            
67             Returns string job ID that can be used to track the job.
68            
69             =cut
70              
71             requires 'run_job_async';
72              
73             =head2 C<$self-E<gt>job_id_from_handle($job)>
74            
75             Return string job identifier for handle.
76            
77             Parameters:
78            
79             =over 4
80            
81             =item * Job handle or identifier
82            
83             =back
84            
85             =cut
86              
87             requires 'job_id_from_handle';
88              
89             =head2 C<$self-E<gt>set_job_progress($job, $numerator, $denominator)>
90            
91             Provide progress report while running the task (from C<run()>).
92            
93             Examples:
94            
95             =over 4
96            
97             =item * C<$self-E<gt>set_progress(3, 10)>
98            
99             3 out of 10 subtasks are complete.
100            
101             =item * C<$self-E<gt>set_progress(45, 100)>
102            
103             45 out of 100 subtasks are complete (or 45% complete).
104            
105             =back
106            
107             Parameters:
108            
109             =over 4
110            
111             =item * Job handle or identifier
112            
113             =item * Numerator
114            
115             =item * Denominator
116            
117             =back
118            
119             =cut
120              
121             requires 'set_job_progress';
122              
123             =head2 C<$self-E<gt>job_status($function_name, $job_id)>
124            
125             Get job status.
126            
127             Parameters:
128            
129             =over 4
130            
131             =item * Class instance ("self")
132            
133             =item * Function name (e.g. "NinetyNineBottlesOfBeer")
134            
135             =item * Job ID (e.g. "H:localhost.localdomain:8")
136            
137             =back
138            
139             Returns array with job status:
140            
141             =begin text
142            
143             { # Job ID that was passed as a parameter 'job_id' =>
144             'H:tundra.home:8',
145            
146             # Whether or not the job is currently running
147             'running' => 1,
148            
149             # Numerator and denominator of the job's progress
150             # (in this example, job is 1333/2000 complete)
151             'numerator' => 1333,
152             'denominator' => 2000
153             };
154            
155             =end text
156            
157             Returns undef if the job ID was not found; dies on error.
158            
159             =cut
160              
161             requires 'job_status';
162              
163             =head2 C<$self-E<gt>show_jobs()>
164            
165             Show all jobs on all the configured servers.
166            
167             Returns a hashref of servers and their jobs, e.g.:
168            
169             =begin text
170            
171             {
172             'localhost:4730' => {
173             # Job ID
174             'H:tundra.home:8' => {
175            
176             # Whether or not the job is currently running
177             'running' => 1,
178            
179             # Numerator and denominator of the job's progress
180             # (in this example, job is 1333/2000 complete)
181             'numerator' => 1333, # 0 if the job haven't been started yet
182             'denominator' => 2000 # 1 if the job haven't been started yet;
183             # 0 if the job has been cancelled
184            
185             },
186            
187             # ...
188            
189             },
190            
191             # ...
192             }
193            
194             =end text
195            
196             Returns C<undef> on error.
197            
198             =cut
199              
200             requires 'show_jobs';
201              
202             =head2 C<$self-E<gt>cancel_job($job_id)>
203            
204             Remove a given job from all the configured servers' queues.
205            
206             Parameters:
207            
208             =over 4
209            
210             =item * job ID (e.g. "H:localhost.localdomain:8")
211            
212             =back
213            
214             Returns true (1) if the job has been cancelled, false (C<undef>) on error.
215            
216             =cut
217              
218             requires 'cancel_job';
219              
220             =head2 C<$self-E<gt>server_status()>
221            
222             Get status from all the configured servers.
223            
224             Returns a hashref of servers and their statuses, e.g.:
225            
226             =begin text
227            
228             {
229             'localhost:4730' => {
230             # Function name
231             'NinetyNineBottlesOfBeer' => {
232            
233             # Number of queued (waiting to be run) jobs
234             'total' => 4,
235            
236             # Number of currently running jobs
237             'running' => 1,
238            
239             # Number of currently registered workers
240             'available_workers' => 1
241            
242             },
243            
244             # ...
245             },
246            
247             # ...
248            
249             };
250            
251             =end text
252            
253             Returns C<undef> on error.
254            
255             =cut
256              
257             requires 'server_status';
258              
259             =head2 C<$self-E<gt>workers()>
260            
261             Get a list of workers from all the configured servers.
262            
263             Returns a hashref of servers and their workers, e.g.:
264            
265             =begin text
266            
267             {
268             'localhost:4730' => [
269             {
270             # Unique integer file descriptor of the worker
271             'file_descriptor' => 23,
272            
273             # IP address of the worker
274             'ip_address' => '127.0.0.1',
275            
276             # Client ID of the worker (might be undefined if the ID is '-')
277             'client_id' => undef,
278            
279             # List of functions the worker covers
280             'functions' => [
281             'NinetyNineBottlesOfBeer',
282             'Addition'
283             ]
284             },
285             # ...
286             ],
287            
288             # ...
289            
290             };
291            
292             =end text
293            
294             Returns C<undef> on error.
295            
296             =cut
297              
298             requires 'workers';
299              
300 1     1   9339 no Moose; # gets rid of scaffolding
  1         4  
  1         10  
301              
302             1;
303