cha-glib.html

gtk 开发手册和参考文档。 包括gtk glib gdk等

                </tr>
              </table>
              <p>
                <code><code class="FUNCDEF"><tt class="FUNCTION">
                GINT_TO_POINTER</tt></code>(<tt class=
                "PARAMETER"><i>p</i></tt>);</code>
              </p>
              <p>
                <code><code class="FUNCDEF"><tt class="FUNCTION">
                GPOINTER_TO_INT</tt></code>(<tt class=
                "PARAMETER"><i>p</i></tt>);</code>
              </p>
              <p>
                <code><code class="FUNCDEF"><tt class="FUNCTION">
                GUINT_TO_POINTER</tt></code>(<tt class=
                "PARAMETER"><i>p</i></tt>);</code>
              </p>
              <p>
                <code><code class="FUNCDEF"><tt class="FUNCTION">
                GPOINTER_TO_UINT</tt></code>(<tt class=
                "PARAMETER"><i>p</i></tt>);</code>
              </p>
            </div>
            <p>
              <b>Figure 2. Macros for storing integers in
              pointers</b>
            </p>
          </div>
        </div>
        <div class="SECT2">
          <h2 class="SECT2">
            <a name="Z27">Debugging Macros</a>
          </h2>
          <p>
            glib has a nice set of macros you can use to enforce
            invariants and preconditions in your code. GTK+ uses
            these liberally---one of the reasons it's so stable and
            easy to use. They all disappear when you define <tt
            class="FUNCTION">G_DISABLE_CHECKS</tt> or <tt class= 
            "FUNCTION">G_DISABLE_ASSERT</tt>, so there's no
            performance penalty in production code. Using these
            liberally is a very, very good idea. You'll find bugs
            much faster if you do. You can even add assertions and
            checks whenever you find a bug to be sure the bug
            doesn't reappear in future versions---this complements
            a regression suite. Checks are especially useful when
            the code you're writing will be used as a black box by
            other programmers; users will immediately know when and
            how they've misused your code.
          </p>
          <p>
            Of course you should be very careful to ensure your
            code isn't subtly dependent on debug-only statements to
            function correctly. Statements that will disappear in
            production code should <i class="EMPHASIS">never</i>
            have side effects.
          </p>
          <div class="FIGURE">
            <a name="ML-PRECONDITION"></a>
            <div class="FUNCSYNOPSIS">
              <a name="ML-PRECONDITION.SYNOPSIS"></a>
              <table border="0" bgcolor="#E0E0E0" width="100%">
                <tr>
                  <td>
<pre class="FUNCSYNOPSISINFO">
#include &lt;glib.h&gt;
</pre>
                  </td>
                </tr>
              </table>
              <p>
                <code><code class="FUNCDEF"><tt class="FUNCTION">
                g_return_if_fail</tt></code>(<tt class=
                "PARAMETER"><i>condition</i></tt>);</code>
              </p>
              <p>
                <code><code class="FUNCDEF"><tt class="FUNCTION">
                g_return_val_if_fail</tt></code>(<tt class= 
                "PARAMETER"><i>condition</i></tt>, <tt class= 
                "PARAMETER"><i>retval</i></tt>);</code>
              </p>
            </div>
            <p>
              <b>Figure 3. Precondition Checks</b>
            </p>
          </div>
          <p>
            <a href="cha-glib.html#ML-PRECONDITION">Figure 3</a>
            shows glib's precondition checks. <tt class="FUNCTION">
            g_return_if_fail()</tt> prints a warning and
            immediately returns from the current function if <span
            class="STRUCTNAME">condition</span> is <span class= 
            "STRUCTNAME">FALSE</span>. <tt class="FUNCTION">
            g_return_val_if_fail()</tt> is similar but allows you
            to return some <span class="STRUCTNAME">retval</span>.
            These macros are incredibly useful---if you use them
            liberally, especially in combination with GTK+'s
            runtime type checking, you'll halve the time you spend
            looking for bad pointers and type errors.
          </p>
          <p>
            Using these functions is simple; here's an example from
            the glib hash table implementation:
          </p>
          <table border="0" bgcolor="#E0E0E0" width="100%">
            <tr>
              <td>
<pre class="PROGRAMLISTING">
&#13;void
g_hash_table_foreach (GHashTable *hash_table,
                      GHFunc      func, 
                      gpointer    user_data)
{
  GHashNode *node;
  gint i;
  
  g_return_if_fail (hash_table != NULL);
  g_return_if_fail (func != NULL);
  
  for (i = 0; i &lt; hash_table-&gt;size; i++)
    for (node = hash_table-&gt;nodes[i]; node; node = node-&gt;next)
      (* func) (node-&gt;key, node-&gt;value, user_data);
}&#13;
</pre>
              </td>
            </tr>
          </table>
          <p>
            Without the checks, passing <span class="STRUCTNAME">
            NULL</span> as a parameter to this function would
            result in a mysterious segmentation fault. The person
            using the library would have to figure out where the
            error occurred with a debugger, and maybe even dig in
            to the glib code to see what was wrong. With the
            checks, they'll get a nice error message telling them
            that <span class="STRUCTNAME">NULL</span> arguments are
            not allowed.
          </p>
          <div class="FIGURE">
            <a name="ML-ASSERTIONS"></a>
            <div class="FUNCSYNOPSIS">
              <a name="ML-ASSERTIONS.SYNOPSIS"></a>
              <table border="0" bgcolor="#E0E0E0" width="100%">
                <tr>
                  <td>
<pre class="FUNCSYNOPSISINFO">
#include &lt;glib.h&gt;
</pre>
                  </td>
                </tr>
              </table>
              <p>
                <code><code class="FUNCDEF"><tt class="FUNCTION">
                g_assert</tt></code>(<tt class=
                "PARAMETER"><i>condition</i></tt>);</code>
              </p>
              <p>
                <code><code class="FUNCDEF"><tt class="FUNCTION">
                g_assert_not_reached</tt></code>(void);</code>
              </p>
            </div>
            <p>
              <b>Figure 4. Assertions</b>
            </p>
          </div>
          <p>
            glib also has more traditional assertion macros, shown
            in <a href="cha-glib.html#ML-ASSERTIONS">Figure 4</a>.
            <tt class="FUNCTION">g_assert()</tt> is basically
            identical to <tt class="FUNCTION">assert()</tt>, but
            responds to <span class="STRUCTNAME">
            G_DISABLE_ASSERT</span> and behaves consistently across
            all platforms. <tt class="FUNCTION">
            g_assert_not_reached()</tt> is also provided; this is
            an assertion which always fails. Assertions call <tt
            class="FUNCTION">abort()</tt> to exit the program and
            (if your environment supports it) dump a core file for
            debugging purposes.
          </p>
          <p>
            Fatal assertions should be used to check <i class= 
            "EMPHASIS">internal consistency</i> of a function or
            library, while <tt class="FUNCTION">
            g_return_if_fail()</tt> is intended to ensure sane
            values are passed to the public interfaces of a program
            module. That is, if an assertion fails, you typically
            look for a bug in the module containing the assertion;
            if a <tt class="FUNCTION">g_return_if_fail()</tt> check
            fails, you typically look for the bug in the code which
            invokes the module.
          </p>
          <p>
            This code from glib's calendrical calculations module
            shows the difference:
          </p>
          <table border="0" bgcolor="#E0E0E0" width="100%">
            <tr>
              <td>
<pre class="PROGRAMLISTING">
&#13;GDate*
g_date_new_dmy (GDateDay day, GDateMonth m, GDateYear y)
{
  GDate *d;
  g_return_val_if_fail (g_date_valid_dmy (day, m, y), NULL);
  
  d = g_new (GDate, 1);
  
  d-&gt;julian = FALSE;
  d-&gt;dmy    = TRUE;
  
  d-&gt;month = m;
  d-&gt;day   = day;
  d-&gt;year  = y;
  
  g_assert (g_date_valid (d));
  
  return d;
}&#13;
</pre>
              </td>
            </tr>
          </table>
          <p>
            The precondition check at the beginning ensures the
            user passes in reasonable values for the day, month and
            year; the assertion at the end ensures that glib
            constructed a sane object, given sane values.
          </p>
          <p>
            <tt class="FUNCTION">g_assert_not_reached()</tt> should
            be used to mark "impossible" situations; a common use
            is to detect switch statements that don't handle all
            possible values of an enumeration:
          </p>
          <table border="0" bgcolor="#E0E0E0" width="100%">
            <tr>
              <td>
<pre class="PROGRAMLISTING">
&#13;  switch (val) 
    {
      case FOO_ONE:
        break;
      case FOO_TWO:
        break;
      default:
        /* Invalid enumeration value */
        g_assert_not_reached();
        break;
    }&#13;
</pre>
              </td>
            </tr>
          </table>
          <p>
            All of the debugging macros print a warning using
            glib's <tt class="FUNCTION">g_log()</tt> facility,
            which means the warning includes the name of the
            originating application or library, and you can
            optionally install a replacement warning-printing
            routine. For example, you might send all warnings to a
            dialog box or log file instead of printing them on the
            console.
          </p>
        </div>
        <div class="SECT2">
          <h2 class="SECT2">
            <a name="GLIB-MEMORY">Memory</a>
          </h2>
          <p>
            glib wraps the standard <tt class="FUNCTION">
            malloc()</tt> and <tt class="FUNCTION">free()</tt> with
            its own <span class="STRUCTNAME">g_</span> variants,
            <tt class="FUNCTION">g_malloc()</tt> and <tt class= 
            "FUNCTION">g_free()</tt>, shown in <a href= 
            "cha-glib.html#FL-MEMORY">Figure 5</a>. These are nice
            in several small ways:
          </p>
          <ul>
            <li>
              <p>
                <tt class="FUNCTION">g_malloc()</tt> always returns
                a <span class="STRUCTNAME">gpointer</span>, never a
                <span class="STRUCTNAME">char*</span>, so there's
                no need to cast the return value.&#13;
              </p>
            </li>
            <li>
              <p>
                <tt class="FUNCTION">g_malloc()</tt> aborts the
                program if the underlying <tt class="FUNCTION">
                malloc()</tt> fails, so you don't have to check for
                a <span class="STRUCTNAME">NULL</span> return
                value.&#13;
              </p>
            </li>
            <li>
              <p>
                <tt class="FUNCTION">g_malloc()</tt> gracefully
                handles a <span class="STRUCTNAME">size</span> of
                <span class="STRUCTNAME">0</span>, by returning
                <span class="STRUCTNAME">NULL</span>.&#13;