After an evaluation, GNOME has moved from Bugzilla to GitLab. Learn more about GitLab.
No new issues can be reported in GNOME Bugzilla anymore.
To report an issue in a GNOME project, go to GNOME GitLab.
Do not go to GNOME Gitlab for: Bluefish, Doxygen, GnuCash, GStreamer, java-gnome, LDTP, NetworkManager, Tomboy.
Bug 623635 - [annotation] Add begin/finish annotations for GAsyncResult
[annotation] Add begin/finish annotations for GAsyncResult
Status: RESOLVED OBSOLETE
Product: gobject-introspection
Classification: Platform
Component: general
2.25.x
Other Linux
: Normal enhancement
: ---
Assigned To: gobject-introspection Maintainer(s)
gobject-introspection Maintainer(s)
Depends on:
Blocks:
 
 
Reported: 2010-07-05 21:28 UTC by Travis Reitter
Modified: 2018-02-08 11:55 UTC
See Also:
GNOME target: ---
GNOME version: ---



Description Travis Reitter 2010-07-05 21:28:17 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.
Comment 1 André Klapper 2015-02-07 17:21:49 UTC
[Mass-moving gobject-introspection tickets to its own Bugzilla product - see bug 708029. Mass-filter your bugmail for this message: introspection20150207 ]
Comment 2 Philip Chimento 2017-01-26 22:31:06 UTC
Future versions of Javascript will gain native syntax for this as well, I would expect that to land in GNOME 3.26.
Comment 3 Emmanuele Bassi (:ebassi) 2017-09-15 11:40:24 UTC
Rust is also interested in this, so I think we have critical mass for a new annotation, and possibly some heuristic.
Comment 4 Sebastian Dröge (slomo) 2017-09-15 11:47:29 UTC
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.
Comment 5 Emmanuele Bassi (:ebassi) 2017-09-15 11:53:47 UTC
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.
Comment 6 Sebastian Dröge (slomo) 2017-09-15 12:42:42 UTC
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.
Comment 7 Philip Chimento 2017-09-19 04:23:49 UTC
+1

Here's Vala's heuristic: https://github.com/GNOME/vala/blob/dd2d6c6e37a884a149e5a9e2481cb84266c08bb0/vala/valagirparser.vala#L782

Looks like exactly the same.
Comment 8 Antoni 2017-11-12 17:18:22 UTC
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`).
Comment 9 GNOME Infrastructure Team 2018-02-08 11:55:46 UTC
-- 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.