On Fri, 2018-02-09 at 10:48 +0000, Philip Withnall wrote:
> On Fri, 2018-02-09 at 07:25 +0000, philip chimento gmail com wrote:
> > The gobject-introspection bugs were migrated from Bugzilla to
> > GitLab
> > today so I got a reminder of everything that I was subscribed to.
> >
> > There are a couple of proposals for annotations I'd like to discuss
> > on the mailing list. I'm not necessarily planning to work on them,
> > but I'd like to get the discussion out of the way so that someone
> > can
> > easily pick them up. Hence this mail and the following ones.
> >
> > Annotation for asynchronous functions: https://gitlab.gnome.org/GNO
> > ME
> > /gobject-introspection/issues/28
> >
> > tl;dr: Add an (async-finish) annotation to the async function, so
> > that bindings can determine the finish function given the async
> > function. This would become an async-finish attribute in the GIR.
> >
> > /**
> > * foo_bar_decide_async: (async-finish foo_bar_decide_finish):
> > * @self: a #FooBar
> > * @blah: a #FooBlah
> > * @cancellable: (nullable): a #GCancellable
> > * @callback: a #GAsyncResultCallback
> > * @data: data to pass to @callback
> > ...
> >
> > Additionally there seems to be consensus around using the same
> > heuristic that Vala currently uses, to determine this information
> > in
> > g-ir-scanner if no async-finish annotation is given.
>
> Yeah, that seems reasonable.
Actually, for consistency with other annotations, I suggest we might
want to call it (finish-func FUNC) rather than (async-finish FUNC).
It’s slightly shorter to type, and has the common ‘-func’ suffix.
> > There are a few functions which would need the annotation anyway,
> > such as g_file_replace_contents_bytes_async() /
> > g_file_replace_contents_finish().
> >
> > Any comments?
>
> I’d be in favour of Sebastian’s additional suggestion that we have a
> (sync-func FUNC) annotation which can be used to link the async and
> sync methods together. That would definitely be useful data to have.
>
> The heuristic to use here would be:
> • If the async method name ends in ‘_async’, the sync method name
> doesn’t have the prefix.
> • If the async method name doesn’t end in ‘_async’, the sync method
> name ends in ‘_sync’.
> • In both cases,
> - the methods must be on the same object,
> - a ‘_finish’ method must be available (either found by heuristic
> or
> by annotation),
> - the sync method must have the same return type as the _finish
> method,
> - the sync and async methods must have the same set of in
> parameters,
> ignoring the source object, GCancellable, GError, GAsyncReadyCallback
> and gpointer user_data (this one may be too hard to test reliably),
> and
> - the sync and finish methods must have the same set of out
> parameters.
>
> Cheers,
> Other Philip
Agreed on all counts.
So, the example would become
/**
* foo_bar_decide_async: (finish-func foo_bar_decide_finish) (sync-func foo_bar_decide):
* @self: a #FooBar
* @blah: a #FooBlah
* @cancellable: (nullable): a #GCancellable
* @callback: a #GAsyncResultCallback
* @data: data to pass to @callback
...
with the understanding that in this example, both annotations would actually be unnecessary since they would be correctly picked up by the heuristics.
For completeness, how about an (async-func) annotation on the sync function? Maybe that should only be an attribute in the GIR, not an annotation, since it can be determined automatically from the sync-func annotation/heuristic?
Note that linking from the finish-func back to the original async function isn't possible, since g_file_replace_contents_finish() is the finish-func for two async operations.
Regards,
Philip C
