Constant - Copy or create data only once on workers in parallel pool - MATLAB (original) (raw)

Copy or create data only once on workers in parallel pool

Since R2021b

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

Description

`C` = parallel.pool.Constant([X](#mw%5F4027162b-38fd-42c4-ab18-9d0b3e592c11)) uses the array X to create a Constant. Use theValue property to read the data.

example

`C` = parallel.pool.Constant([fcn](#mw%5F74185d27-b772-44d3-8bfe-00c1727d5695)) 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](#mw%5F74185d27-b772-44d3-8bfe-00c1727d5695),[cleanupFcn](#mw%5F532a540a-a24f-44df-a7a1-ca266eee2a99)) runs cleanupFcn(C.Value) when C is cleared.

Input Arguments

expand all

X — Input data

MATLAB variable

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.

fcn — Build function

function handle

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

cleanupFcn — Cleanup function

function handle

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. TheConstant object C is cleared when you:

• Create C in a function and do not returnC from that function.
• Clear the Constant object from your workspace.

Example: @fclose

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

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 = 1×10

489.1532 510.2455 486.3741 500.4640 501.6097 490.1254 511.7055 494.8977 502.6807 478.7956

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 R2021b

expand all

R2023a: Use Constant objects in background

You can now use Constant objects in the backgroundPool.