Main Content


Build and use constant from data or function handle


    Use a Constant object to avoid unnecessarily copying data multiple times from your current MATLAB® session to workers in a parallel pool. You can build a Constant object once on a client and transfer the constant to the workers once. Access the Constant in multiple parfor-loops, spmd blocks, or parfeval calls. The value you access in a Constant object is constant. You can share your parallel code that uses Constant objects with MATLAB users who do not have Parallel Computing Toolbox™. For more information, see parallel.pool.Constant.


    Use parallel.pool.Constant to create a Constant object from an array, a function handle, or a composite object. Use the Value property to access underlying data.



    C = parallel.pool.Constant(X) copies the array X to each worker and returns a Constant object.

    Each worker can access the array X within a parallel language construct (parfor, spmd, parfeval) using the Value property to read the data.


    C = parallel.pool.Constant(FH) evaluates the function handle FH on each worker and stores the results in the Constant object C. Use the Value property to access the result from running FH() with one output.

    Use this syntax to create and use any handle-type resources on a parallel pool, such as file handles and database connections. If you want to evaluate a function on each worker to set up workers before computations, use parfevalOnAll instead.


    C = parallel.pool.Constant(FH,cleanupFH) evaluates cleanupFH(C.Value) on each worker when C is cleared.


    C = parallel.pool.Constant(COMP) stores the values in the entries of the Composite object COMP in the Constant object C on each worker.

    Use this syntax when you want to construct data only on the workers, such as when the data is too large to conveniently fit in the client, or when you load the data from a file that only the workers can access. Access the values using the Value property.

    Input Arguments

    expand all

    Input data, specified as any MATLAB variable that can be saved and loaded.

    Function handle for the build function, specified as a function handle.

    MATLAB evaluates the build function to get the Value property of the Constant object. The function must take no input arguments and must return one output argument.

    • When you read the Value property for the first time in your MATLAB session or on a parallel pool worker, MATLAB stores the result from running fcn() in that environment as the Value property.

    • The function is run only once in your MATLAB session or on a parallel pool worker. When you read the Value property after the first time, you read the stored result.

    • If you read the Value property on a different parallel pool worker, MATLAB returns the result from running fcn() on that worker.

    Example: @() fopen(tempname(pwd),'wt')

    Function handle for the cleanup function, specified as a function handle. The function must take one input argument, the Value property of the Constant object.

    MATLAB runs the cleanup function when C is cleared. The Constant object C is cleared when you:

    • Create C in a function and do not return C from that function.

    • Clear the Constant object from your workspace.

    Example: @fclose

    Composite object to build Constant object, specified as a Composite object.

    The COMP object must have a defined value on every worker otherwise you will receive an error.

    Example: spmd COMP = rand(3); end; C


    expand all

    Independent copy of underlying data or handle-type resource, specified as any MATLAB variable that can be saved and loaded or a handle variable.

    Use the Value property of a Constant to access underlying data or handle variable.


    collapse all

    Create a numeric Constant from an array on the client, and use it in multiple parfor-loops on the same pool.

    Create some large data on the client, then build a Constant object, C transferring the data to the pool only once.

    data = rand(1000);
    C = parallel.pool.Constant(data);

    Run multiple parfor-loops accessing the data. For efficiency, preallocate the results array.

    x = eye(5);
    for ii = 1:5
        parfor jj = 1:5
            x(ii,jj) = C.Value(ii,jj);
    x = 5×5
        0.0016    0.5273    0.3794    0.9148    0.2620
        0.1965    0.8118    0.7953    0.5239    0.4186
        0.3482    0.5745    0.6334    0.1987    0.5588
        0.2405    0.6587    0.4238    0.0736    0.6463
        0.8566    0.5241    0.0332    0.7331    0.9080

    Create a Constant object with a function handle and a cleanup function.

    Use parallel.pool.Constant and tempname to create a temporary file on each worker. When you pass the fclose function as the cleanup function handle, the file is automatically closed when C is cleared.

    C = parallel.pool.Constant(@() fopen(tempname(pwd),'wt'),@fclose);

    Display the temporary filenames.

    Worker 1: 
    Worker 2: 
    Worker 3: 
    Worker 4: 
    Worker 5: 
    Worker 6: 

    Write data to the file on each worker.

    parfor idx = 1:1000
        fprintf(C.Value,'Iteration: %d\n',idx);

    Clear C to close the temporary files.

    clear C;   

    Build Constant object from Composite objects on pool workers inside an spmd block.

    Create a Composite object by using spmdBroadcast to send some large data to all workers in an spmd block.

      if spmdIndex == 1
        x = spmdBroadcast(1,rand(5000));
        x = spmdBroadcast(1);
    Starting parallel pool (parpool) using the 'Processes' profile ...
    Connected to parallel pool with 6 workers.

    Build a Constant object with the Composite object and use it in a parfor-loop.

    xc = parallel.pool.Constant(x);
    parfor idx = 1:10
      s(idx) = sum(xc.Value(:,idx));
    s = 1×10
    103 ×
        2.5110    2.5256    2.5060    2.4909    2.5078    2.5187    2.4791    2.4842    2.4926    2.4903


    You must use the parallel.pool.Constant function in the MATLAB client session.

    You can use a Constant object with an already running parallel pool or subsequent parallel pools.

    Extended Capabilities

    Version History

    Introduced in R2015b

    expand all