<!-- ##### SECTION Title ##### -->
Reference Counting and Memory Mangement

<!-- ##### SECTION Short_Description ##### -->

Functions to perform reference counting and memory management on a
#GdkPixbuf.

<!-- ##### SECTION Long_Description ##### -->
  <para>
    #GdkPixbuf structures are reference counted.  This means that
    an application can share a single pixbuf among many parts of the
    code.  When a piece of the program needs to keep a pointer to a
    pixbuf, it should add a reference to it.  When it no longer needs
    the pixbuf, it should subtract a reference.  The pixbuf will be
    destroyed when its reference count drops to zero.  Newly-created
    #GdkPixbuf structures start with a reference count of one.
  </para>

  <para>
    <emphasis>Finalizing</emphasis> a pixbuf means to free its pixel
    data and to free the #GdkPixbuf structure itself.  Most of the
    library functions that create #GdkPixbuf structures create the
    pixel data by themselves and define the way it should be freed;
    you do not need to worry about those.  The only function that lets
    you specify how to free the pixel data is
    gdk_pixbuf_new_from_data().  Since you pass it a pre-allocated
    pixel buffer, you must also specify a way to free that data.  This
    is done with a function of type #GdkPixbufDestroyNotify.  When a
    pixbuf created with gdk_pixbuf_new_from_data() is finalized, your
    destroy notification function will be called, and it is its
    responsibility to free the pixel array.
  </para>

  <para>
    As an extension to traditional reference counting, #GdkPixbuf
    structures support defining a handler for the last unref
    operation.  If gdk_pixbuf_unref() is called on a #GdkPixbuf
    structure that has a reference count of 1, i.e. its last
    reference, then the pixbuf's last unref handler function will be
    called.  It is up to this function to determine whether to
    finalize the pixbuf using gdk_pixbuf_finalize() or to just
    continue execution.  This can be used to implement a pixbuf cache
    efficiently; please see the programmer's documentation for
    details.
  </para>

<!-- FIXME: link the last sentence above to the relevant section of
     the programmer's docs.
-->

<!-- ##### SECTION See_Also ##### -->
  <para>
    #GdkPixbuf, gdk_pixbuf_new_from_data().
  </para>

<!-- ##### USER_FUNCTION GdkPixbufDestroyNotify ##### -->
  <para>
    A function of this type is responsible for freeing the pixel array
    of a pixbuf.  The gdk_pixbuf_new_from_data() function lets you
    pass in a pre-allocated pixel array so that a pixbuf can be
    created from it; in this case you will need to pass in a function
    of #GdkPixbufDestroyNotify so that the pixel data can be freed
    when the pixbuf is finalized.
  </para>

@pixels: The pixel array of the pixbuf that is being finalized.
@data: User closure data.


<!-- ##### USER_FUNCTION GdkPixbufLastUnref ##### -->
  <para>
    A function of this type can be used to override the default
    operation when a pixbuf loses its last reference, i.e. when
    gdk_pixbuf_unref() is called on a #GdkPixbuf structure that has a
    reference count of 1.  This function should determine whether to
    finalize the pixbuf by calling gdk_pixbuf_finalize(), or whether
    to just resume normal execution.  The last unref handler for a
    #GdkPixbuf can be set using the
    gdk_pixbuf_set_last_unref_handler() function.  By default, pixbufs
    will be finalized automatically if no last unref handler has been
    defined.
  </para>

@pixbuf: The pixbuf that is losing its last reference.
@data: User closure data.


<!-- ##### FUNCTION gdk_pixbuf_ref ##### -->
  <para>

  </para>

@pixbuf: 
@Returns: 


<!-- ##### FUNCTION gdk_pixbuf_unref ##### -->
<para>

</para>

@pixbuf: 


<!-- ##### FUNCTION gdk_pixbuf_set_last_unref_handler ##### -->
<para>

</para>

@pixbuf: 
@last_unref_fn: 
@last_unref_fn_data: 


<!-- ##### FUNCTION gdk_pixbuf_finalize ##### -->
<para>

</para>

@pixbuf: <!--
Local variables:
mode: sgml
sgml-parent-document: ("../gdk-pixbuf.sgml" "book" "refsect2" "")
End:
-->


