uid, $analysis_id, $match_type); * * tripal_add_job("Import FASTA file: $dfile", 'tripal_feature', * 'tripal_feature_load_fasta', $args, $user->uid); * @endcode * The code above is copied from the tripal_feature/fasta_loader.php file. The * snipped first builds an array of arguments that will then be passed to the * tripal_add_job function. The number of arguments provided in the $arguments * variable should match the argument set for the callback function provided * as the third argument. * * @ingroup tripal_jobs_api */ function tripal_add_job($job_name, $modulename, $callback, $arguments, $uid, $priority = 10) { global $user; // convert the arguments into a string for storage in the database $args = array(); if (is_array($arguments)) { $args = serialize($arguments); } $record = new stdClass(); $record->job_name = $job_name; $record->modulename = $modulename; $record->callback = $callback; $record->status = 'Waiting'; $record->submit_date = REQUEST_TIME; $record->uid = $uid; $record->priority = $priority; # the lower the number the higher the priority $record->arguments = $args; if (drupal_write_record('tripal_jobs', $record)) { drupal_set_message(t("Job '%job_name' submitted.", array('%job_name' => $job_name))); if (user_access('administer tripal')) { $jobs_url = url("admin/tripal/tripal_jobs"); drupal_set_message(t("Check the jobs page for status.", array('!jobs_url' => $jobs_url))); drupal_set_message(t("You can execute the job queue manually on the command line " . "using the following Drush command:
drush trp-run-jobs --username=%uname --root=%base_path", array('%base_path' => DRUPAL_ROOT, '%uname' => $user->name))); } } else { drupal_set_message(t("Failed to add job %job_name.", array('%job_name' => $job_name)), 'error'); } return $record->job_id; } /** * Retrieve information regarding a tripal job * * @param $job_id * The unique identifier of the job * * @return * An object describing the job * * @ingroup tripal_jobs_api */ function tripal_get_job($job_id) { $job = db_query('SELECT j.* FROM {tripal_jobs} j WHERE j.job_id=:job_id', array(':job_id' => $job_id)) ->fetchObject(); return $job; } /** * Returns a list of running tripal jobs * * @return * and array of objects where each object describes a running job or FALSE if no jobs are running * * @ingroup tripal_jobs_api */ function tripal_is_job_running() { // iterate through each job that has not ended // and see if it is still running. If it is not // running but does not have an end_time then // set the end time and set the status to 'Error' $sql = "SELECT * FROM {tripal_jobs} TJ " . "WHERE TJ.end_time IS NULL and NOT TJ.start_time IS NULL "; $jobs = db_query($sql); foreach ($jobs as $job) { $status = `ps -p $job->pid -o pid=`; if ($job->pid && $status) { // the job is still running so let it go // we return 1 to indicate that a job is running return TRUE; } else { // the job is not running so terminate it $record = new stdClass(); $record->job_id = $job->job_id; $record->end_time = REQUEST_TIME; $record->status = 'Error'; $record->error_msg = 'Job has terminated unexpectedly.'; drupal_write_record('tripal_jobs', $record, 'job_id'); } } // return 1 to indicate that no jobs are currently running. return FALSE; } /** * Returns the start time for a given job * * @param $job * An object describing the job * * @return * The start time of the job if it was already run and either "Cancelled" or "Not Yet Started" otherwise * * @ingroup tripal_jobs_api */ function tripal_get_job_start($job) { if ($job->start_time > 0) { $start = format_date($job->start_time); } else { if (strcmp($job->job_status, 'Cancelled')==0) { $start = 'Cancelled'; } else { $start = 'Not Yet Started'; } } return $start; } /** * Returns the end time for a given job * * @param $job * An object describing the job * * @return * The end time of the job if it was already run and empty otherwise * * @ingroup tripal_jobs_api */ function tripal_get_job_end($job) { if ($job->end_time > 0) { $end = format_date($job->end_time); } else { $end = ''; } return $end; } /** * Set a job to be re-ran (ie: add it back into the job queue) * * @param $job_id * The job_id of the job to be re-ran * @param $goto_jobs_page * If set to TRUE then after the re run job is added Drupal will redirect to the jobs page * * @ingroup tripal_jobs_api */ function tripal_rerun_job($job_id, $goto_jobs_page = TRUE) { global $user; $user_id = $user->uid; $sql = "SELECT * FROM {tripal_jobs} WHERE job_id = :job_id"; $results = db_query($sql, array(':job_id' => $job_id)); $job = $results->fetchObject(); // arguments for jobs used to be stored as plain string with a double colon // separating them. But as of Tripal v2.0 the arguments are stored as // a serialized array. To be backwards compatible, we should check for serialization // and if not then we will use the old style $args = unserialize($job->arguments); if (!$args) { $args = explode("::", $job->arguments); } $job_id = tripal_add_job($job->job_name, $job->modulename, $job->callback, $args, $user_id, $job->priority); if ($goto_jobs_page) { drupal_goto("admin/tripal/tripal_jobs"); } return $job_id; } /** * Cancel a Tripal Job currently waiting in the job queue * * @param $job_id * The job_id of the job to be cancelled * * @ingroup tripal_jobs_api */ function tripal_cancel_job($job_id, $redirect = TRUE) { $sql = "SELECT * FROM {tripal_jobs} WHERE job_id = :job_id"; $results = db_query($sql, array(':job_id' => $job_id)); $job = $results->fetchObject(); // set the end time for this job if ($job->start_time == 0) { $record = new stdClass(); $record->job_id = $job->job_id; $record->end_time = REQUEST_TIME; $record->status = 'Cancelled'; $record->progress = '0'; drupal_write_record('tripal_jobs', $record, 'job_id'); drupal_set_message(t("Job #%job_id cancelled", array('%job_id' => $job_id))); } else { drupal_set_message(t("Job %job_id cannot be cancelled. It is in progress or has finished.", array('%job_id' => $job_id))); } if ($redirect) { drupal_goto("admin/tripal/tripal_jobs"); } } /** * A function used to manually launch all queued tripal jobs * * @param $do_parallel * A boolean indicating whether jobs should be attempted to run in parallel * * @param $job_id * To launch a specific job provide the job id. This option should be * used sparingly as the jobs queue managment system should launch jobs * based on order and priority. However there are times when a specific * job needs to be launched and this argument will allow it. Only jobs * which have not been run previously will run. * * @ingroup tripal_jobs_api */ function tripal_launch_job($do_parallel = 0, $job_id = NULL) { // first check if any jobs are currently running // if they are, don't continue, we don't want to have // more than one job script running at a time if (!$do_parallel and tripal_is_job_running()) { print "Jobs are still running. Use the --parallel=1 option with the Drush command to run jobs in parallel."; return; } // get all jobs that have not started and order them such that // they are processed in a FIFO manner. if ($job_id) { $sql = "SELECT * FROM {tripal_jobs} TJ " . "WHERE TJ.start_time IS NULL and TJ.end_time IS NULL and TJ.job_id = :job_id " . "ORDER BY priority ASC,job_id ASC"; $job_res = db_query($sql, array(':job_id' => $job_id)); } else { $sql = "SELECT * FROM {tripal_jobs} TJ " . "WHERE TJ.start_time IS NULL and TJ.end_time IS NULL " . "ORDER BY priority ASC,job_id ASC"; $job_res = db_query($sql); } foreach ($job_res as $job) { // set the start time for this job $record = new stdClass(); $record->job_id = $job->job_id; $record->start_time = REQUEST_TIME; $record->status = 'Running'; $record->pid = getmypid(); drupal_write_record('tripal_jobs', $record, 'job_id'); // call the function provided in the callback column. // Add the job_id as the last item in the list of arguments. All // callback functions should support this argument. $callback = $job->callback; // arguments for jobs used to be stored as plain string with a double colon // separating them. But as of Tripal v2.0 the arguments are stored as // a serialized array. To be backwards compatible, we should check for serialization // and if not then we will use the old style $args = unserialize($job->arguments); if (!$args) { $args = explode("::", $job->arguments); } $args[] = $job->job_id; // We need to do some additional processing for printing since the switch // to serialized arrays now allows nested arrays which cause errors when // printed using implode alone. $string_args = array(); foreach ($args as $k => $a) { if (is_array($a)) { $string_args[$k] = 'Array'; } elseif (is_object($a)) { $string_args[$k] = 'Object'; } else { $string_args[$k] = $a; } } print "Calling: $callback(" . implode(", ", $string_args) . ")\n"; call_user_func_array($callback, $args); // set the end time for this job $record->end_time = REQUEST_TIME; $record->status = 'Completed'; $record->progress = '100'; drupal_write_record('tripal_jobs', $record, 'job_id'); // send an email to the user advising that the job has finished } } /** * An internal function for setting the progress for a current job * * @param $job_id * The job_id to set the progress for * @param $percentage * The progress to set the job to * * @return * True on success and False otherwise * * @ingroup tripal_core */ function tripal_set_job_progress($job_id, $percentage) { if (preg_match("/^(\d+|100)$/", $percentage)) { $record = new stdClass(); $record->job_id = $job_id; $record->progress = $percentage; if (drupal_write_record('tripal_jobs', $record, 'job_id')) { return TRUE; } } return FALSE; } /** * Returns a list of jobs associated with the given module * * @param $modulename * The module to return a list of jobs for * * @return * An array of objects where each object describes a tripal job * * @ingroup tripal_jobs_api */ function tripal_get_active_jobs($modulename) { $sql = "SELECT * FROM {tripal_jobs} TJ " . "WHERE TJ.end_time IS NULL and TJ.modulename = :modulename "; $results = db_query($sql, array(':modulename' => $modulename)); return $results->fetchObject(); } /** * Returns the date the job was added to the queue * * @param $job * An object describing the job * * @return * The date teh job was submitted * * @ingroup tripal_jobs_api */ function tripal_get_job_submit_date($job) { return format_date($job->submit_date); }