GIterator bug final writeup

[Owen Taylor <otaylor redhat com>]

Wanted to definitely WONTFIX 

 http://bugzilla.gnome.org/show_bug.cgi?id=83729

about GIterator, which has been in limbo for a long time, so I found a
writeup I started a year or two ago and finished it off.

The basic question to me is "what is GIterator trying to achieve?".

Possibilities:

 1) Consistency. We have many ways of returning lists of
    items or iterating over sets of items. Conceivably,
    by consitently always using GIterator in these 
    circumstances, we could have a single way of doing
    everything.

    To me, this is a lost battle. GTK+ is relatively mature 
    codebase - is GTK+ going to have twice as many entry points 
    10 years from now? I doubt it. So, if we only used
    GIterator for new additions, we'd still be > 50% 
    inconstistent.
    
    And you can't get consistency by adding extra function 
    variants ... the old ones will still be there in the
    docs, still be there in old code.
  
    In my opinion, adding GIterator is not going to make
    it easier for people to learn how to program GTK+ in C.

 2) Better memory management. One problem with the current
    methods of returning lists or arrays is that the
    caller has to figure out how to free the result.
    GIterator standardizes that.

 3) Language binding support. Array and list returns are
    currently a problem for language bindings because
    of the memory management concerns in 2). foreach()
    functions don't have this problem, but they typically
    require some hand language binding glue and may not
    be very natural for some programming languages. (For 
    instance, C++) 

    A second problem for language bindings is that there
    is missing type information if we just have a 
    function signature returning a GSList.

    GIterator and GValueIterator do help the memory 
    management problem .. see above.

    GIterator doesn't solve the type information problem.
  
 4) Convenience. Maybe it is just easier to use GIterator
    than the current APIs. I don't see this as the case ...
    it's more function calls. It's not type safe. (Some
    of the current calls aren't, some are.) You can't
    make multiple passes through the data in an easy
    fashion.

None of these is all that compelling to me.

One other thing to note is that with iterators you have
to choose between

 - Lack of robustness like a foreach() function; if iterators
   contain pointers to internal data, they won't be 
   robust against structural changes.

 - Lack of efficiency like returning an array. You can 
   make the iterator robust by just making it a wrapper
   around an array.

The fact that we can't achieve consistency is the killer objection 
to me. Memory management does get better, language binding
support and convenience is a bit of a wash. But without
being able to use GIterator consitently everywhere, in the
end all we will be making it harder to learn how to use 
GLib and GTK+, not easier.

Regards,
					Owen