time to introduce the ability for runners to decide if they care to that they should return early

svn path=/trunk/KDE/kdelibs/; revision=934729

runnercontext.cpp

@@ -299,6 +299,12 @@ QString RunnerContext::mimeType() const
     return d->mimeType;
 }
 
+bool RunnerContext::isValid()
+{
+    // if our qptr is null, we aren't useful anymore
+    return d->q;
+}
+
 bool RunnerContext::addMatches(const QString &term, const QList<QueryMatch> &matches)
 {
     Q_UNUSED(term)

runnercontext.h

@@ -102,6 +102,25 @@ class PLASMA_EXPORT RunnerContext : public QObject
          */
         QString mimeType() const;
 
+        /**
+         * @returns true if this context is no longer valid and therefore
+         * matching using it should abort. Most useful as an optimization technique
+         * inside of AbstractRunner subclasses in the match method, e.g.:
+         *
+         * while (.. a possibly large iteration) {
+         *     if (!context.isValid()) {
+         *         return;
+         *     }
+         *
+         *     ... some processing ...
+         * }
+         *
+         * While not required to be used within runners, it provies a nice way
+         * to avoid unecessary processing in runners that may run for an extended
+         * period (as measured in 10s of ms) and therefore improve the user experience.
+         */
+        bool isValid();
+
          /**
          * Appends lists of matches to the list of matches.
          *