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 789815 - Improve documentation for private fields of GSourceFuncs
Improve documentation for private fields of GSourceFuncs
Status: RESOLVED OBSOLETE
Product: glib
Classification: Platform
Component: docs
2.54.x
Other Linux
: Normal normal
: ---
Assigned To: gtkdev
gtkdev
Depends on:
Blocks:
 
 
Reported: 2017-11-02 12:41 UTC by Philip Withnall
Modified: 2018-05-24 19:50 UTC
See Also:
GNOME target: ---
GNOME version: ---



Description Philip Withnall 2017-11-02 12:41:23 UTC
From bug #697908:

@@ +1185,3 @@
+  gnutls_source_dispatch,
+  gnutls_source_finalize,
+  (GSourceFunc)g_tls_connection_gnutls_source_dtls_closure_callback,

So I'm quite confused by this.

Only the first four fields of GSourceFuncs are documented. The final two fields are annotated:

  /*< private >*/
  /* For use by g_source_set_closure */

So I would say it's unacceptable to use them. On the other hand, this class already used them before your patch. And the documentation of g_source_set_closure() actually instructs us to use them. IMO that is clearly a GLib documentation bug. Can you file a bug report?
Comment 1 Michael Catanzaro 2017-11-28 16:03:56 UTC
This bug is related to bug #790948, which is also to improve the documentation of GSourceFuncs. But I don't understand very well how the closures are supposed to work, so I've only submitted a patch in the other bug.
Comment 2 Philip Withnall 2017-11-29 17:51:43 UTC
If you could put together a patch, that would be great. I think the key points here are:
 - Those two fields in GSourceFuncs should not be private
 - closure_callback effectively converts a C function call into a closure invocation
 - closure_marshal effectively converts a closure invocation into a C function call
 - There’s some information about callbacks here: https://developer.gnome.org/gnome-devel-demos/unstable/custom-gsource.c.html.en#callback
 - Closure support (those two functions) is not needed if you only use your GSource with g_source_set_callback{,_indirect}()
 - It’s needed if you use your GSource with g_source_set_closure() or g_source_set_dummy_callback()
 - I don’t know of any code which actually uses g_source_set_closure() — both pygobject and gjs use g_source_set_callback()
Comment 3 Michael Catanzaro 2017-11-29 19:22:42 UTC
I'm going to pass on this one, sorry!
Comment 4 GNOME Infrastructure Team 2018-05-24 19:50:32 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/glib/issues/1296.