Main Content

parallel.pool.Constant

Copy or create data only once on workers in parallel pool

Since R2021b

expand all in page

    Description

    Create a Constant object to avoid unnecessarily copying data multiple times from your current MATLAB® session to workers in a parallel pool or background pool. The value you access in a Constant object is constant.

    • If you have Parallel Computing Toolbox™, use a Constant object to avoid unnecessarily copying data to workers in a parallel pool. For more information, see parallel.pool.Constant (Parallel Computing Toolbox).

    • If you do not have Parallel Computing Toolbox, you can still use Constant objects in the background pool. (since R2023a)

    • If you do not have a parallel pool and do not want to use the background pool, you can still use Constant objects. The Constant is only created in your current MATLAB session. Use Constant when you run portable parallel code designed to work with or without Parallel Computing Toolbox.

    For more information about running parallel code without Parallel Computing Toolbox, see Run Parallel Language in MATLAB.

    Creation

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

    Syntax

    C = parallel.pool.Constant(X)
    C = parallel.pool.Constant(fcn)
    C = parallel.pool.Constant(fcn,cleanupFcn)

    Description

    C = parallel.pool.Constant(X) uses the array X to create a Constant. Use the Value property to read the data.

    example

    C = parallel.pool.Constant(fcn) uses the function handle fcn to create a Constant object C. Use the Value property to get the result from running fcn() with one output.

    Note

    Use this function handle syntax to create a Constant object when you want to have the same variable name for a handle-type resource in your current MATLAB session and on a parallel pool. For example, use the function handle syntax to set up a database connection both in your current MATLAB and on a parallel pool. If you want to evaluate a function on each worker to set up workers before computations, use parfevalOnAll (Parallel Computing Toolbox) instead.

    C = parallel.pool.Constant(fcn,cleanupFcn) runs cleanupFcn(C.Value) when C is cleared.

    Input Arguments

    expand all

    Input data, specified as any MATLAB variable that can be saved and loaded and is supported on a thread-worker. To find out which functions have built-in thread support, see Check Thread Supported Functions.

    Build function, specified as a function handle.

    MATLAB uses the build function to initialize 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 returns the result from running fcn() in that environment.

    • When you read the Value property in your MATLAB session, MATLAB returns the result from running fcn() in your MATLAB session. The first time you read the Value property, the result is stored.

      The function is run only once in your MATLAB session. When you read the Value property after the first time, you read the stored result.

    • When you read the Value property for the first time on a parallel pool worker, MATLAB returns the result from running fcn() on that worker.

      When you read the Value property for the first time on the worker, the result is stored as the Value property. The function is run only once on that 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')

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

    The cleanup function is run 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

    Properties

    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.

    Examples

    collapse all

    Open Live Script

    Create a numeric Constant object and use it in multiple parfeval calls in the backgroundPool.

    Create some large data on the client then build a Constant object to transfer the data to the backgroundPool. 

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

    Use the Constant object to run multiple parfeval calls that access the data in a for-loop and collect the results as they become available. For efficiency, preallocate an array of future objects.

    f(1:10) = parallel.FevalFuture;
for idx = 1:10
     f(idx) = parfeval(backgroundPool,@(c,idx) sum(c.Value(:,idx)),1,c,idx);
end

    Retrieve the individual future outputs as they become available using fetchNext.

    results = zeros(1,10);
for idx = 1:10
    [completedIdx,value] = fetchNext(f);
    results(completedIdx) = value;
    fprintf('Got result with index: %d.\n', completedIdx)
end
    Got result with index: 1.
Got result with index: 2.
Got result with index: 3.
Got result with index: 4.
Got result with index: 5.
Got result with index: 6.
Got result with index: 7.
Got result with index: 8.
Got result with index: 9.
Got result with index: 10.

    results
    results = 1×10

  489.1532  510.2455  486.3741  500.4640  501.6097  490.1254  511.7055  494.8977  502.6807  478.7956


    clear c

    Extended Capabilities

    Version History

    Introduced in R2021b

    expand all

    See Also

    | (Parallel Computing Toolbox) | (Parallel Computing Toolbox) | (Parallel Computing Toolbox) |