GNOME Bugzilla – Bug 789815
Improve documentation for private fields of GSourceFuncs
Last modified: 2018-05-24 19:50:32 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?
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.
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()
I'm going to pass on this one, sorry!
-- 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.