[Okular-devel] Threaded Generators API

[Albert Astals Cid]

A Dilluns 22 Gener 2007 09:59, Tobias Koenig va escriure:
> 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?

I'm not sure i understand what you want to do.

Would the current pdf generator be a single threaded or a multi threaded one?

Does the multithread mean that it can run more than one thread at once, that 
is, one thread for generating a pixmap and at the same time a thread for 
getting text of a page?

Besides that all things that help making generators simpler is wellcome from 
my side :-)

Albert

>
> Ciao,
> Tobias