Main Content

parallel.pool.Constant

Build and use constant from data or function handle

expand all in page

    Description

    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.

    Creation

    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.

    Syntax

    C = parallel.pool.Constant(X)
    C = parallel.pool.Constant(FH)
    C = parallel.pool.Constant(FH,cleanupFH)
    C = parallel.pool.Constant(COMP)

    Description

    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.

    example

    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.

    example

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

    example

    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.

    example

    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

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

    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.

    spmd
   disp(fopen(C.Value));
end
    Worker 1: 
  C:\myTemporaryFiles\tpb2d60042_d684_4705_b084_63496d07b936
Worker 2: 
  C:\myTemporaryFiles\tpc6bef84f_bebe_44fc_acb2_ddd2fcba5026
Worker 3: 
  C:\myTemporaryFiles\tpf6775778_b06a_46ba_b502_27e2c253c66f
Worker 4: 
  C:\myTemporaryFiles\tp4dc6e57a_6b65_437a_8eb7_82877403eee3
Worker 5: 
  C:\myTemporaryFiles\tpd0e279ac_a141_49f0_a0b6_90c4cad137a4
Worker 6: 
  C:\myTemporaryFiles\tpf02acaad_60a5_441a_b1a1_46e4c66f33a1

    Write data to the file on each worker.

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

    Clear C to close the temporary files.

    clear C;
    Open Live Script

    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.

    spmd
  if spmdIndex == 1
    x = spmdBroadcast(1,rand(5000));
  else
    x = spmdBroadcast(1);
  end
end
    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));
end
s
    s = 1×10
103 ×

    2.5110    2.5256    2.5060    2.4909    2.5078    2.5187    2.4791    2.4842    2.4926    2.4903

    Tips

    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

    See Also

    | | | | | | |