Jobs

Functions
	tripal_get_job ($job_id)
	tripal_add_job ($job_name, $modulename, $callback, $arguments, $uid, $priority=10, $includes=[], $ignore_duplicate=FALSE)
	tripal_is_job_running ()
	tripal_max_jobs_exceeded ($max_jobs)
	tripal_rerun_job ($job_id, $goto_jobs_page=NULL)
	tripal_cancel_job ($job_id, $redirect=NULL)
	tripal_launch_job ($do_parallel=0, $job_id=NULL, $max_jobs=-1, $single=0)
	tripal_set_job_progress ($job_id, $percentage)
	tripal_get_job_progress ($job_id)
	tripal_get_active_jobs ($modulename=NULL)
	tripal_execute_job ($job_id, $redirect=TRUE)

Detailed Description

Tripal offers a job management subsystem for managing tasks that may require an extended period of time for completion. Tripal provides several administrative tasks that may time out and not complete due to limitations of the web server. To circumvent this, as well as provide more fine-grained control and monitoring, Tripal uses a jobs management system.

The Tripal jobs management system allows administrators to submit tasks to be performed which can then be launched through a UNIX command-line PHP script or cron job. This command-line script can be added to a cron entry along-side the Drupal cron entry for automatic, regular launching of Tripal jobs. The order of execution of waiting jobs is determined first by priority and second by the order the jobs were entered.

Function Documentation

tripal_add_job()

tripal_add_job	(		$job_name,
			$modulename,
			$callback,
			$arguments,
			$uid,
			$priority = 10,
			$includes = [],
			$ignore_duplicate = FALSE
	)

Adds a job to the Tripal Job queue

Parameters

$job_name	The human readable name for the job
$modulename	The name of the module adding the job
$callback	The name of a function to be called when the job is executed
$arguments	An array of arguments to be passed on to the callback
$uid	The uid of the user adding the job
$priority	The priority at which to run the job where the highest priority is 10 and the lowest priority is 1. The default priority is 10.
$includes	An array of paths to files that should be included in order to execute the job. Use the module_load_include function to get a path for a given file.
$ignore_duplicate	. Set to TRUE to not add the job if it has the same name as another job which has not yet run. The default is TRUE.

Returns

The job_id of the registered job, or FALSE on failure.

Example usage:

$args = array($dfile, $organism_id, $type, $library_id, $re_name,
$re_uname,
      $re_accession, $db_id, $rel_type, $re_subject, $parent_type,
$method,
      $user->uid, $analysis_id, $match_type);
 
$includes = array()
$includes[] = module_load_include('inc', 'tripal_chado',
                             'includes/loaders/tripal_chado.fasta_loader');
 
tripal_add_job("Import FASTA file: $dfile", 'tripal_feature',
  'tripal_feature_load_fasta', $args, $user->uid, 10, $includes);

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.

tripal_cancel_job()

tripal_cancel_job	(		$job_id,
			$redirect = NULL
	)

Cancel a Tripal Job currently waiting in the job queue.

Parameters

$job_id	The job_id of the job to be cancelled
$redirect	DEPRECATED

Returns

FALSE if the an error occured or the job could not be canceled, TRUE otherwise.

tripal_execute_job()

tripal_execute_job	(		$job_id,
			$redirect = TRUE
	)

Execute a specific Tripal Job.

Parameters

$job_id	The job id to be exeuted.
$redirect	DEPRECATED

tripal_get_active_jobs()

tripal_get_active_jobs

(

$modulename = NULL

)

Returns a list of jobs that are active.

Parameters

$modulename

Limit the list returned to those that were added by a specific module. If no module name is provided then all active jobs are returned.

Returns

An array of objects where each object describes a tripal job. If no jobs were found then an empty array is returned. Each object will have the following members:

• job_id: The unique ID number for the job.
• uid: The ID of the user that submitted the job.
• job_name: The human-readable name of the job.
• modulename: The name of the module that submitted the job.
• callback: The callback function to be called when the job is run.
• arguments: An array of arguments to be passed to the callback function.
• progress: The percent progress of completion if the job is running.
• status: The status of the job: Waiting, Completed, Running or Cancelled.
• submit_date: The UNIX timestamp when the job was submitted.
• start_time: The UNIX timestamp for when the job started running.
• end_time: The UNIX timestampe when the job completed running.
• error_msg: Any error message that occured during execution of the job.
• prirotiy: The execution priority of the job (value between 1 and 10)

tripal_get_job()

tripal_get_job

(

$job_id

)

DEPRECATED

Use the TripalJob::load function instead

Retrieve information regarding a tripal job

Parameters

$job_id

The unique identifier of the job

Returns

An object representing a record from the tripal_job table or FALSE on failure.

tripal_get_job_progress()

tripal_get_job_progress

(

$job_id

)

Retrieves the current proress of a job.

Parameters

$job_id

The job_id to get the progress for

Returns

A value between 0 and 100 indicating the percentage complete of the job. FALSE on failure.

tripal_is_job_running()

tripal_is_job_running

(

)

Indicates if any jobs are running.

This function will check the system to see if a job has a process ID and if that process ID is still running. It will update the job status accordingly before returning.

Returns

Returns TRUE if any job is running or FALSE otherwise.

tripal_launch_job()

tripal_launch_job	(		$do_parallel = 0,
			$job_id = NULL,
			$max_jobs = -1,
			$single = 0
	)

A function used to manually launch all queued tripal jobs.

Parameters

$do_parallel	A boolean indicating whether jobs should be attempted to run in parallel
$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.
$max_jobs	The maximum number of jobs that should be run concurrently. If -1 then unlimited.
$single	Ensures only a single job is run rather then the entire queue.

tripal_max_jobs_exceeded()

tripal_max_jobs_exceeded

(

$max_jobs

)

Check for too many concurrent jobs.

Parameters

$max_jobs

The maximum number of concurrent jobs to allow; -1 = no limit

tripal_rerun_job()

tripal_rerun_job	(		$job_id,
			$goto_jobs_page = NULL
	)

Set a job to be re-run (ie: add it back into the job queue).

Parameters

$job_id	The job_id of the job to be re-ran
$goto_jobs_page	DEPRECATED If set to TRUE then after the re run job is added Drupal will redirect to the jobs page

tripal_set_job_progress()

tripal_set_job_progress	(		$job_id,
			$percentage
	)

An internal function for setting the progress for a current job.

Parameters

$job_id	The job_id to set the progress for
$percentage	The progress to set the job to

Returns

True on success and False otherwise