Constant - Build and use constant from data or function handle - MATLAB (original) (raw)

Main Content

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 theConstant 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

Description

`C` = parallel.pool.Constant([X](#mw%5F6095cfa7-ab73-456c-aedf-1c59b8fb6fa4)) copies the array X to each worker and returns aConstant 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](#mw%5F2e4ecc68-37ba-4a80-974f-1f5257d0661e)) evaluates the function handle FH on each worker and stores the results in the Constant object C. Use theValue property to access the result from runningFH() 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](#mw%5F2e4ecc68-37ba-4a80-974f-1f5257d0661e),[cleanupFH](#mw%5F73140227-6f01-4c35-9d06-24cd15bf49eb)) evaluates cleanupFH(C.Value) on each worker whenC is cleared.

example

`C` = parallel.pool.Constant([COMP](#mw%5F2e67ec0d-fa51-45e7-b012-2098a96926b0)) stores the values in the entries of the Composite objectCOMP 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

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.

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 theConstant object.

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

Example: @fclose

COMP — Build composite

Composite object

Composite object to build Constant object, specified as aComposite 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

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

collapse all

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.

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

expand all

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.