Re: API update proposal: cancellation notification

["Juan A." Suárez Romero <jasuarez igalia com>]

On Mon, 2011-01-24 at 14:28 +0100, Guillaume Emont wrote:
> Hi people!
> 
> We've discussed a bit on IRC that it might be useful for the caller to
> be notified once an operation has been cancelled.
> The rationale is that cancellation is an asynchronous operation, that
> will not be finished (the cancelled operation won't be terminated)
> immediately.
> 
> So, a "quick" poll
> 
> a/ Call the GrlMediaSourceResultCb callback with a special value to
> the remaining parameter (GRL_SOURCE_OP_CANCELLED), that would probably
> be implemented as (guint)-2 (aka G_MAXUINT-1).
> Pros: 
>  - not too intrusive, small enough change for all parts (core,
> plugins, caller)
> Cons: 
>  - makes the semantic of remaining ambivalent
>  - won't work for metadata callbacks that don't have a remaining
> parameter
> 
> b/ Call the operation callback with a GError set to
> GRL_CORE_ERROR_OPERATION_CANCELLED.
> Pros: 
>  - consistent with GIO's GCancellable stuff, such as
> g_file_read_async()
>  - not too intrusive, small changes. If the caller does not care about
> it, it might even be able to treat it with the same code as for
> handling other errors
>  - works for all operations
> Cons:
>  - Cancellation might not be an error stricto sensu, though others
> (GIO at least) do it that way.
> 
> c/ Provide a cancelled signal that takes a callback like cancelled_cb
> (GrlMediaSource *source, guint operation_id, gpointer user_data) (or
> the same with a GrlMetadataSource)

> d/ Take a GCancellable as parameter for the operation calls. These
> already provide a complete API, as well as a "cancelled" signal. For
> consistency, the _cancel() call would be deprecated. If implementing
> this solution, it would be consistent to implement (b) as well.


I think we should keep it as simple as possible. Thus, I would go with
either (a) or (b), as they are the most simplest ones, do not require
any change on the api, and satisfied the requirements we are looking for
(being notified when an operation is cancelled).

(a) only fits in the case of operations returning several results, but
not in the case of operations returning just one value (as metadata()).
So I would go with (b). Also, GIO is doing this way, so the semantic
will not be completely weird for people already used to use glib/gio
(though somewhat it is a bit weird for me using a GError to notify a
cancellation).


	J.A.