[Bug 39189] [next] decide on a policy for transfer, naming and containers

[bugzilla-daemon at freedesktop.org]

https://bugs.freedesktop.org/show_bug.cgi?id=39189

Simon McVittie <simon.mcvittie at collabora.co.uk> changed:

           What    |Removed                     |Added
----------------------------------------------------------------------------
                 CC|                            |jonny.lamb at collabora.co.uk,
                   |                            |simon.mcvittie at collabora.co
                   |                            |.uk
            Summary|[API Break] Use GPtrArray   |[next] decide on a policy
                   |as our preferred container  |for transfer, naming and
                   |for collections             |containers

--- Comment #3 from Simon McVittie <simon.mcvittie at collabora.co.uk> 2012-03-05 10:45:21 PST ---
Before getting much further with next, we should decide:

----

1. What is our preferred transfer mode for single objects?

The options are none and full. We should choose one to use whenever the name of
a method doesn't specifically indicate it ("dup", "borrow").

In favour of none:
* it's the easiest "C binding"

In favour of full:
* you have to use it anyway if you ever want to become thread-safe
* you have to use it anyway if you compute the value on-demand

Whichever one we choose, we can use "dup" or "borrow" to make it explicit when
we're using the other one.

Additionally, I think whenever we have a "dup" or "borrow" without a
corresponding "get", in Telepathy 1.0 we should use "Rename to:" to rename it
to get_foo for introspective bindings. (This is an introspection API break.)

Current practice in tp-glib: "get" mostly means (transfer none), but a lot of
things are only available as "dup". Sometimes functions with transfer none are
called "borrow" anyway.

My opinion: we should bite the bullet and make "get" mean (transfer full). We
can have parallel "borrow" functions as "C bindings" where it makes sense, and
use (skip) to omit them from introspection.

----

2. What is our preferred transfer mode for plural objects?

Options are none, container and full.

none and full have the same advantages as for singular objects. full is also
popular in GIO.

In favour of container: it's popular (although by no means the only thing used)
in Gtk.

Current practice in tp-glib: "get" means (transfer container), e.g. in
TpAccount. This may have been Jonny's idea, or he might have just copied
current practice from Empathy.

My opinion: I think we should make "get" mean (transfer full), and have
parallel "borrow" functions if we really need them.

----

3. What is our preferred container for plural getters?

The options are basically GList and GPtrArray, with a dishonourable mention for
GSList if you like micro-optimizations.

In favour of GList:
* everything else uses it
* returning a non-refcounted type guarantees that any changes made by the
  object are not visible to callers with an old copy, and vice versa
* never needs to realloc
* the empty list takes no memory
* short lists take less memory than anything else, except GSList
* forward and reverse iteration is O(n)
* you can do O(n) list building via a GQueue or the prepend-and-reverse
  pattern

In favour of GPtrArray:
* you can refcount it (but that might not be such a good idea)
* you can set a free_func for safe use of (transfer container)
* large arrays use around 1/3 of the memory of GList
* reverse iteration still works
* building is trivial and O(n)
* iteration is trivial and O(n)
* most operations are O(1) unless you need to realloc

In favour of GSList:
* returning a non-refcounted blah blah blah (... same as GList)
* uses around 2/3 of the memory of GList
* never needs to realloc
* the empty list takes no memory
* short lists take less memory than anything else
* forward iteration is O(n) (but reverse iteration is expensive)

Current practice in tp-glib: GList, except where we use a C array
    with a length

My opinion: let's standardize on GList for least-astonishment.

-- 
Configure bugmail: https://bugs.freedesktop.org/userprefs.cgi?tab=email
------- You are receiving this mail because: -------
You are the QA Contact for the bug.
You are the assignee for the bug.