Main Content

createTask

Create new task in job

collapse all in page

    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.

    example

    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.

    example

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

    example

    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.

    example

    Examples

    collapse all

    Open Live Script

    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
    Open Live Script

    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
    Open Live Script

    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");
    Open Live Script

    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

    collapse all

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

    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

    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

    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

    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

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

    Example: "Processes"

    Data Types: char | string

    Output Arguments

    collapse all

    Task, returned as a parallel.Task object.

    Version History

    Introduced before R2006a

    See Also

    | | |