Re: Behaviour of getters wrt dup/ref

[Alexander Larsson <alexl redhat com>]

On Sat, 2007-09-15 at 23:08 -0400, Behdad Esfahbod wrote:
> On Fri, 2007-09-14 at 10:35 -0400, Alexander Larsson wrote:
> > 
> > char *      g_data_input_stream_get_line (GDataInputStream *data_stream,
> >                                           gsize             *length,
> >                                           GCancellable     *cancellable,
> >                                           GError           **error);
> > 
> > This actually reads new data from the stream, so it has to dup. One
> > could imagine a similar call that returns some form of object instead
> > of a string. 
> 
> Hi Alex,
> 
> I think it's pretty common in glib and pango at least to return
> g_strdup'ed strings.  The no-ref-count rule is mostly for objects that
> have a literal ref/unref pair.

Ok, lets start from the general rule that strings are strdup:ed and
gobjects are not ref:ed. 

Here are some violations of that in the gio api, reasons why, and
possible changes:

GList *   g_app_info_get_all_for_type (const char  *content_type);
GAppInfo *g_app_info_get_default_for_type (const char  *content_type);

These obviously have to return a ref:ed value, because the content type
string doesn't own the result. 
Maybe I should use another name for these. For instance
g_app_info_query_all_fo_type and g_app_info_query_default_for_type.

char *   g_content_type_get_description   (const char   *type);
char *   g_content_type_get_mime_type     (const char   *type);
GIcon *  g_content_type_get_icon          (const char   *type);

Same here.

char *g_data_input_stream_get_line(...)

Independent on the memory allocation properties of this it really should
be read_line().

GDrive * g_volume_get_drive      (GVolume              *volume);

This currently refs the result for historical reasons. This API is quite
similar to the gnome-vfs volume manager API. There is a singleton volume
monitor that keeps track of the volumes and drives availible on the
system, which can change at any time. So, if you get the drive for a
volume you get the current value, which might change later. In gnome-vfs
this API is used by gnome-vfs backends, which means the API have to be
threadsafe, and the only way to make it threadsafe is to ref in the
getter. In gio we could decide to make this API not threadsafe and have
non-reffing getters. Opinions on this?

const char *g_file_info_get_attribute_string (GFileInfo  *info,
					      const char *attribute);
and helpers like:
const char *g_file_info_get_name (GFileInfo  *info);

For these calls it really makes no sense to dup the code. The GFileInfo
is the container for the data, and we're just peeking at the data. This
is somewhat similar to g_value_get_string() which also doesn't dup.

GFile * g_file_get_parent (GFile *file);
GFile * g_file_get_child (GFile *file,
			  const char *name);

These create a new GFile object, and there just is no way to not ref the
return value. Should we use a different name for these, and if so what?
I don't have any good ideas. Maybe just g_file_parent() /
g_file_child()?

GFileInfo *g_file_get_info (GFile              *file,
			   const char          *attributes,
			   GFileGetInfoFlags    flags,
			   GCancellable        *cancellable,
			   GError             **error);

This is not really a getter, but an i/o operator (its stat/lstat).
However, read_info() seems a bit weird name for this. Can anyone think
of a better name?

> Other than that, for functions that return read data from the stream,
> some people may have reasons to want to avoid malloc/free'ing on each
> line.  One way to work around that is to have the function take a
> GString, so you can reuse the buffer from the previous line.  I know
> most people are not a big fan of that idea though.

Hmmm, there are lots of lowlevel functions that you can use if you want
to do fancy array growing and whatnot. get_line() (or better,
read_line()) is mainly a very easy to use helper function for reading a
full line of text. I don't think we want to make it more complicated, as
then the whole point of it is sort of moot.