Re: Behaviour of getters wrt dup/ref

[Tim Janik <timj gtk org>]

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