PoolWaitbar¶

class core.PoolWaitbar¶

Bases: handle

POOLWAITBAR - Thread-safe progress dialog for parallel loops (parfor / spmd / parfeval).

Uses parallel.pool.DataQueue + afterEach to route increment signals from worker threads back to the client (main) thread, where the uiprogressdlg lives. This makes UI updates safe inside parfor loops without any explicit locking.

MIB3 note: Only uiprogressdlg is supported (the classic figure-based waitbar is not used in MIB3). Always supply either a UIFigure parent handle or an already-open uiprogressdlg handle. For progress shown over the active dataset, pass obj.mibModel.getProgressBarParent() (or obj.getProgressBarParent() inside MibModel methods) as the parent - it returns the document window when undocked, so the bar follows the dataset across monitors, and the main MIB window otherwise.

Requires: Parallel Computing Toolbox (parallel.pool.DataQueue).

Usage:

Basic examples: Example 1 - PoolWaitbar in an additional MIB child window

% Use with a child window controller; parent = obj.view.gui (AppDesigner dialog)
pwb = core.PoolWaitbar(maxValue, 'Please wait...', obj.view.gui, 'waitbar title', true);
for i = 1:maxValue
    % ... process something ...
      if ~isempty(pwb)
          if pwb.getCancelState(); pwb.deletePoolWaitbar(); return; end
          pwb.increment();
      end
end
pwb.deletePoolWaitbar();

Example 2 - PoolWaitbar in a docked panel of MIB

% Parent to the active image document so the bar follows it when undocked
pwb = core.PoolWaitbar(nItems, 'Processing...', obj.mibModel.getProgressBarParent(), 'My Task', true);
for ii = 1:nItems
    % ... process item ...
      if ~isempty(pwb)
          if pwb.getCancelState(); pwb.deletePoolWaitbar(); return; end
          pwb.increment();
      end
end
pwb.deletePoolWaitbar();

Example 3 - Parallel loop with batch cancel polling

% Cancelable parfor with batching (cancel polling between batches only)
pwb = core.PoolWaitbar(n, 'Processing...', obj.view.gui, 'Job', true);
pwb.setIncrement(10);         % update every 10 steps
for batchStart = 1:10:n
    if pwb.getCancelState(); pwb.deletePoolWaitbar(); return; end
    batchEnd = min(batchStart+9, n);
    parfor ii = batchStart:batchEnd
        pwb.increment();
    end
end
pwb.deletePoolWaitbar();

Constructor Summary

PoolWaitbar(N, message, parentOrHandle, WindowName, Cancelable, Indeterminate)¶

POOLWAITBAR - Construct a thread-safe progress dialog for parallel loops.

Syntax:

function obj = PoolWaitbar(N, message, parentOrHandle, WindowName, Cancelable)

Input Arguments:

• N - double, total number of iterations expected

• message - (optional) char, text shown inside the dialog; default ‘Please wait…’

• parentOrHandle - (optional) either:

  • matlab.ui.Figure / matlab.ui.container.internal.AppContainer - parent window; a new uiprogressdlg is created automatically. Prefer obj.mibModel.getProgressBarParent() (or obj.getProgressBarParent() inside MibModel methods) so the bar follows the active dataset window when it is undocked

  • matlab.ui.dialog.ProgressDialog - existing dialog to reuse (its Value is reset to 0 and Message/Title updated)

  • [] - error; a parent is required in MIB3

• WindowName - (optional) char, dialog title; default ‘’

• Cancelable - (optional) logical, add Cancel button; default false. Only used when parentOrHandle is a Figure.

• Indeterminate - (optional) logical, default=false; use the Indeterminate mode

Output Arguments:

• obj - core.PoolWaitbar instance

Usage:

Example 1

pwb = core.PoolWaitbar(200, 'Eroding...', obj.mibModel.getProgressBarParent(), 'Erode');

Example 2 - Reuse an open dialog

% Reuse an open dialog
pwb = core.PoolWaitbar(200, 'Phase 2', existingWb);

Method Summary

delete()¶

DELETE - Destructor: clean up the DataQueue, Listener, and dialog.

Syntax:

function delete(obj)

deletePoolWaitbar(keepDialog)¶

DELETEPOOLWAITBAR - Tear down the PoolWaitbar, optionally keeping the uiprogressdlg.

Syntax:

function deletePoolWaitbar(obj, keepDialog)

Input Arguments:

• keepDialog - (optional) logical; when true the underlying uiprogressdlg is NOT deleted so the caller can continue using it directly. Default false (dialog is deleted).

Output Arguments:

(none)

Usage:

Example 1

pwb.deletePoolWaitbar();% delete everything

Example 2

pwb.deletePoolWaitbar(true);% keep dialog open

getCancelState()¶

GETCANCELSTATE - Return true if the user pressed Cancel in the dialog.

Syntax:

function res = getCancelState(obj)

Only meaningful when the dialog was created with Cancelable = true. Poll this between parfor batches (on the main thread) - do not call it from inside a parfor body.

Input Arguments:

(none)

Output Arguments:

• res - logical, true when Cancel has been requested

Usage:

Example 1

if pwb.getCancelState(); break; end

getCurrentIteration()¶

GETCURRENTITERATION - Return the number of iterations completed so far.

Syntax:

function count = getCurrentIteration(obj)

Input Arguments:

(none)

Output Arguments:

• count - double, current iteration counter

getMaxNumberOfIterations()¶

GETMAXNUMBEROFITERATIONS - Return the total number of expected iterations.

Syntax:

function result = getMaxNumberOfIterations(obj)

Input Arguments:

(none)

Output Arguments:

• result - double, the N value set at construction or updated

getText()¶

GETTEXT - Return the current message string from the uiprogressdlg.

Syntax:

function text = getText(obj)

Input Arguments:

(none)

Output Arguments:

• text - char, current dialog message

getWaitbarHandle()¶

GETWAITBARHANDLE - Return the underlying uiprogressdlg handle.

Syntax:

function wb = getWaitbarHandle(obj)

Use this before calling deletePoolWaitbar(true) to retain a reference to the dialog for subsequent updates.

Input Arguments:

(none)

Output Arguments:

• wb - matlab.ui.dialog.ProgressDialog handle

Usage:

Example 1

wb = pwb.getWaitbarHandle(); pwb.deletePoolWaitbar(true);

increaseMaxNumberOfIterations(N)¶

INCREASEMAXNUMBEROFITERATIONS - Increase the total iteration count by N.

Syntax:

function increaseMaxNumberOfIterations(obj, N)

Input Arguments:

• N - double, amount to add to the current maximum

Output Arguments:

(none)

increment()¶

INCREMENT - Signal one step of progress from any thread (main or worker).

Syntax:

function increment(obj)

This is the only method that is safe to call inside a parfor body. It uses send() on the immutable DataQueue; the actual UI update happens asynchronously on the main thread.

Input Arguments:

(none)

Output Arguments:

(none)

Usage:

Example 1

parfor ii = 1:n; pwb.increment(); end

setCurrentIteration(count)¶

SETCURRENTITERATION - Manually set the completed-iteration counter.

Syntax:

function setCurrentIteration(obj, count)

Useful when restarting progress tracking mid-run or when stitching two sequential phases that share one dialog.

Input Arguments:

• count - double, new value for the internal counter

Output Arguments:

(none)

setIncrement(increment)¶

SETINCREMENT - Set the step size added to Count on each increment() call.

Syntax:

function setIncrement(obj, increment)

Use this when the caller wants to call increment() less frequently (e.g., every 10 iterations to reduce overhead).

Input Arguments:

• increment - double, new step size; default 1

Output Arguments:

(none)

Usage:

Example 1

pwb.setIncrement(10);% advance bar by 10% each call

updateIndeterminateMode(indeterminateMode)¶

UPDATEINDETETRMINATEMODE - update the indeterminate mode of the progress bar

Syntax:

function updateIndeterminateMode(obj) function updateIndeterminateMode(obj, indeterminateMode)

Input Arguments:

• indeterminateMode - logical, indeterminate switch, when true show the progress bar using indeterminate style. Default = true

Output Arguments:

(none)

Usage:

Example 1

pwb.updateIndeterminateMode(true); % enable the indeterminate mode
pwb.updateIndeterminateMode(false); % disable the indeterminate mode

updateMaxNumberOfIterations(N)¶

UPDATEMAXNUMBEROFITERATIONS - Replace the total iteration count with a new value.

Syntax:

function updateMaxNumberOfIterations(obj, N)

Input Arguments:

• N - double, new total number of iterations

Output Arguments:

(none)

updateText(newText)¶

UPDATETEXT - Update the message shown in the uiprogressdlg.

Syntax:

function updateText(obj, newText)

Only safe to call from the main thread (not inside parfor).

Input Arguments:

• newText - char, new message string

Output Arguments:

(none)

Usage:

Example 1

pwb.updateText(sprintf('Processing slice %d/%d', z, zMax));