parallel.pool.ActivityMonitor

Parallel pool activity monitor

Since R2025a

expand all in page

    Description

    Use ActivityMonitor to monitor and collect data on worker activity in a parallel pool.

    Monitoring data includes:

    • The type of parallel construct, such as parfor, parfeval, and spmd.

    • The amount of data (in bytes) the client and workers send and receive.

    • The time each worker spends processing their portion of the parallel code.

    You can retrieve the monitoring results using the results function and view the monitoring data in the Pool Dashboard.

    Creation

    Syntax

    monitor = parallel.pool.ActivityMonitor
    monitor = parallel.pool.ActivityMonitor(pool)
    monitor = parallel.pool.ActivityMonitor(___,Start=start)

    Description

    monitor = parallel.pool.ActivityMonitor creates an ActivityMonitor object and starts collecting activity monitoring data on the current parallel pool. If no parallel pool exists, parallel.pool.ActivityMonitor starts a new parallel pool using the default profile, unless you disable automatic pool creation in your parallel settings.

    To save monitoring results, use the results function. To stop collecting and save monitoring results, use the stop function.

    example

    monitor = parallel.pool.ActivityMonitor(pool) starts collecting activity monitoring data on the parallel pool specified by pool.

    example

    monitor = parallel.pool.ActivityMonitor(___,Start=start) specifies whether the ActivityMonitor object starts collecting pool monitoring data immediately after creation.

    example

    Input Arguments

    expand all

    Parallel pool, specified as a ProcessPool, ClusterPool, ThreadPool, or BackgroundPool object.

    You can use an interactive or batch parallel pool.

    Before R2026a: ThreadPool or BackgroundPool objects are not supported.

    Example: parpool("Processes");

    Example: batch(...,Pool=4);

    Collect pool monitoring data immediately after creation, specified as a logical or numeric true (1) or false (0).

    • true — Creates an ActivityMonitor object that immediately starts collecting activity monitoring data.

    • false — Creates an ActivityMonitor object but does not start collecting activity monitoring data. To start collecting monitoring data, use the start object function.

    Data Types: logical

    Output Arguments

    expand all

    Pool activity monitor, returned as an ActivityMonitor object.

    Object Functions

    isRunningDetermine whether pool activity monitor is running
    resultsRetrieve results from parallel pool activity monitor
    stopStop monitoring parallel pool activity
    startStart collecting parallel pool activity monitoring data

    Examples

    collapse all

    Open Live Script

    Create an ActivityMonitor object to start collecting pool monitoring data. With default settings, parallel.pool.ActivityMonitor automatically starts an interactive parallel pool using the default profile if one does not exist.

    monitor = parallel.pool.ActivityMonitor;
    Starting parallel pool (parpool) using the 'Processes' profile ...
Connected to parallel pool with 6 workers.

    Run a parfor-loop to generate random numbers and store them in an array.

    data = zeros(1,100);
parfor idx = 1:100
    data(idx) = rand;
end

    Stop the activity monitor and retrieve the results collected during the parfor execution.

    monitorResults = stop(monitor);

    Create a parallel pool using the cluster profile, MyCluster.

    pool = parpool("MyCluster");

    Create an ActivityMonitor object to collect monitoring data for the pool but do not start collecting data immediately.

    monitor = parallel.pool.ActivityMonitor(pool,Start=false);
    Open Live Script

    Collect activity monitoring data on a batch pool job using an ActivityMonitor object.

    Write a function that creates an ActivityMonitor object to collect monitoring data, executes parallel tasks, and collects pool monitoring results.

    function monitorResults = myParallelCode

monitor = parallel.pool.ActivityMonitor;

f(1:100) = parallel.FevalFuture;
for idx = 1:100
    f(idx) = parfeval(@(n) real(eig(randn(n))),1,5e2); 
end
maxFuture = afterEach(f,@max,1);
wait(maxFuture);

monitorResults = stop(monitor);
end

    Run the myParallelCode function as a batch pool job using the myCluster profile and wait for the batch job to complete.

    j = batch(@myParallelCode,1,Pool=4,Profile="myCluster");
wait(j);

    Fetch the monitoring results from the completed batch job.

    out = fetchOutputs(j);
monitoringResults = out{1};

    Limitations

    • Before R2026a: ActivityMonitor is not supported on parallel pools of thread workers.

    • ActivityMonitor does not collect information about data transfers when you monitor activity on a parallel pool of thread workers.

    • ThreadPool objects created using parpool('Threads') and the BackgroundPool are both thread-based pools that use the same resources. It is possible that activity on one pool may block activity on the other. If you use both pools at the same time and monitor activity on a ThreadPool, the ActivityMonitor collects data only for the workers the ThreadPool uses. When you view the pool monitoring data in the Pool Dashboard, the Timeline graph indicates when workers perform work for the other pool in grey and labels the other pool type in the legend.

    Alternative Functionality

    Tool

    You can use the Pool Dashboard to collect and view pool monitoring data on an interactive parallel pool.

    Version History

    Introduced in R2025a

    expand all

    See Also

    Functions

    Objects

    Tools