Proposed draft for the thumbnail D-Bus specification

[Kevin Krammer]

On Tuesday 09 September 2008, Philip Van Hoof wrote:
> On Tue, 2008-09-09 at 13:08 +0200, Kevin Krammer wrote:

> I'm fine with adding amendments that state that cancels might be
> available, but don't have to be available. IF it's clear that it's a
> *might be available* not a *will be available*.
>
> That way it'll be a loose specification (the cancel part), but if it's
> absolutely clear that it's *might be available*, then nobody will expect
> any guarantees. Which is what I want for this one (you do too, so it
> seems).

Yes, an annotation clarifying that might help to avoid misunderstandings, 
though I doubt anyone with a bit of experience will ever assume always 
interruptable processes, at least not if they have every heard of locking or 
atomic operations.

> In the end is a specification a contract. A contract means guarantees.

True and I agree that the behavioral specification for cancel needs to be 
clear enough that the implementation's response time will depend on the 
implementation's capabilities.

> I don't see the point in a specification if nobody is going to implement
> it right anyway.

Well, since some implementations will be done by Free Software developers who 
most of the times strive for technically perfect implementations, I am 
optimistic :)

> As I *know* that a lot of implementers wont even try to get it right.

True, easy-way-out is quite popular.

> So your cancel will be ...
>
> At some point in time, it will cancel.
>
> Okay, then I make a cancel that cancels right after the thumbnail's
> generation *is*  finished. That fulfills your contract, doesn't it?

Yes, it does.

> But will you be happy?

Since the specification does by definition not require a specific 
implementation, I can always look for a better implementation if the 
currently available ones don't make me happy.

> I guarantee you implementers will do this if you specify it in such a
> vague way.

That's ok. Having the possibility of capable implementations is IMHO better 
than to guarantee that none will ever exist.

> > If one delegates processing to a service, cancelling is the method of
> > conveying that you are no longer interested in a result.
>
> But it's possible that `Ready` signals got sent already. And since your
> cancel is vaguely defined as "at some point in time, it'll cancel": why
> shouldn't I just keep sending the `Ready` signals until the generation
> of the thumbnail *is* finished.

My interpretation is that this would violate the specification for "Ready", 
i.e. I would strongly assume that it is not emitted during the operation, 
only when the thumbnail has actually been finished.

Unless of course we annotate Ready to mean "I completed something, could be 
just reading the file".

> In other words: don't implement cancel at all.

True, though a sensible assumption would be that any implementation will be 
able to stop after finishing one uri before starting to work on the next.

> That's completely correct according to your vague spec for cancel.

Not very likely, but yes, it is.

> So what was the point of specifying cancel in the first place then?

Allowing implementors who actually care about resource usage to implement a 
version which provides better response times.

> > I don't think it depends on an implementation detail such as thread-based
> > or process-based to tell a worker to stop at the next checkpoint it
> > reaches. Just because it is technically possible to hard kill a process
> > doesn't mean will ever want to do that since one can easily create stale
> > lock files, SHM semaphores, etc. that way.
>
> Checkpoints are the cancel points that I've been using in previous
> E-mails. All my remarks about cancels points apply to check points too.
>
> Cancel (check) points are, by the way, hard. They require the entire
> outside and inside API of your frameworks to cope.

Yes, of course.
If the API available to you takes a filename and returns an image, the best 
you can do is cancel after each image.
If the API allows to specific a buffer, you can provide a cancel point after 
read.
If the API allows to specify a generic I/O like a stream, you can probably 
cancel at ever read operation.

> Like GCancellable in GIO and GVFS (I don't know what KIO has for this).

Exactly!
Having the cancellation as part of the API gives a hint to implementors that 
they ought to think about cancelling.
Not having it in the API removes any hope of ever getting an implementation 
capable of cancelling.

> Not all thumbnailers can use this.

Yes, but some will.

> > Since there is usually more than one way to implement a thumbnail
> > algorithm, having a spec with cancel capabilities gives hint to
> > developers of such implementations that they should probably think about
> > where to put check points.
>
> That's true.
>
> So for the hint, I'd approve an amendments that hints that a cancel
> might be available.
>
> And, therefore, a high quality thumbnailer implementation would have
> cancels this way.

Exactly!


> So send me proposals for a cancel DBus API ...

<method name="Cancel">
      <arg type="u" name="handle" direction="in" />
</method>

Stops operations on the queue referred to by "handle" as soon as the 
thumbnailer is capable of doing so.
Note: depending on the thumbnailer's capabilities it might have to complete 
the full queue without interruption


Cheers,
Kevin
-- 
Kevin Krammer, KDE developer, xdg-utils developer
KDE user support, developer mentoring
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 189 bytes
Desc: This is a digitally signed message part.
Url : http://lists.freedesktop.org/archives/xdg/attachments/20080913/2a4536c8/attachment.pgp