Reference Counting and Memory Mangement

The gdk-pixbuf Library
<<< Previous Page	Home	Up	Next Page >>>

Description

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.

Finalizing 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.

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.

Details

GdkPixbufDestroyNotify ()

void        (*GdkPixbufDestroyNotify)       (guchar *pixels,
                                             gpointer data);

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.

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

GdkPixbufLastUnref ()

void        (*GdkPixbufLastUnref)           (GdkPixbuf *pixbuf,
                                             gpointer data);

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.

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

gdk_pixbuf_ref ()

GdkPixbuf*  gdk_pixbuf_ref                  (GdkPixbuf *pixbuf);

Adds a reference to a pixbuf. It must be released afterwards using gdk_pixbuf_unref().

`pixbuf` :	A pixbuf.
Returns :	The same as the `pixbuf` argument.

gdk_pixbuf_unref ()

void        gdk_pixbuf_unref                (GdkPixbuf *pixbuf);

Removes a reference from a pixbuf. If this is the last reference for the pixbuf, then its last unref handler function will be called; if no handler has been defined, then the pixbuf will be finalized.

pixbuf : A pixbuf.

gdk_pixbuf_set_last_unref_handler ()

void        gdk_pixbuf_set_last_unref_handler
                                            (GdkPixbuf *pixbuf,
                                             GdkPixbufLastUnref last_unref_fn,
                                             gpointer last_unref_fn_data);

Sets the handler function for the pixbuf's last unref handler. When gdk_pixbuf_unref() is called on this pixbuf and it has a reference count of 1, i.e. its last reference, then the last unref handler will be called. This function should determine whether to finalize the pixbuf or just continue. If it wishes to finalize the pixbuf, it should do so by calling gdk_pixbuf_finalize().

gdk_pixbuf_finalize ()

void        gdk_pixbuf_finalize             (GdkPixbuf *pixbuf);

Finalizes a pixbuf by calling its destroy notification function to free the pixel data and freeing the pixbuf itself. This function is meant to be called only from within a GdkPixbufLastUnref handler function, and the specified pixbuf must have a reference count of 1, i.e. its last reference.

pixbuf : A pixbuf with a reference count of 1.

`pixbuf` :	A pixbuf.
`last_unref_fn` :	Handler function for the last unref.
`last_unref_fn_data` :	Closure data to pass to the last unref handler function.