9 Meadow is an
abstract interface to the queue manager.
11 A Meadow knows how to check&change the actual status of Workers on the farm.
15 Copyright [1999-2015] Wellcome Trust Sanger Institute and the EMBL-European Bioinformatics Institute
16 Copyright [2016-2024] EMBL-European Bioinformatics Institute
18 Licensed under the Apache License,
Version 2.0 (the
"License"); you may not use
this file except in compliance with the License.
19 You may obtain a copy of the License at
23 Unless required by applicable law or agreed to in writing, software distributed under the License
24 is distributed on an
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
25 See the License
for the specific language governing permissions and limitations under the License.
29 Please subscribe to the
Hive mailing list: http:
34 package Bio::EnsEMBL::Hive::Meadow;
38 use Sys::Hostname (
'hostname');
40 use base (
'Bio::EnsEMBL::Hive::Configurable');
43 # -------------------------------------- <versioning of the Meadow interface> -------------------------------------------------------
45 our $MEADOW_MAJOR_VERSION =
'5'; # Make sure you change
this number whenever an incompatible change is introduced
48 sub get_meadow_major_version {
50 return $MEADOW_MAJOR_VERSION; # fetch the declared $MEADOW_MAJOR_VERSION of the interface
54 sub get_meadow_version {
61 sub check_version_compatibility {
64 my $mmv = $self->get_meadow_major_version();
65 my $mv = $self->get_meadow_version();
66 # warn "$self : MVC='$mmv', MV='$mv'\n";
68 return ($mv=~/^$mmv\./) ? 1 : 0;
71 # -------------------------------------- </versioning of the Meadow interface> ------------------------------------------------------
76 Title :
new (constructor)
77 Function: Instantiates a
new Meadow object
82 my ($class, $config, $name) = @_;
84 my $self = bless {}, $class;
86 $self->{
'_name'} = $name; # Record the name given to avoid querying the meadow once more
94 my ($self, $config) = @_;
96 $self->config( $config );
97 $self->context( [
'Meadow', $self->type, $self->cached_name ] );
104 Function: Wrapper around L<name()> that caches its
return value.
105 This is because (1) it can be expensive to get the name
106 (e.g. calling an external command), and (2) the name of a
107 Meadow is not expected to change through the life of the
117 unless( ref($self) and $name = $self->{
'_name'} ) { # unless the name was storable AND stored in the
object
119 if($name = $self->name() and ref($self) ) { # ... get the not-yet-stored name and
if it is storable
120 $self->{
'_name'} = $name; # ... ... then store it in the
object
131 Function: The
"type" of a Meadow is basically its job management
132 system. eHive comes with two Meadows: Platform LSF (type
133 "LSF"), and a
default fork()-based (type
"LOCAL"). Other
134 meadows can be implemented provided that they follow the
140 my $class = shift @_;
142 $class = ref($class)
if(ref($class));
144 return (reverse split(/::/, $class ))[0];
148 =head2 get_current_hostname
150 Title : get_current_hostname
151 Function: Returns the
"current" hostname (most UNIX-based Meadows will simply use
this base method)
155 sub get_current_hostname {
163 Function: The
"signature" of a Meadow is its unique identifier across
171 return $self->type.
'/'.$self->cached_name;
177 Title : pipeline_name
178 Function: Getter/setter
for the name of the current pipeline.
179 This method is used by other Meadow methods such as
180 L<job_name_prefix()>.
187 if(@_) { #
new value is being set (which can be undef)
188 $self->{
'_pipeline_name'} = shift @_;
190 return $self->{
'_pipeline_name'};
194 =head2 runWorker_path
196 Title : runWorker_path
197 Function: Getter
for the path to runWorker.pl
198 This is now set in the JSON config file. When missing or set to
null,
199 defaults to $EHIVE_ROOT_DIR/scripts
206 my $path = $self->config_get(
'RunWorkerPath')
207 if ( length($path) ) {
208 $path = $path .
'/' unless $path =~ /\/$/; # add
"/" as suffix
if user forgot
214 =head2 job_name_prefix
216 Title : job_name_prefix
217 Function: Tells how the agents (workers) should be generally named. It
218 is used to name
new agents, and to find our own agents.
222 sub job_name_prefix {
225 return ($self->pipeline_name() ? $self->pipeline_name().
'-' :
'') .
'Hive-';
229 =head2 job_array_common_name
231 Title : job_array_common_name
232 Function: More specific version of L<job_name_prefix()> that returns
233 the actual name that agents should have at a specific
238 sub job_array_common_name {
239 my ($self, $rc_name, $iteration) = @_;
241 return $self->job_name_prefix() .
"${rc_name}-${iteration}";
246 ## The methods below must be reimplemented in a sub-class. See Meadow/LOCAL and Meadow/LSF
252 Function: Returns the name of the Meadow (which excludes the Meadow type)
259 die
"Please use a derived method";
263 =head2 get_current_worker_process_id
265 Title : get_current_worker_process_id
266 Function: Called by a worker to find its process_id. At any point in
267 time, the triple (meadow_type, meadow_name, process_id)
272 sub get_current_worker_process_id {
275 die
"Please use a derived method";
279 =head2 status_of_all_our_workers
281 Title : status_of_all_our_workers
282 Function: Returns an arrayref of arrayrefs [worker_pid, meadow_user, status, rc_name]
283 listing the workers that
this Meadow can see.
284 Allowed statuses are
"RUN",
"PEND",
"SSUSP",
"UNKWN"
288 sub status_of_all_our_workers { # returns an arrayref
289 my ($self, $meadow_users_of_interest) = @_;
291 die
"Please use a derived method";
295 =head2 check_worker_is_alive_and_mine
297 Title : check_worker_is_alive_and_mine
298 Function: Tells whether the given worker lives in the current Meadow
299 and belongs to the current user.
303 sub check_worker_is_alive_and_mine {
304 my ($self, $worker) = @_;
306 die
"Please use a derived method";
313 Function: Kill a worker.
318 my ($self, $worker, $fast) = @_;
320 die
"Please use a derived method";
324 =head2 parse_report_source_line
326 Title : parse_report_source_line
327 Function: Opens and parses a file / command-line to
return the
328 resource-
usage of some workers. Should
return a hashref
329 where process_id is the key to a hashref composed of:
342 sub parse_report_source_line {
343 my ($self, $bacct_source_line) = @_;
345 warn
"\t".ref($self).
" does not support resource usage logs\n";
351 =head2 get_report_entries_for_process_ids
353 Title : get_report_entries_for_process_ids
354 Function: A higher-level method that gets process_ids as input and
355 returns a structure like parse_report_source_line.
359 sub get_report_entries_for_process_ids {
360 my ($self, @process_ids) = @_;
362 warn
"\t".ref($self).
" does not support resource usage logs\n";
367 =head2 get_report_entries_for_time_interval
369 Title : get_report_entries_for_time_interval
370 Function: A higher-level method that gets a time interval as input and
371 returns a structure like parse_report_source_line.
376 sub get_report_entries_for_time_interval {
377 my ($self, $from_time, $to_time, $username) = @_;
379 warn
"\t".ref($self).
" does not support resource usage logs\n";
385 =head2 submit_workers_return_meadow_pids
387 Title : submit_workers_return_meadow_pids
388 Function: Submit $required_worker_count workers with the command $worker_cmd and
return the meadow-specific worker_pids
392 sub submit_workers_return_meadow_pids {
393 my ($self, $worker_cmd, $required_worker_count, $iteration, $rc_name, $rc_specific_submission_cmd_args, $submit_log_subdir) = @_;
395 die
"Please use a derived method";
402 Function: Runs an arbitrary commands on the given host. The host is expected to belong to the meadow and be reachable
407 my ($self, $meadow_host, $meadow_user, $command) = @_;
408 # By default we trust the network, but this can be switched off in the config file
409 my @extra_args = $self->config_get(
'StrictHostKeyChecking') ? () : qw(-o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/
null);
410 # Several hard-coded parameters here:
411 # - BatchMode=yes disables human interaction (no password asked)
412 # - ServerAliveInterval=30 tells ssh that the server must answer within 30 seconds
413 # - timeout 3m means that the whole command must complete within 3 minutes
414 return system(
'timeout',
'3m',
'ssh', @extra_args,
'-o',
'BatchMode=yes',
'-o',
'ServerAliveInterval=30', sprintf(
'%s@%s', $meadow_user, $meadow_host), @$command);
418 =head2 cleanup_temp_directory
420 Title : cleanup_temp_directory
421 Function: Cleanup the temp directory assigned to the worker
425 sub cleanup_temp_directory {
426 my ($self, $worker) = @_;
428 # The feature can be disabled for this actual meadow
429 return unless $self->config_get(
'CleanupTempDirectoryKilledWorkers');
431 print
"GarbageCollector:\tCleaning-up ".$worker->temp_directory_name.
"\n";
432 my $rc = $self->run_on_host($worker->meadow_host, $worker->meadow_user, [
'rm',
'-rf', $worker->temp_directory_name]);
433 $worker->worker_say(sprintf(
"Error: could not clean %s's temp directory '%s': %s\n", $worker->meadow_host, $worker->temp_directory_name, $@))
if $rc;