[Okular-devel] Threaded Generators API

Tobias Koenig tokoe at kde.org
Mon Jan 22 09:59:57 CET 2007


Hi,

over the weekend I made up my mind how to implement a generator API
which allows the generator to execute special tasks (e.g. generating
pixmap, generating textpage, extract font information) as separated
thread, but put as less burden as necessary on the 3rd-party developer.

After several attempts to implement it by extending our current Okular::Document or
Okular::Generator class I came to the conclusion that we have to do a
bigger change in the API.

Asking data from the Generator for a synchronous task differs too much
from asking data for an asynchronous task, so the best solution IMHO
would be to add two new classes Okular::SingleThreadedGenerator and
Okular::MultiThreadedGenerator, which both inherits from Okular::Generator.
(better name suggestions are always welcome ;)).

Both classes provide methods for generating pixmaps, textpages and font
infos, however the differ in the semantic of the functions.

The Okular::SingleThreadedGenerator would have the same API as our
current Okular::Generator and the Okular::MultiThreadedGenerator would
start separated threads for each generation request.

Example:

class SingleThreadedGenerator
{
  public:

    ...
    virtual void generatePixmap( PixmapRequest* request );
    virtual void generateTextPage( Page* );
    ...

  protected:
    void signalRequestDone( PixmapRequest* request );
};

class MultiThreadedGenerator
{
  public:

    void generatePixmap( PixmapRequest* request );
    void generateTextPage( Page* );

  protected:
    virtual QImage createPixmap( PixmapRequest* request );
    virtual TextPage* createTextPage( Page* page );
};

In the MultiThreadedGenerator, the 3rd-party developer has to implement
createPixmap() and createTextPage(). These two methods are called by
generatePixmap()/generateTextPage() (template method pattern).

generatePixmap/TextPage will instanciate a new PixmapGeneratingThread or
TextPageGeneratingThread for every request and execute
createPixmap/createTextPage in the thread's run() method.
The result is passed back out of the thread (the qimage is converted to
an pixmap) and the data are passed further to the Okular::Document.

For the Okular::Document class the differences between the both
generator types should be opaque, because it has to call
generatePixmap/generateTextPage() in both cases.

We just have to change the Document to be aware of the fact that text
extraction can be asnychronous now. But that's something we should have
for the SingleThreadedGenerator as well.

Thoughts:
----------
 * To unify the two interfaces further we could apply the template
   method pattern to SingleThreadedGenerator as well, so the developer
   has to reimplement createPixmap/createTextPage in both cases (to make
   it more consistent)

What do you think about it?

Ciao,
Tobias
-- 
Separate politics from religion and economy!
The Council of the European Union is an undemocratic and illegal institution!
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 189 bytes
Desc: Digital signature
Url : http://mail.kde.org/pipermail/okular-devel/attachments/20070122/db325a19/attachment.pgp 


More information about the Okular-devel mailing list