Main Content

createCommunicatingJob

Create communicating job on cluster

collapse all in page

    Syntax

    j = createCommunicatingJob(cluster)
    j = createCommunicatingJob(___,Name=Value)
    j = createCommunicatingJob(___,Type=jobType)
    j = createCommunicatingJob(___,Profile=profileName)

    Description

    j = createCommunicatingJob(cluster) creates a communicating job object for the identified cluster.

    example

    j = createCommunicatingJob(___,Name=Value) also specifies communicating job object properties using one or more name-value arguments.

    For a list of supported object properties, see parallel.Job. In most cases, the values you specify override the values in the cluster profile. If you specify AttachedFiles or AdditionalPaths, the software combines the values with the values in the applicable profile. If you specify an invalid property name or value, the software does not create an object.

    j = createCommunicatingJob(___,Type=jobType) specifies the communicating job type as pool or spmd. A pool job runs the specified task function with an available parallel pool. An spmd job runs the specified task function simultaneously on all workers, and you can use spmd* functions for communication between workers.

    j = createCommunicatingJob(___,Profile=profileName) creates a communicating job object with the property values corresponding to the profile profileName. If you do not specify a profile, the software applies the Profile property of the cluster object cluster.

    Examples

    collapse all

    Open Live Script

    This example shows how to create and submit a pool type communicating job.

    Create a communicating job object on the default cluster.

    myCluster = parcluster;
j = createCommunicatingJob(myCluster,Type="pool");

    Add the task to the job, using a function handle to the maxEig function, which uses a parfor-loop to calculate the maximum eigenvalue of random matrices. The function is defined at the end of this example. The maxEig function requires a pool type communicating job to execute the statements in the parfor-loop.

    createTask(j,@maxEig,1,{100});

    Set the number of workers required for parallel execution using the NumWorkersRange job property.

    j.NumWorkersRange = [5 10];

    Run the job.

    submit(j);

    Wait for the job to finish and retrieve its results.

    wait(j)
out = fetchOutputs(j)
    out = 1×1 cell array
    {[2.5248e+03]}

    Delete the job from the cluster.

    delete(j);

    Supporting Function

    The maxEig function uses a parfor-loop to calculate the maximum eigenvalue of randomly generated matrices of increasing sizes. 

    function result = maxEig(N)
    result = 0;
    parfor ii=1:N
        result = result + max(eig(rand(ii)));
    end
end

    Input Arguments

    collapse all

    Cluster, specified as a parallel.Cluster object that represents cluster computing resources. To create the object, use the parcluster function.

    Example: parcluster;

    Data Types: parallel.Cluster

    Communicating job type, specified as one of these options:

    • "pool" — Run the specified task function with a parallel pool. The parallel pool executes the body of parallel functions such as parfor and spmd that are inside the task function.

      You can specify the number of workers to make into a parallel pool by setting the value of the NumWorkersRange as either:

      • A nonnegative integer.

      • A 2-element vector of nonnegative integers, which is interpreted as a range. The size of the resulting parallel pool is as large as possible in the range requested.

      One worker from the parallel pool runs the task function. So, for a pool type job on a pool of N workers, only N—1 workers execute the parfor and spmd code in the task function.

      createCommunicatingJob supports pools with up to 2000 workers. (since R2024a)

    • "spmd" — Run the specified task function simultaneously on all workers. You can use communication functions such as spmdSend and spmdReceive to communicate between workers.

    Data Types: char | string

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

    Example: "Processes" applies the property values specified in the Processes profile to the job.

    Data Types: char | string

    Output Arguments

    collapse all

    Job, returned as a parallel.Job object.

    Data Types: parallel.Job

    Tips

    • To develop and test your code, you can run batch job on a local cluster on your client machine. If you close your MATLAB® session, any batch jobs using the local cluster also stop immediately.

    • When you offload work to a remote cluster, you can close the MATLAB client session while the job is processing and retrieve information from a batch job later or in a new client session.

    • When you offload computations to workers, any files that the client needs for computations must also be available on workers. By default, the client attempts to detect and attach these files. To turn off automatic detection, set the AutoAttachFiles property to false. If the software cannot find all the files, or if sending files from client to worker is slow, use one of these options.

      • If the files are in a folder that is not accessible on the workers, set the AttachedFiles property. The cluster copies each file you specify from the client to the workers.

      • If the files are in a folder that is accessible on the workers, you can set the AdditionalPaths property instead. Use the AdditionalPaths property to add paths to the MATLAB search path for each worker and avoid copying files unnecessarily from the client to the workers.

    Version History

    Introduced in R2012a

    expand all

    See Also

    | | | | |

    Topics