GNOME Bugzilla – Bug 623635
[annotation] Add begin/finish annotations for GAsyncResult
Last modified: 2018-02-08 11:55:46 UTC
Some languages (like Vala) support native syntax for asynchronous functions. Vala's GLib/C parser has a heuristic that treats pairs of functions with signatures void $(foo)_async (..., GAsyncResultCallback cb, ...); $(type) $(foo)_finish (..., GAsyncResult *res, ...); as a native async function returning type $(type). In order for Vala's (and other languages') GIR parser to generate the same binding, without having to hard-code this heuristic, g-ir-scanner/compiler will need to implement it and adjust GIR output accordingly.
[Mass-moving gobject-introspection tickets to its own Bugzilla product - see bug 708029. Mass-filter your bugmail for this message: introspection20150207 ]
Future versions of Javascript will gain native syntax for this as well, I would expect that to land in GNOME 3.26.
Rust is also interested in this, so I think we have critical mass for a new annotation, and possibly some heuristic.
As a heuristic, this should work for the cases that I saw so far: If there is a xxx_finish() function with a GAsyncResult parameter, check a) Is there a xxx_async() function with a GAsyncResultCallback parameter, or b) Is there a xxx() function with a GAsyncResultCallback parameter b) is the case for various GDBus functions where the sync variant is called xxx_sync() instead. One might also want to annotate which function is the sync variant, if any.
Let's start the bikeshed. We should use a function-level annotation, e.g. /** * 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 * * ... */ This also works for functions that are asynchronous but have no '_async' modifier (e.g. GDBus): /** * foo_bar_collect: (async-finish foo_bar_collect_finish): * ... */ These would be translated into the GIR as an attribute to the callable elements — function, method, virtual-method, e.g. attribute async-finish { xsd:string }? The heuristics for automatically detecting this in the scanner would be: - the callable has a GAsyncResultCallback argument - if the callable ends with '_async', remove that token - check if function_name + '_finish' exists in the same namespace - check if function_name + '_finish' has a GAsyncResult argument This should keep the false positives to zero.
I like the color of your bikeshed. Maybe in addition having a way of linking the sync version of a function to the async one, and the other way around, would be useful. But I can only think of it being useful for documentation purposes right now.
+1 Here's Vala's heuristic: https://github.com/GNOME/vala/blob/dd2d6c6e37a884a149e5a9e2481cb84266c08bb0/vala/valagirparser.vala#L782 Looks like exactly the same.
I found this function: https://developer.gnome.org/gio/unstable/GFile.html#g-file-replace-contents-bytes-async That has a `_finish` method that requires an annotation because the `_finish` method has a different prefix (no `_bytes`).
-- GitLab Migration Automatic Message -- This bug has been migrated to GNOME's GitLab instance and has been closed from further activity. You can subscribe and participate further through the new bug through this link to our GitLab instance: https://gitlab.gnome.org/GNOME/gobject-introspection/issues/28.