Upcoming GLib changes

[Tim Janik <timj gtk org>]

hi fellow hackers,

Owen and me recently went over the new additions in the glib 1.3 branch
in order to sort out what realy should be in there and to reveal code
portions that still need some work to be certified as clean and
elegant GLib code ;)
we discovered that we actually had a bunch of issues with the current
stuff in the development tree, and in order to bring GLib 1.3 up to speed,
i'll merge all the pending bug fixes from 1.2.x in the next few days and
clean up various parts of the new API. the following is a summary of our
concerns with the current CVS version.


the random number generator (Mersenne Twister)
----------------------------------------------

1) at this point, we do not want glib to depend on libm.so, so
   the g_rand_normal() implementation should vanish from the grand.c

2) the current random number implementation provides two sets of interfaces.

   one uses a context structure (containing some state information to produce
   the next random number) to allow multiple streams of repeatable random
   numbers, and works well in a threaded environment with no lock overhead.

   The other one is built on top of this and uses a single global context
   for a simplified interface. This simplified interface works
   like the old-fashioned unix rand() and srand() functions, using a global
   lock for thread safety.

   there was disagreement over whether the second interface was necessary.
   i liked it, but Owen and Federico thought it was confusing and unecessary
   bloat.
   so, to help resolve the issue we thought we'd ask what other people on
   gtk-devel-list think.

 
the GQueue implementation
-------------------------

1) we'd like to change the GList *list, *list_end; pointers in the GQueue
   structure to GList *head, *tail; which seems more appropriate for
   this type of data structure.
   the guint list_size; field in the GQueue structure should also be removed,
   because the only common reason to check the size of the queue is the
   "empty" operation and that doesn't need the length.
 
2) similarly to 1), g_queue_push_front (), g_queue_pop_front (),
   g_queue_push_back () and g_queue_pop_back () should actually read
   g_queue_push_head (), g_queue_pop_head (), g_queue_push_tail () and
   g_queue_pop_tail ().

2) g_queue_get_size () should better be named g_queue_length () to conform
   with the rest of the GLib API.

3) g_queue_index (), g_queue_push (), g_queue_pop () and g_queue_peek ()
   have no place in the g_queue API, since they are either not standard
   queue operations or are already available with g_queue_push_tail (),
   g_queue_pop_head ().


the GStack implementation
-------------------------

probably all of the major GLib hackers have been thinking about implementing
a GStack structure at some point (or have actually been doing such a thing,
my stab at this was for instance in fall '97) and figured that all the
neccessary bits are already provided by GSList.
the current g_stack_ API is merely a bad wrapper (macros don't give verbose
warnings about NULL pointers and treating a non existant stack as an
empty one is simply wrong) over some of the GList functions for no apparent
benefit. apart from that, things like g_stack_index() are simply not
stack conforming operations, if you think about using such a function,
be assured that you would have wanted to use a linked list in the first
place. a sane stack implementation would expose: stack_push, stack_pop,
stack_empty and maybe stack_peek, all of which is readily available
with slist_prepend, slist_remove (slist_delete_link),
slist == NULL and slist ? slist->data.


GList & GSList
--------------

the recently added g_list_delete () function should be named
g_list_delete_link (), and of course, we need a GSList implementation
for that as well (the GList and GSList implementations and API should
always stay in sync).


g_strescape ()
--------------

rather than having our own baked escape sequence string conversion routine,
GLib should implement the SunOS variants for this purpose, most notably the
strccpy() and strecpy() functions.


GString
-------

the newly introduced g_string-*() macros are all broken with regards to
GString *string pointer checking and apart from that, accessor macros
for the GString structure are unjustified since the valuable bits of
the GString structure (gchar *str; gint len;) are exposed through the API
and are guarranteed to stay that way through future versions of GLib.
the g_string_ macros are mostly broken.
also there is no point in providing wrapper macros for all kinds of
string manipulation functions (like g_string_cmp(), g_string_dup()),
people can just pass gstring->str to their string manipulatin functions
directly.
the g_string_tokenise() and g_string_tokenise_free() functions are
also superfluous.  If present at all, they should operate on normal
strings, not on GStrings. But that's simply what g_strsplit()
already provides.
code like the one found in g_string_readline() and g_string_readline_buffered()
should probably apear in the g_io_channel API if there is public demand for
such functions.



in general, i'd like to remind people to conform to the overall GLib coding
style, that is, we need appropriate g_return_if_fail () statements all
over the place and follow the GNU coding style. we certainly appreciate
contributions to GLib, but we don't have the time to go through patches
line-by-line for coding style fixes, so in the future, we'll be asking
for resubmission of patches that need fixes in this regard.

---
ciaoTJ