docs/reference/glib/changes.sgml

   1 <refentry id="glib-changes" revision="17 Jan 2002">
   2 <refmeta>
   3 <refentrytitle>Changes to GLib</refentrytitle>
   4 <manvolnum>3</manvolnum>
   5 <refmiscinfo>Changes to GLib</refmiscinfo>
   6 </refmeta>
   7
   8 <refnamediv>
   9 <refname>Changes to GLib</refname>
  10 <refpurpose>
  11 Incompatible changes made between successing versions of GLib
  12 </refpurpose>
  13 </refnamediv>
  14
  15
  16 <refsect1>
  17 <title>Incompatible changes from 2.0 to 2.2</title>
  18
  19 <itemizedlist>
  20
  21 <listitem>
  22 <para>
  23 GLib changed the seeding algorithm for the pseudo-random number
  24 generator Mersenne Twister, as used by <structname>GRand</structname>
  25 and <structname>GRandom</structname>. This was necessary, because some
  26 seeds would yield very bad pseudo-random streams. Also the
  27 pseudo-random integers generated by
  28 <function>g_rand*_int_range()</function> will have a
  29 slightly better equal distribution with the new version of GLib.
  30 </para>
  31
  32 <para>
  33 Further information can be found at the website of the Mersenne
  34 Twister random number generator at <ulink
  35 url="http://www.math.keio.ac.jp/~matumoto/emt.html">http://www.math.keio.ac.jp/~matumoto/emt.html</ulink>.
  36 </para>
  37
  38 <para>
  39 The original seeding and generation algorithms, as found in GLib
  40 2.0.x, can be used instead of the new ones by setting the environment
  41 variable <envar>G_RANDOM_VERSION</envar> to the value of '2.0'. Use
  42 the GLib-2.0 algorithms only if you have sequences of numbers generated
  43 with Glib-2.0 that you need to reproduce exactly.
  44 </para>
  45
  46 </listitem>
  47
  48 </itemizedlist>
  49
  50 </refsect1>
  51
  52 <refsect1>
  53 <title>Incompatible changes from 1.2 to 2.0</title>
  54
  55 <para>
  56 The <ulink url="http://developer.gnome.org/dotplan/porting/">GNOME 2.0
  57 porting guide</ulink> on <ulink
  58 url="http://developer.gnome.org">http://developer.gnome.org</ulink>
  59 has some more detailed discussion of porting from 1.2 to 2.0.
  60 See the section on GLib.
  61 </para>
  62
  63 <itemizedlist>
  64
  65 <listitem>
  66 <para>
  67 The event loop functionality <structname>GMain</structname> has extensively
  68 been revised to support multiple separate main loops in separate threads.
  69 All sources (timeouts, idle functions, etc.) are associated with a
  70 <structname>GMainContext</structname>.
  71 </para>
  72
  73 <para>
  74 Compatibility functions exist so that most application code dealing with
  75 the main loop will continue to work. However, code that creates new custom
  76 types of sources will require modification.
  77 </para>
  78
  79 <para>
  80 The main changes here are:
  81
  82   <itemizedlist>
  83
  84   <listitem>
  85   <para>
  86    Sources are now exposed as <type>GSource *</type>, rather than simply as
  87    numeric ids.
  88   </para>
  89   </listitem>
  90
  91   <listitem>
  92   <para>
  93    New types of sources are created by structure "derivation" from
  94    <structname>GSource</structname>, so the <literal>source_data</literal>
  95    parameter to the <structname>GSource</structname> virtual functions has been
  96    replaced with a <type>GSource *</type>.
  97   </para>
  98   </listitem>
  99
 100   <listitem>
 101   <para>
 102    Sources are first created, then later added to a specific
 103    <structname>GMainContext</structname>.
 104   </para>
 105   </listitem>
 106
 107   <listitem>
 108   <para>
 109    Dispatching has been modified so both the callback and data are passed
 110    in to the <function>dispatch()</function> virtual function.
 111   </para>
 112   </listitem>
 113
 114   </itemizedlist>
 115   To go along with this change, the vtable for
 116   <structname>GIOChannel</structname> has changed and
 117   <function>add_watch()</function> has been replaced by
 118   <function>create_watch()</function>.
 119 </para>
 120 </listitem>
 121
 122 <listitem>
 123 <para>
 124 <function>g_list_foreach()</function> and
 125 <function>g_slist_foreach()</function> have been changed so they
 126 are now safe against removal of the current item, not the next item.
 127 </para>
 128
 129 <para>
 130 It's not recommended to mutate the list in the callback to these
 131 functions in any case.
 132 </para>
 133 </listitem>
 134
 135 <listitem>
 136 <para>
 137 <structname>GDate</structname> now works in UTF-8, not in the current locale.
 138 If you want to use it with the encoding of the locale, you need to convert
 139 strings using <function>g_locale_to_utf8()</function> first.
 140 </para>
 141 </listitem>
 142
 143 <listitem>
 144 <para>
 145 <function>g_strsplit()</function> has been fixed to:
 146
 147   <itemizedlist>
 148   <listitem>
 149   <para>
 150    include trailing empty tokens, rather than stripping them
 151   </para>
 152   </listitem>
 153   <listitem>
 154   <para>
 155    split into a maximum of <literal>max_tokens</literal> tokens, rather
 156    than <literal>max_tokens + 1</literal>
 157   </para>
 158   </listitem>
 159   </itemizedlist>
 160
 161   Code depending on either of these bugs will need to be fixed.
 162 </para>
 163 </listitem>
 164
 165 <listitem>
 166 <para>
 167 Deprecated functions that got removed:
 168 <function>g_set_error_handler()</function>,
 169 <function>g_set_warning_handler()</function>,
 170 <function>g_set_message_handler()</function>, use
 171 <function>g_log_set_handler()</function> instead.
 172 </para>
 173 </listitem>
 174 </itemizedlist>
 175
 176 </refsect1>
 177
 178 </refentry>