Re: Behaviour of getters wrt dup/ref

[Alexander Larsson <alexl redhat com>]

On Thu, 2007-09-20 at 13:37 +0200, Tim Janik wrote:
> 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.
> 

Makes sense to me. Thanks.