Apply Callbacks to MATLAB Job Scheduler Jobs and Tasks

The MATLAB^® Job Scheduler has the ability to trigger callbacks in the client session whenever jobs or tasks in the MATLAB Job Scheduler cluster change to specific states.

Client objects representing jobs and tasks in a MATLAB Job Scheduler cluster include the following properties:

Callback Property Object Cluster Profile Manager Field Description

Callback Property	Object	Cluster Profile Manager Field	Description
`QueuedFcn`	Job only	`JobQueuedFcn`	Specifies the function to execute in the client when a job is submitted to the MATLAB Job Scheduler queue
`RunningFcn`	Job or task	`JobRunningFcn` `TaskRunningFcn`	Specifies the function to execute in the client when a job or task begins its execution
`FinishedFcn`	Job or task	`JobFinishedFcn` `TaskFinishedFcn`	Specifies the function to execute in the client when a job or task completes its execution

QueuedFcn

Job only

JobQueuedFcn

Specifies the function to execute in the client when a job is submitted to the MATLAB Job Scheduler queue

RunningFcn

Job or task

JobRunningFcn

TaskRunningFcn

Specifies the function to execute in the client when a job or task begins its execution

FinishedFcn

Job or task

JobFinishedFcn

TaskFinishedFcn

Specifies the function to execute in the client when a job or task completes its execution

You can set each of these properties to any valid MATLAB callback value in the Cluster Profile Manager, see the table and Add and Modify Cluster Profiles. The callback follows the same behavior for Handle Graphics^®, passing into the callback function the object (job or task) that makes the call and an empty argument of event data.

These properties apply only in the client MATLAB session in which they are set. Later sessions that access the same job or task objects do not inherit the settings from previous sessions. You can apply the properties to existing jobs and tasks at the command-line, but the cluster profile settings apply only at the time these objects are first created.

Note

The callback properties are available only when using a MATLAB Job Scheduler cluster.

Example 1. Create Callbacks at the Command Line

This example shows how to create job and task callbacks at the client session command line.

Create and save a callback function clientTaskCompleted.m on the path of the MATLAB client, with the following content:

function clientTaskCompleted(task,eventdata)
   disp(['Finished task: ' num2str(task.ID)])

Create a job and set its QueuedFcn, RunningFcn, and FinishedFcn properties, using a function handle to an anonymous function that sends information to the display.

c = parcluster('MyMJS');
j = createJob(c,'Name','Job_52a');
j.QueuedFcn = @(job,eventdata) disp([job.Name ' now ' job.State]);
j.RunningFcn = @(job,eventdata) disp([job.Name ' now ' job.State]);
j.FinishedFcn = @(job,eventdata) disp([job.Name ' now ' job.State]);

Create a task whose FinishedFcn is a function handle to the separate function.

createTask(j,@rand,1,{2,4}, ...
    'FinishedFcn',@clientTaskCompleted);

Run the job and note the output messages from both the job and task callbacks.

submit(j)

Job_52a now queued
Job_52a now running
Finished task: 1
Job_52a now finished

To use the same callbacks for any jobs and tasks on a given cluster, you should set these properties in the cluster profile. For details on editing profiles in the profile manager, see Discover Clusters and Use Cluster Profiles. These property settings apply to any jobs and tasks created using a cluster derived from this profile. The sequence is important, and must occur in this order:

Set the callback property values for the profile in the profile manager.
Use the cluster profile to create a cluster object in MATLAB.
Use the cluster object to create jobs and then tasks.

Example 2. Set Callbacks in a Cluster Profile

This example shows how to set several job and task callback properties using the profile manager.

Edit your MATLAB Job Scheduler cluster profile in the profile manager so that you can set the callback properties to the same values in the previous example. The saved profile looks like this:

The Cluster Profile Manager showing the callback properties of a MATLAB Job Scheduler cluster profile. The JobFinishedFcn, JobRunningFcn, and JobQueuedFcn all display the name of the job and its status. The TaskFinishedFcn is the clientTaskCompleted function.

Create and save a callback function clientTaskCompleted.m on the path of the MATLAB client, with the following content. (If you created this function for the previous example, you can use that.)

function clientTaskCompleted(task,eventdata)
   disp(['Finished task: ' num2str(task.ID)])

Create objects for the cluster, job, and task. Then submit the job. All the callback properties are set from the profile when the objects are created.

c = parcluster('MyMJS');
j = createJob(c,'Name','Job_52a');
createTask(j,@rand,1,{2,4});

submit(j)

Job_52a now queued
Job_52a now running
Finished task: 1
Job_52a now finished

Tips

You should avoid running code in your callback functions that might cause conflicts. For example, if every task in a job has a callback that plots its results, there is no guarantee to the order in which the tasks finish, so the plots might overwrite each other. Likewise, the FinishFcn callback for a job might be triggered to start before the FinishFcn callbacks for all its tasks are complete.
Submissions made with batch use applicable job and task callbacks. Parallel pools can trigger job callbacks defined by their cluster profile.