On Fri, 14 Sep 2007, Alexander Larsson wrote: > I got some feedback on gio about a getter function that returned a ref, > and now I'm reviewing the gio APIs for things like that, making sure its > internally consistent and consistent with gtk+/glib. > > However, I'm not sure what the gtk+ standard for this is. I heard "no > reffing getters", but that is somewhat limited.
[without following the rest of this thread...] we discussed this back in the day when we still could have changed matters to be consistently across the platform. i believe the general getter/dup/peek discussion should be in the gnome-hackers archive around 2000. the short story is this: - it was suggested to name getters 'peek' if they returned pointers to memoery that was not duplicated or referenced. i.e. not owned by the caller. - it was suggested to name getters 'dup' (or 'ref') if they returned pointers to memoery that was allocated or referenced for the purpose of the getter, i.e. owned by the caller. - after a lengthy discussion, both suggestions got rejected and we stuck with: a) a getter is usually named '_get_' b) memory returned by a getter can be duplicated/referenced or not, that depends on the getter. the user always has to refer to the documentation or source code here. c) for strings, getters that return memory not owned by the caller should use G_CONST_RETURN. a good reason for why there is no simple convention for getters is the case of getting a list of objects. in some cases you'd want to be able to peek at the internally stored list nodes for performance reasons, e.g.: /* returned list *not* owed by caller */ GSList* gtk_window_peek_toplevels (void); free: /*noop*/ in others, you'd e.g. buy the overhead of a list copy for the sake of always returning doubly linked lists and do: /* returned list owed by caller, but not references */ GList* gtk_window_list_toplevels (void); free: g_list_free (return_value); and then again, for some object lists where it's common practice to modify or destroy some of the returned instances, or where it's likely to have a concurrent entity deleting/adding/shuffling items in the list, it may make most sense to hand out extra object references: /* returned list and additional references owed by caller */ GList* gtk_window_list_toplevels_refed (void); free: g_list_foreach (return_value, g_object_unref, NULL); g_list_free (return_value); --- ciaoTJ _______________________________________________ gtk-devel-list mailing list gtk-devel-list@gnome.org http://mail.gnome.org/mailman/listinfo/gtk-devel-list