Proposed draft for the thumbnail D-Bus specification

[Rob Taylor]

Philip Van Hoof wrote:
> Hi there whoever is interested in thumbnailing!
> 
> This is the location to the draft:
> 
> http://live.gnome.org/ThumbnailerSpec
> 
> This is the Subversion repository to a prototype implementation:
> 
> https://stage.maemo.org/svn/maemo/projects/haf/branches/hildon-thumbnail/daemonize/daemon/
> 
> It's somewhat untested and unfinished and at the same time tested (it's
> a prototype at this moment).
> 
> I'm very interested in corrections, reviews, spelling fixes,
> concerns, ..

I've tidied up the page a bit and clarified some of the English..

After some discussion with Philip, we've also added a
handle_to_unqueue argument to the Queue method call.

This should make the API easier to use as an application need only ever 
care about one handle at a time. It should also cut down the number of 
bus transactions in the common case of scrolling a window.

Consider the sequence of user actions:
   open window -> scroll -> scroll -> scroll -> close

Previously, this would have required behaviour along the lines of

  queue->queue->queue->queue->unqueue->unqueue->unqueue->unqueue

or

  queue->unqueue->queue->unqueue->queue->unqueue->queue->unqueue

With the addition of this feature, a client need only:

  queue->queue->queue->queue->unqueue

(each queue in the above example is a queue of the thumbnails that are 
now required for the scrolled window)

I've just noticed a slightly difficult race condition when calling this 
api asynchronously (which existing in a different form previously): When 
a new queue message has been sent, the window closes and then the queue 
return message returns.

In this case the application would need to keep a flag that a queue has 
been requested which is cleared when the async call returns. If the 
window is closed when a queue has not yet returned it should wait to 
emit the unqueue until the Queue call has returned (i.e in the async 
callback).

In without this addition, there'd still be similar logic required for 
queue requests still in progress when a window closes (i.e note that the 
window has closed and call unqueue when the async call to Queue returns. 
But it is a little less fiddly as you'd still call the Unqueue as normal.

Of course, as the spec strongly recommends that the queue is LIFO, it 
should be relatively harmless if you fail to unqueue a queued action in 
rare circumstances.

Thoughts, opinions?
Rob

> 
> Features of the draft:
> 
> * Dependency on the Thumbnail-spec (this is definitely a feature, yes.
>   Let's start to agree on a common thumbnail storage once and for all
>   instead of all inventing our own incompatible thumbnail caches)
> 
> * Queuing and indeed unqueuing requests. This makes it possible to let
>   the daemon forget about requests that got requested by accident (the
>   use-case being the window of a file manager closing before the
>   thumbnailing of items finished) (see lower for canceling)
> 
> * Possibility for the daemon to send early results back for items that
>   it could finish sooner than other items. This is useful for already
>   cached thumbnails.
> 
> * Possibility for third party vendors to provide a closed source, closed
>   or patented format thumbnailer by registering support for a MIME type
>   to a manager interface that is required to be implemented by the
>   thumbnailer service. Anti-patent feelings are irrelevant for this
>   this specification: I don't like patented formats too, but that averse
>   is irrelevant here - let's just make it possible and let us make
>   others decide for themselves, we are not the anti-patent police -
> 
>   Generic thumbnailer: org.freedesktop.manager.Register
>   Specialized thumbnailers: org.freedesktop.Create
> 
> * Possibility to queue a lot of items without having to send a lot of
>   DBus messages. Possibility for the daemon to reply `Ready` signals in
>   groups too (for the same reason).
> 
> * Limited error reporting (I don't think file-managers are going to do a
>   lot with errors. But if necessary we can improve error reporting to be
>   topnotch)
> 
> * Limited status reporting. You receive signals when a queued task is
>   started and when it's finished. You receive signals when individual
>   items are finished.
> 
> * Intelligent thumbnail handling on Move, Delete and Copy. This allows a
>   file manager to inform the thumbnailer about Moves, Deletes and
>   Copies. Polling to keep the thumbnail cache correct is not implied by
>   this specification (and therefore not required, but permitted).
> 
> Recommended by the specification
> 
> * Asynchronous LIFO handling of the queue (strongly recommended)
> 
> Not supported:
> 
> * Canceling of activated requests. This is too hard to implement.
>   Functions like pthread_cancel are a no-option (leaks memory) and
>   starting and killing processes is not something I want to require by
>   the specification. The only viable option would be to adapt all
>   thumbnail algorithms to have meaningful cancel points. This is not
>   something I want to require from the specification.
> 
>   I also looked at the current thumbnailing code of a few filemanagers.
> 
>   Although Nautilus's private library has a load_image_cancel method, it
>   doesn't seem to be called (which makes me wonder why it was never
>   removed from nautilus-thumbnail.c)!
> 
>   Nautilus's remove_from_queue and remove_all_from_queue are however
>   used by Nautilus itself. Therefore is this functionality available in
>   the D-Bus API.
> 
> * Topnotch status reporting. This is too difficult for implementers of a
>   daemon to require in the specification. Just like canceling would it
>   require rewriting a lot of thumbnail algorithms.
> 
> 
> Notes
> 
> Note that the not supported features don't mean that in future it wont
> ever be added to a 2.0 version of this specification or that in a custom
> DBus namespace a thumbnailer can't provide this functionality.
> 
> 


-- 
Rob Taylor, Codethink Ltd. - http://codethink.co.uk