parallel.pool.Constant

Build and use constant from data or function handle

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.

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

X — Input data

MATLAB variable

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

FH — Build function handle

function handle

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')

cleanupFH — Cleanup function handle

function handle

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

COMP — Build composite

Composite object

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

Value — Underlying data or handle-type resource

MATLAB variable

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

Make Constant from Array in Client

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

Make Constant from Function Handle

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;   

Make Constant from Composite

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

Thread-Based Environment

Run code in the background using MATLAB® backgroundPool or accelerate code with Parallel Computing Toolbox™ ThreadPool.

This function fully supports thread-based environments. For more information, see Run MATLAB Functions in Thread-Based Environment.

Version History

Introduced in R2015b

R2023b: parallel.pool.Constant with no arguments now returns invalid Constant object

When you call the parallel.pool.Constant function without input arguments, it initializes a Constant object in an invalid state. Before R2023b, calling the parallel.pool.Constant function without input arguments errors.

You can use parallel.pool.Constant with no arguments to assign invalid Constant objects to array elements. When you create or grow an array of Constant objects without assigning values to each element, any new elements of the array contain invalid Constant elements.

R2023a: Constant objects no longer automatically transferred to workers

MATLAB will no longer automatically transfer Constant objects from your current MATLAB session to workers in a parallel pool. MATLAB will send the Constant object to workers only if the object is required to execute your code.

In previous releases, MATLAB automatically sent the Constant object to the workers in the parallel when the pool was started.

You do not need to make any changes to your code.