Progress Tracking

_|

What is a ProgressListener?

A ProgressListener is a thread-safe mechanism that tracks long-running or asynchronous operations in the Magic Lane SDK. It provides structured notifications for events such as:

• Task start
• Progress updates
• Status changes
• Completion

Why Use a Progress Listener?

• To monitor background operations (like loading, network calls, computations).
• To receive updates in real time via well-defined callback functions.
• To ensure thread-safe and delayed execution.

ProgressListener Methods

Method	Description	Triggered When
notifyStart(bool hasProgress)	Marks the beginning of an operation	At operation start (NotifyStart)
notifyProgress(int percent)	Reports progress in % (0–100)	During operation
notifyStatusChanged(int status)	Notifies about internal status transitions	Optional, mid-operation
notifyComplete(int reason, String hint)	Indicates the operation has completed, along with a reason and optional message	At end (NotifyComplete), exactly once

notifyStart(bool hasProgress)

• Purpose: Notifies that the operation has started.
• Parameter: hasProgress indicates whether the operation will report progress updates (true) or not (false).
• Usage: Called at the beginning of an operation. It's a mandatory call to signal that an operation is in progress.

notifyComplete(int reason, String hint)

• Purpose: Notifies that the operation has finished.

• Parameters:

  • reason: An integer indicating the reason or status of completion (e.g., success, failure).
  • hint: Optional descriptive information about the result.

• Usage: Called when the operation finishes. It may trigger cleanup, UI updates, or further logic depending on the outcome.

Example Usage

gem::vrp::Service service;
ProgressListener listener;

int res = service.addCustomer(&listener, customer);

WAIT_UNTIL(std::bind(&ProgressListener::IsFinished, &listener), 5000);

if (listener.IsFinished() && listener.GetError() == gem::KNoError && res == gem::KNoError) {
    std::cout << "Customer added successfully." << std::endl;
}

Behind the scenes:

• NotifyStart(...) is called at the beginning of addCustomer.
• Periodic NotifyProgress(...) calls are made if enabled.
• NotifyComplete(...) is called when finished.

WAIT_UNTIL

What It Does

The WAIT_UNTIL macro repeatedly evaluates a condition (predicate function) until it returns true or a specified timeout (in milliseconds) is reached.

note

WAIT_UNTIL is intended only for testing purposes. It is commonly used in asynchronous workflows to wait for operations (like network calls or background tasks) to complete during tests.

Behavior

1. Records the current time as a starting reference.
2. Enters a loop where it:
   • Calls the predicate function.
   • If the result is true, exits immediately and returns true.
   • If the result is false:
     • Advances an internal timer (m_pAPITimer->Tick()).
     • Sleeps for a short interval (based on the timer period).
     • Checks if the elapsed time has exceeded the timeout.
3. If the condition is not satisfied within the timeout, it returns false.