[PATCH-API-DOCU] AbstractRunner documentation

[Sebastian Trüg]

On Tuesday 28 October 2008 00:01:23 Aaron J. Seigo wrote:
> i haven't read through your added docu (i trust you on that =), but did
> take a look at the questions and here are some answers:
>
> +        // trueg: why is this method not protected?
>
> because it can be called by other classes if they don't care to do async
> matching in threads (or external processes, i suppose). at this point we
> could probably make it protected if we wanted to as nothing probably uses
> it.

i see.

> +        // trueg: why having a reference to the context. This is very
> weird when storing it
> +        //        for async operations
>
> you can make copies of the context just fine; it's a non-const reference to
> allow for future features where runners can add their own bits of
> information to the context during processing. maybe we'll take advantage of
> that someday =P

Making copies of the reference is not that trivial since you cannot have an 
uninitialized reference. Thus, you have to always create the object you store 
the reference in in the match method. At least that is how I understand it.
I know that using a pointer would mean that people can delete it but then 
maybe a shared object copy would be cleaner.
Anyway, it is not really important...

> +        // trueg: what do we need the term for? It is stored in the
> context anyway! Plus: matches() does not have a term parameter!
>
> it's needed to match the term with the context's current term. since it's
> threaded the following can happen:
>
> * match is called with term "kon"
> * runner goes off looks up "konsole" and "konqueror"
> * meanwhile the user types 's'
> * the runner tries to register its two matches with term "kon"; the context
> has changed, however (the runner doesn't know that yet!), and so it knows
> it can discard it

Hm, but the term is unused (as in Q_UNUSED) as each runner thread gets its own 
context which is a local copy of the global context.

> iow, it's there to fix race conditions between the user input and runner
> returning matches =)
>
> > Sidenote: is it intended to not support async runners directly?
>
> well, it is what it is. we don't need async runners now that we use
> threads, i guess =)

not really true. The nepomuk search runner for example is async since it uses 
the nepomuk query service which emits dbus signals for new results. Now this 
is really simple to do with a local event loop as I also explain in the 
documentation but could be confusing for unexperienced developers. Again, 
something not really important, especially since now it is in the 
documentation.

Cheers,
Sebastian

-- 
Sebastian Trueg
Sponsored by Mandriva to work on Nepomuk-KDE.

http://nepomuk.kde.org