GNOME Bugzilla – Bug 626721
[annotation] (success) for functions with (out) args and bool return value
Last modified: 2018-01-25 14:03:57 UTC
Some functions have a gboolean return value and some out args, and the return value is TRUE on success, FALSE on failure. If the return value is FALSE, the out args values are usually undefined, and as such cannot be trusted by bindings: trying to cast an undefined out pointer into a GObject or something else might lead to issues or crashes. Such a function is gdk_event_get_state(). As a solution, we would like to introduce a new (success) annotation for the return value of such functions. It would indicate that the binding should *not* use the (out) values when the return value is FALSE. Binding-side (here, pygobject), we would have something like this: state = some_event.get_state() if out is not None: do_something_with_the_state(state) instead of the current: (success, state) = some_event.get_state() if success: do_something_with_the_state(state)
very similar to bug 599698, though that proposal wouldn't include gdk_event_get_state()
Created attachment 256855 [details] IRC conversation log
A while ago (well over a year) on #introspection, I discussed a different idea for indicating whether conditional out parameters are filled with a value for a successful outcome. See attached log. In this proposal, the (out) annotation is extended to indicate 1. whether an out parameter is conditional 2. the source of the condition This would be achieved with additional arguments as follows: (out cond=PARAM) to indicate that the out parameter is 'successfully filled' when PARAM is non-zero, i.e. when PARAM not FALSE for a gboolean, not NULL for a pointer etc. (out cond-ret) to indicate that the out parameter is 'successfully filled' when the return value is non-zero. Unlike the (success) annotation for return values proposed in comment #1, this approach does not require all out parameters to have the same conditional behaviour. So, for example, the (success) annotation would not exactly capture the conditional behaviour of out parameters of gtk_tree_selection_get_selected where model is filled irrespective of the return value iter is filled iff the return value is non-zero
Previous comment should have said comment #0 instead of comment #1.
In many cases, it would be better to just have more-bindable alternative versions of the functions.
[Mass-moving gobject-introspection tickets to its own Bugzilla product - see bug 708029. Mass-filter your bugmail for this message: introspection20150207 ]
*** This bug has been marked as a duplicate of bug 669016 ***