Inheritance diagram for Bio::EnsEMBL::Hive::Worker:

Collaboration diagram for Bio::EnsEMBL::Hive::Worker:

Public Member Functions
public	init ()

public	meadow_type ()

public	meadow_name ()

public	host ()

public	process_id ()

public	work_done ()

public	status ()

public	born ()

public	last_check_in ()

public	died ()

public	cause_of_death ()

public String	log_dir ()

public	current_role ()

public	debug ()

public	execute_writes ()

public	special_batch ()

public	perform_cleanup ()

public	retry_throwing_jobs ()

public	can_respecialize ()

public Int	life_span ()

public	lifespan_stopwatch ()

public	life_span_limit_reached ()

public Hive::Limiter	job_limiter ()

public	more_work_done ()

public	prev_job_error ()

public	runnable_object ()

public	get_stdout_redirector ()

public	get_stderr_redirector ()

public	worker_say ()

public	toString ()

public void	run ()

public	specialize_and_compile_wrapper ()

public	run_one_batch ()

public	set_and_update_status ()

public	enter_status ()

public	start_job_output_redirection ()

public	stop_job_output_redirection ()

Public Member Functions inherited from Bio::EnsEMBL::Hive::Storable
public Bio::EnsEMBL::Hive::Storable	new ()

public Int	dbID ()

public Bio::EnsEMBL::Hive::DBSQL::BaseAdaptor	adaptor ()

public	DESTROY ()

public	AUTOLOAD ()

Detailed Description

Description

    Object which encapsulates the details of how to find jobs, how to run those
    jobs, and then check the rules to create the next jobs in the chain.
    Essentially knows where to find data, how to process data, and where to
    put it when it is done (put in next persons INBOX) so the next Worker
    in the chain can find data to work on.

    Hive based processing is a concept based on a more controlled version
    of an autonomous agent type system.  Each worker is not told what to do
    (like a centralized control system - like the current pipeline system)
    but rather queries a central database for jobs (give me jobs).

    Each worker is linked to an analysis_id, registers its self on creation
    into the Hive, creates a RunnableDB instance of the Analysis->module,
    gets relevant configuration information from the database, does its
    work, creates the next layer of job entries by interfacing to
    the DataflowRuleAdaptor to determine the analyses it needs to pass its
    output data to and creates jobs on the database of the next analysis.
    It repeats this cycle until it has lived its lifetime or until there are no
    more jobs left to process.
    The lifetime limit is a safety limit to prevent these from 'infecting'
    a system and sitting on a compute node for longer than is socially exceptable.
    This is primarily needed on compute resources like an LSF system where jobs
    are not preempted and run until they are done.

    The Queens primary job is to create Workers to get the work down.
    As part of this, she is also responsible for summarizing the status of the
    analyses by querying the jobs, summarizing, and updating the
    analysis_stats table.  From this she is also responsible for monitoring and
    'unblocking' analyses via the analysis_ctrl_rules.
    The Queen is also responsible for freeing up jobs that were claimed by Workers
    that died unexpectantly so that other workers can take over the work.  

    The Beekeeper is in charge of interfacing between the Queen and a compute resource
    or 'compute farm'.  Its job is to query Queens if they need any workers and to
    send the requested number of workers to open machines via the runWorker.pl script.
    It is also responsible for interfacing with the Queen to identify workers which died
    unexpectantly so that she can free the dead workers unfinished jobs.

Member Function Documentation

◆ born()

public Bio::EnsEMBL::Hive::Worker::born ( )

Undocumented method

Code:

click to view

◆ can_respecialize()

public Bio::EnsEMBL::Hive::Worker::can_respecialize ( )

Undocumented method

Code:

click to view

◆ cause_of_death()

public Bio::EnsEMBL::Hive::Worker::cause_of_death ( )

Undocumented method

Code:

click to view

◆ current_role()

public Bio::EnsEMBL::Hive::Worker::current_role ( )

Undocumented method

Code:

click to view

◆ debug()

public Bio::EnsEMBL::Hive::Worker::debug ( )

Undocumented method

Code:

click to view

◆ died()

public Bio::EnsEMBL::Hive::Worker::died ( )

Undocumented method

Code:

click to view

◆ enter_status()

public Bio::EnsEMBL::Hive::Worker::enter_status ( )

Undocumented method

Code:

click to view

◆ execute_writes()

public Bio::EnsEMBL::Hive::Worker::execute_writes ( )

Undocumented method

Code:

click to view

◆ get_stderr_redirector()

public Bio::EnsEMBL::Hive::Worker::get_stderr_redirector ( )

Undocumented method

Code:

click to view

◆ get_stdout_redirector()

public Bio::EnsEMBL::Hive::Worker::get_stdout_redirector ( )

Undocumented method

Code:

click to view

◆ host()

public Bio::EnsEMBL::Hive::Worker::host ( )

Undocumented method

Code:

click to view

◆ init()

public Bio::EnsEMBL::Hive::Worker::init ( )

Undocumented method

Code:

click to view

◆ job_limiter()

public Hive::Limiter Bio::EnsEMBL::Hive::Worker::job_limiter ( )

  Title   :   job_limiter
  Arg [1] :   (optional) integer $value
  Usage   :   $limiter_obj = $self->job_limiter;
              $self->job_limiter($new_value);
  Description: The maximum number of jobs to be done by the Worker can be limited by the given number.
               A worker 'dies' when either the 'life_span' or 'job_limit' is exceeded.
  DefaultValue : undef (relies on life_span to limit life of worker)
  Returntype : Hive::Limiter object

Code:

click to view

◆ last_check_in()

public Bio::EnsEMBL::Hive::Worker::last_check_in ( )

Undocumented method

Code:

click to view

◆ life_span()

public Int Bio::EnsEMBL::Hive::Worker::life_span ( )

  Arg [1] : (optional) integer $value (in seconds)
  Title   :   life_span
  Usage   :   $value = $self->life_span;
              $self->life_span($new_value);
  Description: Defines the maximum time a worker can live for. Workers are always
               allowed to complete the jobs they get, but whether they can
               do multiple rounds of work is limited by their life_span
  DefaultValue : 3600 (60 minutes)
  Returntype : integer scalar

Code:

click to view

◆ life_span_limit_reached()

public Bio::EnsEMBL::Hive::Worker::life_span_limit_reached ( )

Undocumented method

Code:

click to view

◆ lifespan_stopwatch()

public Bio::EnsEMBL::Hive::Worker::lifespan_stopwatch ( )

Undocumented method

Code:

click to view

◆ log_dir()

public String Bio::EnsEMBL::Hive::Worker::log_dir ( )

  Arg [1] : (optional) string directory path
  Title   : log_dir
  Usage   : $worker_log_dir = $self->log_dir;
            $self->log_dir($worker_log_dir);
  Description: Storable getter/setter attribute for the directory where STDOUT and STRERR of the worker will be redirected to.
               In this directory each job will have its own .out and .err files.
  Returntype : string

Code:

click to view

◆ meadow_name()

public Bio::EnsEMBL::Hive::Worker::meadow_name ( )

Undocumented method

Code:

click to view

◆ meadow_type()

public Bio::EnsEMBL::Hive::Worker::meadow_type ( )

Undocumented method

Code:

click to view

◆ more_work_done()

public Bio::EnsEMBL::Hive::Worker::more_work_done ( )

Undocumented method

Code:

click to view

◆ perform_cleanup()

public Bio::EnsEMBL::Hive::Worker::perform_cleanup ( )

Undocumented method

Code:

click to view

◆ prev_job_error()

public Bio::EnsEMBL::Hive::Worker::prev_job_error ( )

Undocumented method

Code:

click to view

◆ process_id()

public Bio::EnsEMBL::Hive::Worker::process_id ( )

Undocumented method

Code:

click to view

◆ retry_throwing_jobs()

public Bio::EnsEMBL::Hive::Worker::retry_throwing_jobs ( )

Undocumented method

Code:

click to view

◆ run()

public void Bio::EnsEMBL::Hive::Worker::run ( )

  Title   :   run
  Usage   :   $worker->run;
  Description: 
    This is a self looping autonomous function to process jobs.
    First all STDOUT/STDERR is rediected, then looping commences.
    Looping consists of 
      1) claiming jobs,
      2) processing those jobs through an instance of the 'module class' of 
         the analysis asigned to this worker,  
      3) updating the job, analysis_stats, and hive tables to track the 
         progress of the job, the analysis and this worker.
    Looping stops when any one of these are met:
      1) there is no more jobs to process 
      2) job_limit is reached
      3) life_span has been reached.
  Returntype : none

Code:

click to view

sub run {
    my ($self, $specialization_arghash) = @_;
    if( my $worker_log_dir = $self->log_dir ) {
        $self->get_stdout_redirector->push( $worker_log_dir.'/worker.out' );
        $self->get_stderr_redirector->push( $worker_log_dir.'/worker.err' );
    }
    my $min_batch_time  = Bio::EnsEMBL::Hive::AnalysisStats::min_batch_time();
    my $job_adaptor     = $self->adaptor->db->get_AnalysisJobAdaptor;
    print "\n"; # to clear beekeeper's prompt in case output is not logged
    $self->worker_say( $self->toString() );
    $self->specialize_and_compile_wrapper( $specialization_arghash );
    while (!$self->cause_of_death) {  # Worker's lifespan loop (ends only when the worker dies for any reason)
        my $batches_stopwatch           = Bio::EnsEMBL::Hive::Utils::Stopwatch->new()->restart();
        my $jobs_done_by_batches_loop   = 0; # by all iterations of internal loop
        $self->{'_interval_partial_timing'} = {};
        if( my $special_batch = $self->special_batch() ) {
            my $special_batch_length = scalar(@$special_batch);     # has to be recorded because the list is gradually destroyed
            $jobs_done_by_batches_loop += $self->run_one_batch( $special_batch );
            $self->cause_of_death( $jobs_done_by_batches_loop == $special_batch_length ? 'JOB_LIMIT' : 'CONTAMINATED');
        } else {    # a proper "BATCHES" loop
            while (!$self->cause_of_death and $batches_stopwatch->get_elapsed < $min_batch_time) {
                my $current_role        = $self->current_role;
                if( scalar(@{ $job_adaptor->fetch_all_incomplete_jobs_by_role_id( $current_role->dbID ) }) ) {
                    my $msg = "Lost control. Check your Runnable for loose 'next' statements that are not part of a loop";
                    $self->worker_say( $msg );
                    $self->cause_of_death('CONTAMINATED');
                    $job_adaptor->release_undone_jobs_from_role($current_role, $msg);
                } elsif( $self->job_limiter->reached()) {
                    $self->worker_say( "job_limit reached (".$self->work_done." jobs completed)" );
                    $self->cause_of_death('JOB_LIMIT');
                } elsif ( my $alive_for_secs = $self->life_span_limit_reached()) {
                    $self->worker_say( "life_span limit reached (alive for $alive_for_secs secs)" );
                    $self->cause_of_death('LIFESPAN');
                } else {
                    my $desired_batch_size  = $current_role->analysis->stats->get_or_estimate_batch_size();
                    my $hit_the_limit;  # dummy at the moment
                    ($desired_batch_size, $hit_the_limit)   = $self->job_limiter->preliminary_offer( $desired_batch_size );
                    my $actual_batch = $job_adaptor->grab_jobs_for_role( $current_role, $desired_batch_size );
                    if(scalar(@$actual_batch)) {
                        $self->adaptor->db->get_AnalysisStatsAdaptor->interval_update_claim($self->current_role->analysis->dbID, scalar(@$actual_batch));
                        my $jobs_done_by_this_batch = $self->run_one_batch( $actual_batch );
                        $jobs_done_by_batches_loop += $jobs_done_by_this_batch;
                        $self->job_limiter->final_decision( $jobs_done_by_this_batch );
                    } else {
                        $self->cause_of_death('NO_WORK');
                    }
                }
            }
        }
        # The following two database-updating operations are resource-expensive (all workers hammering the same database+tables),
        # so they are not allowed to happen too frequently (not before $min_batch_time of work has been done)
        #
        if($jobs_done_by_batches_loop) {
            $self->adaptor->db->get_AnalysisStatsAdaptor->interval_update_work_done(
                $self->current_role->analysis->dbID,
                $jobs_done_by_batches_loop,
                $batches_stopwatch->get_elapsed,
                $self->{'_interval_partial_timing'}{'FETCH_INPUT'}  || 0,
                $self->{'_interval_partial_timing'}{'RUN'}          || 0,
                $self->{'_interval_partial_timing'}{'WRITE_OUTPUT'} || 0,
            );
        }
            # A mechanism whereby workers can be caused to exit even if they were doing fine:
        if (!$self->cause_of_death) {
            my $analysis = $self->current_role->analysis;
            my $stats = $analysis->stats;     # make sure it is fresh from the DB
            if( defined($stats->hive_capacity) && (0 <= $stats->hive_capacity) && ($self->adaptor->db->get_RoleAdaptor->get_hive_current_load >= 1.1)
             or defined($analysis->analysis_capacity) && (0 <= $analysis->analysis_capacity) && ($analysis->analysis_capacity < $stats->num_running_workers)
            ) {
                $self->cause_of_death('HIVE_OVERLOAD');
            }
        }
        my $cod = $self->cause_of_death() || '';
        if( $cod eq 'NO_WORK') {
            $self->adaptor->db->get_AnalysisStatsAdaptor->update_status( $self->current_role->analysis_id, 'ALL_CLAIMED' );
        }
        if( $cod =~ /^(NO_WORK|HIVE_OVERLOAD)$/ and $self->can_respecialize and (!$specialization_arghash->{'-analyses_pattern'} or $specialization_arghash->{'-analyses_pattern'}!~/^\w+$/) ) {
            my $old_role = $self->current_role;
            $self->adaptor->db->get_RoleAdaptor->finalize_role( $old_role, 1 );
            $self->current_role( undef );
            $self->cause_of_death(undef);
            $self->specialize_and_compile_wrapper( $specialization_arghash, $old_role->analysis );
        }
    }     # /Worker's lifespan loop
        # have runnable clean up any global/process files/data it may have created
    if($self->perform_cleanup) {
        if(my $runnable_object = $self->runnable_object()) {    # the temp_directory is actually kept in the Process object:
            $runnable_object->cleanup_worker_temp_directory();
        }
    }
    # The second arguments ("self_burial") controls whether we need to
    # release the current (unfinished) batch
    $self->adaptor->register_worker_death($self, ($self->cause_of_death eq 'CONTAMINATED' ? 0 : 1));
    if($self->debug) {
        $self->worker_say( 'AnalysisStats : '.$self->current_role->analysis->stats->toString ) if( $self->current_role );
        $self->worker_say( 'dbc '.$self->adaptor->db->dbc->disconnect_count. ' disconnect cycles' );
    }
    $self->worker_say( "Having completed ".$self->work_done." jobs the Worker exits : ".$self->cause_of_death  );
    if( $self->log_dir ) {
        $self->get_stdout_redirector->pop();
        $self->get_stderr_redirector->pop();
    }
}

◆ run_one_batch()

public Bio::EnsEMBL::Hive::Worker::run_one_batch ( )

Undocumented method

Code:

click to view

sub run_one_batch {
    my ($self, $jobs) = @_;
    my $jobs_done_here = 0;
    my $current_role            = $self->current_role;
    my $hive_use_param_stack    = $self->adaptor->db->hive_use_param_stack();
    my $accu_adaptor            = $self->adaptor->db->get_AccumulatorAdaptor;
    my $max_retry_count         = $current_role->analysis->max_retry_count();  # a constant (as the Worker is already specialized by the Queen) needed later for retrying jobs
    $self->adaptor->check_in_worker( $self );
    $self->adaptor->safe_synchronize_AnalysisStats( $current_role->analysis->stats );
    if($self->debug) {
        $self->worker_say( 'AnalysisStats : ' . $current_role->analysis->stats->toString );
        $self->worker_say( 'claimed '.scalar(@{$jobs}).' jobs to process' );
    }
    my $job_partial_timing;
    ONE_BATCH: while(my $job = shift @$jobs) {         # to make sure jobs go out of scope without undue delay
        my $job_id = $job->dbID();
        $self->worker_say( $job->toString ) if($self->debug); 
        my $job_stopwatch = Bio::EnsEMBL::Hive::Utils::Stopwatch->new();
        $job_partial_timing = {};
        $self->start_job_output_redirection($job);  # switch logging into job's STDERR
        eval {  # capture any throw/die
            my $runnable_object = $self->runnable_object();
            $runnable_object->input_job( $job );    # "take" the job
            $job->incomplete(1);
            $job->accu_hash( $accu_adaptor->fetch_structures_for_job_ids( $job_id )->{ $job_id } );
            $self->adaptor->db->dbc->query_count(0);
            $job_stopwatch->restart();
            my @params_precedence = (
                $runnable_object->param_defaults(),
                $self->adaptor->db->get_PipelineWideParametersAdaptor->fetch_param_hash(),
                $current_role->analysis->parameters(),
            );
            if( $hive_use_param_stack ) {
                my $input_ids_hash      = $job->adaptor->fetch_input_ids_for_job_ids( $job->param_id_stack, 2, 0 );     # input_ids have lower precedence (FOR EACH ID)
                my $accu_hash           = $accu_adaptor->fetch_structures_for_job_ids( $job->accu_id_stack, 2, 1 );     # accus have higher precedence (FOR EACH ID)
                my %input_id_accu_hash  = ( %$input_ids_hash, %$accu_hash );
                push @params_precedence, @input_id_accu_hash{ sort { $a <=> $b } keys %input_id_accu_hash }; # take a slice. Mmm...
            }
            push @params_precedence, $job->input_id(), $job->accu_hash();
            $job->param_init( $runnable_object->strict_hash_format(), @params_precedence );
            $self->worker_say( "Job $job_id unsubstituted_params= ".stringify($job->{'_unsubstituted_param_hash'}) ) if($self->debug());
            $job_partial_timing = $runnable_object->life_cycle();
        };
        if(my $msg = $@) {
            $job->died_somewhere( $job->incomplete );  # it will be OR'd inside
            $self->runnable_object->warning( $msg, $job->incomplete );
        }
            # whether the job completed successfully or not:
        $self->runnable_object->input_job( undef );   # release an extra reference to the job
        $job->runtime_msec( $job_stopwatch->get_elapsed );
        $job->query_count( $self->adaptor->db->dbc->query_count );
        my $job_completion_line = "Job $job_id : ". ($job->died_somewhere ? 'died' : 'complete' );
        print STDERR "\n$job_completion_line\n" if($self->log_dir and ($self->debug or $job->died_somewhere));  # one copy goes to the job's STDERR
        $self->stop_job_output_redirection($job);                                                               # and then we switch back to worker's STDERR
        $self->worker_say( $job_completion_line );                                                              # one copy goes to the worker's STDERR
        $self->current_role->register_attempt( ! $job->died_somewhere );
        if($job->died_somewhere) {
                # If the job specifically said what to do next, respect that last wish.
                # Otherwise follow the default behaviour set by the beekeeper in $worker:
                #
            my $may_retry = defined($job->transient_error) ? $job->transient_error : $self->retry_throwing_jobs;
            $job->adaptor->release_and_age_job( $job_id, $max_retry_count, $may_retry, $job->runtime_msec );
            if( $self->prev_job_error                # a bit of AI: if the previous job failed as well, it is LIKELY that we have contamination
             or $job->lethal_for_worker ) {          # trust the job's expert knowledge
                my $reason = $self->prev_job_error            ? 'two failed jobs in a row'
                           :                                    'suggested by job itself';
                $self->worker_say( "Job's error has contaminated the Worker ($reason), so the Worker will now die" );
                $self->cause_of_death('CONTAMINATED');
                last ONE_BATCH;
            }
        } else {    # job successfully completed:
            $self->more_work_done( $job_partial_timing );
            $jobs_done_here++;
            $job->set_and_update_status('DONE');
            if(my $semaphored_job_id = $job->semaphored_job_id) {
                my $dbc = $self->adaptor->db->dbc;
                $dbc->do( "SELECT 1 FROM job WHERE job_id=$semaphored_job_id FOR UPDATE" ) if($dbc->driver ne 'sqlite');
                $job->adaptor->decrease_semaphore_count_for_jobid( $semaphored_job_id );    # step-unblock the semaphore
            }
            if($job->lethal_for_worker) {
                $self->worker_say( "The Job, although complete, wants the Worker to die" );
                $self->cause_of_death('CONTAMINATED');
                last ONE_BATCH;
            }
        }
        $self->prev_job_error( $job->died_somewhere );
        $self->enter_status('READY');
    } # /while(my $job = shift @$jobs)
    return $jobs_done_here;
}

◆ runnable_object()

public Bio::EnsEMBL::Hive::Worker::runnable_object ( )

Undocumented method

Code:

click to view

◆ set_and_update_status()

public Bio::EnsEMBL::Hive::Worker::set_and_update_status ( )

Undocumented method

Code:

click to view

◆ special_batch()

public Bio::EnsEMBL::Hive::Worker::special_batch ( )

Undocumented method

Code:

click to view

◆ specialize_and_compile_wrapper()

public Bio::EnsEMBL::Hive::Worker::specialize_and_compile_wrapper ( )

Undocumented method

Code:

click to view

◆ start_job_output_redirection()

public Bio::EnsEMBL::Hive::Worker::start_job_output_redirection ( )

Undocumented method

Code:

click to view

◆ status()

public Bio::EnsEMBL::Hive::Worker::status ( )

Undocumented method

Code:

click to view

◆ stop_job_output_redirection()

public Bio::EnsEMBL::Hive::Worker::stop_job_output_redirection ( )

Undocumented method

Code:

click to view

◆ toString()

public Bio::EnsEMBL::Hive::Worker::toString ( )

Undocumented method

Code:

click to view

◆ work_done()

public Bio::EnsEMBL::Hive::Worker::work_done ( )

Undocumented method

Code:

click to view

◆ worker_say()

public Bio::EnsEMBL::Hive::Worker::worker_say ( )

Undocumented method

Code:

click to view

The documentation for this class was generated from the following file:

modules/Bio/EnsEMBL/Hive/Worker.pm

Public Member Functions

Detailed Description

Description

Member Function Documentation

◆ born()

◆ can_respecialize()

◆ cause_of_death()

◆ current_role()

◆ debug()

◆ died()

◆ enter_status()

◆ execute_writes()

◆ get_stderr_redirector()

◆ get_stdout_redirector()

◆ host()

◆ init()

◆ job_limiter()

◆ last_check_in()

◆ life_span()

◆ life_span_limit_reached()

◆ lifespan_stopwatch()

◆ log_dir()

◆ meadow_name()

◆ meadow_type()

◆ more_work_done()

◆ perform_cleanup()

◆ prev_job_error()

◆ process_id()

◆ retry_throwing_jobs()

◆ run()

◆ run_one_batch()

◆ runnable_object()

◆ set_and_update_status()

◆ special_batch()

◆ specialize_and_compile_wrapper()

◆ start_job_output_redirection()

◆ status()

◆ stop_job_output_redirection()

◆ toString()

◆ work_done()

◆ worker_say()