Main Content


Create new task in job



    t = createTask(j,fcn,N,{x1,...,xn}) creates a new task object in job j, and returns t, a handle to the added task object. This task evaluates the function specified by a function handle or function name fcn, with the given cell array of input arguments {x1,...,xn}, and returns N output arguments.


    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 specified by a function handle or function name fcn. The cell array C1 provides the input arguments to the first task, C2 to the second task, and so on, so that there is one task per cell array of input arguments.

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

    Multidimensional matrices of inputs fcn, N and {C1,...,Cm} are supported. If fcn is a cell array, or N is a double array, their dimensions must match those of {C1,...,Cm}. The output t is a vector with the same number of elements as {C1,...,Cm}.

    Note that because a communicating job has only one task, this form of vectorized task creation is not appropriate for such jobs.


    t = createTask(___,Name,Value) specifies task object properties using one or more name-value pair arguments. Use this syntax in addition to any of the input argument combinations in previous syntaxes. For a list of valid properties, see the parallel.Task object reference page. The property name must be a character vector, with the value being the appropriate type for that property. The values specified in these name-value pairs override the values in the profile. If an invalid property name or property value is specified, the object is not created.


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


    collapse all

    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 which generates a 10-by-10 random matrix.

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

    Run the job.


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

    taskoutput = fetchOutputs(j);

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

        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

    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 to each task.

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

    t is a 3-by-1 matrix of task objects.

    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 T.

    for idx = 1:150
        tasks(idx) = createTask(j, @magic, 1, {idx});
    whos tasks
      Name       Size             Bytes  Class                    Attributes
      tasks      1x150             1200  parallel.task.CJSTask              

    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 the property values specified in the cluster profile myMJS_Cluster.

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

    Create a job object on the default cluster.

    c = parcluster;
    job = createJob(c);

    To create a single task with all cell arrays as its input arguments, use the {C1} syntax of createTask. For example, to create a task that runs strjoin({'1','1','2'},{'+','='}), use the following code.

    task = createTask(job,@strjoin,1,{{{'1','1','2'},{'+','='}}});
    ans = 1×3 cell
        {'1'}    {'1'}    {'2'}
    ans = 1×2 cell
        {'+'}    {'='}

    Submit and wait for the job.


    Retrieve the outputs and display them.

    outputs = fetchOutputs(job);

    If you attempt to use the {inputargs} syntax with {inputargs} = {{'1','1','2'},{'+','='}}, then createTask uses the {C1,...,Cm} syntax and creates multiple tasks. For example, the following code incorrectly creates two tasks, one for strjoin('1','1','2') and one for strjoin('+','=').

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

    Input Arguments

    collapse all

    Job that the task object is created in, specified as a parallel.Job object.

    Example: j = createJob;

    Data Types: parallel.Job

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

    Example: createTask(j,@zeros,1,{x,y}); specifies the task must evaluate the zeros function.

    Data Types: char | string | cell | function_handle

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

    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 the function fcn, specified as a cell array. Each element in the cell array will be passed as a separate input argument.

    Example: createTask(j,@zeros,1,{x,y}); specifies the input arguments x and y to the zeros function.

    Data Types: cell

    Cell array input arguments defining input arguments to each of m tasks, specified as a cell array of cell arrays. A task is created for each cell array.

    Example: createTask(j,@zeros,1,{{x1,y1},{x2,y2},{x3,y3}}); specifies {{x1,y1},{x2,y2},{x3,y3}} as input arguments to three tasks that evaluate the zeros function.

    Data Types: cell

    Cluster profile to identify the cluster, specified as the comma-separated pair consisting of 'Profile' and a character vector or string for the ProfileName.

    Example: j = createTask(j,@zeros,1,{x,y},'Profile','Processes');

    Data Types: char | string

    Output Arguments

    collapse all

    Task, returned as a parallel.Task object.

    Data Types: parallel.Task

    Version History

    Introduced before R2006a