From dc773ab3f41b0295050b8d11a3307c60f43956bb Mon Sep 17 00:00:00 2001 From: Sebastian Trueg Date: Thu, 30 Oct 2008 09:58:10 +0000 Subject: [PATCH] Major documentation improvement/cleanup/fix svn path=/trunk/KDE/kdebase/workspace/libs/plasma/; revision=877767 --- abstractrunner.h | 64 ++++++++++++++++++++++++++++++++++-------------- querymatch.h | 2 ++ runnercontext.h | 8 +++--- 3 files changed, 53 insertions(+), 21 deletions(-) diff --git a/abstractrunner.h b/abstractrunner.h index bea7952c1..09fcec74f 100644 --- a/abstractrunner.h +++ b/abstractrunner.h @@ -47,10 +47,9 @@ class AbstractRunnerPrivate; * * @short An abstract base class for Plasma Runner plugins. * - * Be aware that runners have to be thread-safe. This is due to - * the fact that each runner is executed in its own thread for - * each new term. Thus, a runner may be executed more than once - * at the same time. + * Be aware that runners have to be thread-safe. This is due to the fact that + * each runner is executed in its own thread for each new term. Thus, a runner + * may be executed more than once at the same time. See match() for details. */ class PLASMA_EXPORT AbstractRunner : public QObject { @@ -79,31 +78,56 @@ class PLASMA_EXPORT AbstractRunner : public QObject /** * This is the main query method. It should trigger creation of - * QueryMatch instances through RunnerContext::addInformationalMatch, - * RunnerContext::addExactMatch, and RunnerContext::addPossibleMatch. + * QueryMatch instances through RunnerContext::addMatch and + * RunnerContext::addMatches. It is called internally by performMatch(). * * If the runner can run precisely the requested term (RunnerContext::query()), - * it should create an exact match (RunnerContext::addExactMatch). + * it should create an exact match by setting the type to RunnerContext::ExactMatch. * The first runner that creates a QueryMatch will be the * default runner. Other runner's matches will be suggested in the - * interface. Non-exact matches should be offered via RunnerContext::addPossibleMatch. + * interface. Non-exact matches should be offered via RunnerContext::PossibleMatch. * - * The match will be activated if the user selects it. + * The match will be activated via run() if the user selects it. * - * If this runner's exact match is selected, it will be passed into - * the run method. - * @see run + * Each runner is executed in its own thread. Whenever the user input changes this + * method is called again. Thus, it needs to be thread-safe. Also, all matches need + * to be reported once this method returns. Asyncroneous runners therefore need + * to make use of a local event loop to wait for all matches. * - * Since each runner is executed in its own thread there is no need - * to return from this method right away, nor to create all matches - * here. + * It is recommended to use local status data in async runners. The simplest way is + * to have a separate class doing all the work like so: + * + * \code + * void MyFancyAsyncRunner::match( RunnerContext& context ) + * { + * QEventLoop loop; + * MyAsyncWorker worker( context ); + * connect( &worker, SIGNAL(finished()), + * &loop, SLOT(quit()) ); + * worker.work(); + * loop.exec(); + * } + * \endcode + * + * Here MyAsyncWorker creates all the matches and calls RunnerContext::addMatch + * in some internal slot. It emits the finished() signal once done which will + * quit the loop and make the match() method return. The local status is kept + * entirely in MyAsyncWorker which makes match() trivially thread-safe. + * + * @caution This method needs to be thread-safe since KRunner will simply + * start a new thread for each new term. + * + * @caution Returning from this method means to end execution of the runner. + * + * @sa run(), RunnerContext::addMatch, RunnerContext::addMatches, QueryMatch */ + // trueg: why is this method not protected? virtual void match(Plasma::RunnerContext &context); /** - * Triggers a call to match. + * Triggers a call to match. This will call match() internally. * - * @arg globalContext the search context used in executing this match. + * @arg context the search context used in executing this match. */ void performMatch(Plasma::RunnerContext &context); @@ -126,8 +150,12 @@ class PLASMA_EXPORT AbstractRunner : public QObject /** * Called whenever an exact or possible match associated with this * runner is triggered. + * + * @param context The context in which the match is triggered, i.e. for which + * the match was created. + * @param match The actual match to run/execute. */ - virtual void run(const Plasma::RunnerContext &context, const Plasma::QueryMatch &action); + virtual void run(const Plasma::RunnerContext &context, const Plasma::QueryMatch &match); /** * The nominal speed of the runner. diff --git a/querymatch.h b/querymatch.h index c738580a0..63a81741f 100644 --- a/querymatch.h +++ b/querymatch.h @@ -136,6 +136,8 @@ class PLASMA_EXPORT QueryMatch * Requests this match to activae using the given context * * @param context the context to use in conjunction with this run + * + * @sa AbstractRunner::run */ void run(const RunnerContext &context) const; diff --git a/runnercontext.h b/runnercontext.h index 3d0937e10..baa2112fd 100644 --- a/runnercontext.h +++ b/runnercontext.h @@ -104,25 +104,27 @@ class PLASMA_EXPORT RunnerContext : public QObject /** * Appends lists of matches to the list of matches. - * The RunnerContext takes over ownership of the matches on successful addition. * * This method is thread safe and causes the matchesChanged() signal to be emitted. * * @return true if matches were added, false if matches were e.g. outdated */ + // trueg: what do we need the term for? It is stored in the context anyway! Plus: matches() does not have a term parameter! + // plus: it is Q_UNUSED bool addMatches(const QString &term, const QList &matches); /** * Appends a match to the existing list of matches. - * The RunnerContext takes over ownership of the match on successful addition. * * If you are going to be adding multiple matches, use addMatches instead. * - * @arg term the search term that this match was generated for + * @arg term the search term that this match was generated for. * @arg match the match to add * * @return true if the match was added, false otherwise. */ + // trueg: what do we need the term for? It is stored in the context anyway! Plus: matches() does not have a term parameter! + // plus: it is Q_UNUSED bool addMatch(const QString &term, const QueryMatch &match); /**