createTask

Create new task in job

Syntax

t = createTask(j,fcn,N,{x1,...,xn})

t = createTask(j,fcn,N,{C1,...,Cm})

t = createTask(___,Name=Value)

t = createTask(___,Profile=profileName)

Description

t = createTask(j,fcn,N,{x1,...,xn}) creates a new task in job j and returns t, the corresponding task object. This task evaluates the function fcn with the cell array of input arguments {x1,...,xn} and returns N output arguments.

If you attempt to create one task with arrays of cells arrays as input, createTask creates a task for each cell array. To create one task with arrays of cell arrays as input, see Create Single Task with Arrays of Cell Array as Inputs.

t = createTask(j,fcn,N,{C1,...,Cm}) uses a cell array of m cell arrays of input arguments to create m task objects in job j. Each task evaluates the function fcn. The cell array C1 provides the input arguments to the first task, C2 to the second task, and so on, so that each task has a corresponding cell array of input arguments.

If fcn is a cell array, each element of fcn specifies a function for each task and fcn must have m elements. If N is a numeric array, each element specifies the number of output arguments for each task.

If fcn is a cell array or N is a numeric array, their dimensions must match those of {C1,...,Cm}. The output t is a vector with the same number of elements as {C1,...,Cm}.

Because a communicating job has only one task, this form of vectorized task creation is not appropriate for these jobs.

t = createTask(___,Name=Value) specifies task object properties using one or more name-value arguments. For a list of supported properties, see parallel.Task.

t = createTask(___,Profile=profileName) creates a task object with property values corresponding to the cluster profile ProfileName. For details about defining and applying cluster profiles, see Discover Clusters and Use Cluster Profiles.

Examples

Create Job with One Task

This example shows how to create one task for a job.

Create a cluster using the default profile and then create a job.

c = parcluster;
j = createJob(c);

Add a task that generates a 10-by-10 random matrix.

t = createTask(j,@rand,1,{10,10});

Run the job.

submit(j);

Wait for the job to finish running, then get the output from the task evaluation using the fetchOutputs function.

wait(j);
taskoutput = fetchOutputs(j);

Finally, show the 10-by-10 random matrix.

disp(taskoutput{1});

    0.1349    0.3414    0.0378    0.2873    0.6815    0.1700    0.6341    0.8666    0.1985    0.0739
    0.6744    0.6596    0.1527    0.1777    0.8329    0.3007    0.9087    0.9242    0.2509    0.7697
    0.9301    0.9604    0.0199    0.4932    0.7620    0.8125    0.9334    0.4732    0.5438    0.4916
    0.5332    0.2081    0.7638    0.8810    0.3301    0.8027    0.9230    0.5052    0.0748    0.7206
    0.1150    0.0206    0.2389    0.3993    0.8738    0.4026    0.4597    0.4667    0.9900    0.7507
    0.6540    0.0097    0.7247    0.3138    0.4917    0.9944    0.2229    0.7484    0.7052    0.4890
    0.2621    0.4432    0.3819    0.3073    0.6435    0.7122    0.0043    0.2366    0.4252    0.2600
    0.9625    0.6220    0.1527    0.6538    0.5951    0.5486    0.6156    0.1400    0.8675    0.6854
    0.8972    0.9800    0.4316    0.3740    0.0846    0.9692    0.2890    0.7388    0.8969    0.8876
    0.3187    0.4841    0.8672    0.2539    0.1876    0.6113    0.0459    0.9253    0.6454    0.9783

Add Multiple Tasks to Job

This example shows two ways to add multiple tasks to a job.

Use one call to create three tasks for a job, each of which uses a different function. Provide a cell array of three cell arrays defining the input arguments for each task.

c = parcluster;
j = createJob(c);
t = createTask(j,{@rand,@magic,@ones},1,{{3,3} {3} {3,3}});

Display and view information about t.

t

t = 

 3x1 Task array:
 
         ID        State              FinishDateTime  Function  Errors  Warnings
       -------------------------------------------------------------------------
    1     1      pending                                  rand       0         0
    2     2      pending                                 magic       0         0
    3     3      pending                                  ones       0         0

whos t

  Name      Size            Bytes  Class                    Attributes

  t         3x1                24  parallel.task.CJSTask              

Alternatively, use a for-loop to create 150 tasks for job j. Display the properties of tasks.

for idx = 1:150
    tasks(idx) = createTask(j,@magic,1,{idx});
end
whos tasks

  Name       Size             Bytes  Class                    Attributes

  tasks      1x150             1200  parallel.task.CJSTask              

Create Task with Different Properties

Create a task that captures the worker diary, regardless of the setting in the cluster profile.

c = parcluster;
j = createJob(c);
t1 = createTask(j,@rand,1,{10,10},CaptureDiary=true);

Create a task with property values corresponding to the myMJS_Cluster cluster profile.

t2 = createTask(j,@magic,1,{10},Profile="myMJS_Cluster");

Create Single Task with Arrays of Cell Array as Inputs

Create a job object on the default cluster.

c = parcluster;
job = createJob(c);

Create a task that runs strjoin({'1','1','2'},{'+','='}).

task = createTask(job,@strjoin,1,{{{'1','1','2'},{'+','='}}});
task.InputArguments{:}

ans = 1×3 cell
    {'1'}    {'1'}    {'2'}

ans = 1×2 cell
    {'+'}    {'='}

Submit and wait for the job.

submit(job);
wait(job);

Retrieve and display the outputs.

outputs = fetchOutputs(job);
disp(outputs{1});

1+1=2

Input Arguments

j — Job in which software creates task

parallel.Job object

Job in which the software creates the task, specified as a parallel.Job object.

fcn — Function that task evaluates

function handle | character vector | string scalar | cell array of function handles

Function that the task evaluates, specified as function handle, a character vector or string array that specifies a function name, or a cell array of function handles. Specify multiple task functions as a cell array of function handles. The cell array must have the same number of elements as the {C1,...,Cm} input.

Example: @zeros

Data Types: char | string | cell | function_handle

N — Number of outputs from fcn

nonnegative integer | array of nonnegative integers

Number of outputs from fcn, specified as a nonnegative integer or an array of nonnegative integers. Specify multiple numbers of outputs as an array of nonnegative integers. The array must have the same number of elements as {C1,...,Cm} input.

Example: createTask(j,@zeros,1,{x,y}); specifies a single output is expected.

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64

{x1,...,xn} — Input arguments to fcn

cell array

Input arguments to fcn, specified as a cell array. The software passes each element in the cell array to fcn as a separate input argument.

Example: {x,y}

Data Types: cell

{C1,...,Cm} — Input arguments to each task

cell arrays of cell arrays

Input argument to each task, specified as a cell array of cell arrays. The software creates a task for each cell array.

Example: {{x1,y1},{x2,y2},{x3,y3}}

Data Types: cell

profileName — Cluster profile

character vector | string scalar

Cluster profile, specified as a character vector or string scalar.

Example: "Processes"

Data Types: char | string

Output Arguments

t — Task

parallel.Task object

Task, returned as a parallel.Task object.

Version History

Introduced before R2006a