Ordfoss

OperationContext.h header

#include <ew/core/OperationContext.h>

Namespace ew::core

OperationContext class

class ew::core::OperationContext

The caller's handle on a long-running engine operation: where it reports progress, and where it asks whether to stop.

Both callbacks are OPTIONAL, and that is the point of wrapping them. The engine previously took two bare std::function members, so every use site had to remember a null check – the conversion orchestrator guards if (m_options->progress) at each call and grew its own cancelledNow() helper for the other one. Forgetting either is a crash rather than a missing feature, so the check belongs here, once, instead of at every call site.

THREADING: this type does no threading and imposes none. The engine is synchronous by design and the CLIENT owns the thread (the desktop app runs long work through QtConcurrent::run); the callbacks are therefore invoked on whichever thread is running the operation, and a UI client must marshal to its own thread before touching widgets. Deliberately plain std::function rather than QFuture/QPromise: libs/core must stay free of both a threading and a networking dependency, which is the invariant tools/ci/check-local-only.ps1 enforces.

Members

using ew::core::foundation::OperationContext::ProgressHandler = std::function<void(const ProgressReport&)>

Receives each progress report. Invoked on the thread running the operation.

using ew::core::foundation::OperationContext::CancellationPoll = std::function<bool()>

Answers "should this operation stop?". Polled at the operation's own checkpoints, so cancellation is cooperative: it takes effect at the next checkpoint, not instantly.

ew::core::foundation::OperationContext::OperationContext()=default

Constructs a context that reports nowhere and is never cancelled – the right default for a caller that just wants the operation to run to completion.

ew::core::foundation::OperationContext::OperationContext(ProgressHandler onProgress, CancellationPoll isCancelled)

Constructs a context with either or both callbacks; passing an empty one is fine.

void ew::core::foundation::OperationContext::setProgressHandler(ProgressHandler handler)

Sets (or clears, when empty) the progress handler.

void ew::core::foundation::OperationContext::setCancellationPoll(CancellationPoll poll)

Sets (or clears, when empty) the cancellation poll.

void ew::core::foundation::OperationContext::report(const ProgressReport &report) const

Reports report to the handler, or does nothing when none is set. Always safe to call.

void ew::core::foundation::OperationContext::report(qint64 done, qint64 total, const QString &activity) const

Convenience overload for the common done of total, doing activity call.

bool ew::core::foundation::OperationContext::isCancelled() const

True when the caller has asked the operation to stop. False when no poll is set, so an operation can call this unconditionally at its checkpoints.

bool ew::core::foundation::OperationContext::wantsProgress() const

True when a progress handler is set. For an operation that would do real work purely to build a report – counting files only to say how many there are – and can skip it when nobody is listening. Not needed to call report safely.