4
>Reference Counting and Memory Mangement</TITLE
7
CONTENT="Modular DocBook HTML Stylesheet Version 1.76b+
10
TITLE="The gdk-pixbuf Library"
11
HREF="index.html"><LINK
16
TITLE="The GdkPixbuf Structure"
17
HREF="gdk-pixbuf-gdk-pixbuf.html"><LINK
20
HREF="gdk-pixbuf-file-loading.html"></HEAD
55
HREF="gdk-pixbuf-gdk-pixbuf.html"
60
><<< Previous Page</B
109
HREF="gdk-pixbuf-file-loading.html"
114
>Next Page >>></B
123
NAME="GDK-PIXBUF-REFCOUNTING">Reference Counting and Memory Mangement</H1
131
>Reference Counting and Memory Mangement -- Functions to perform reference counting and memory management on a
134
CLASS="REFSYNOPSISDIV"
147
> #include <gdk-pixbuf/gdk-pixbuf.h>
151
HREF="gdk-pixbuf-refcounting.html#GDKPIXBUFDESTROYNOTIFY"
152
>*GdkPixbufDestroyNotify</A
156
HREF="gdk-pixbuf-refcounting.html#GDKPIXBUFLASTUNREF"
157
>*GdkPixbufLastUnref</A
158
>) (GdkPixbuf *pixbuf,
161
HREF="gdk-pixbuf-refcounting.html#GDK-PIXBUF-REF"
163
> (GdkPixbuf *pixbuf);
165
HREF="gdk-pixbuf-refcounting.html#GDK-PIXBUF-UNREF"
167
> (GdkPixbuf *pixbuf);
169
HREF="gdk-pixbuf-refcounting.html#GDK-PIXBUF-SET-LAST-UNREF-HANDLER"
170
>gdk_pixbuf_set_last_unref_handler</A
174
HREF="gdk-pixbuf-refcounting.html#GDKPIXBUFLASTUNREF"
175
>GdkPixbufLastUnref</A
177
gpointer last_unref_fn_data);
179
HREF="gdk-pixbuf-refcounting.html#GDK-PIXBUF-FINALIZE"
180
>gdk_pixbuf_finalize</A
181
> (GdkPixbuf *pixbuf);</PRE
194
> GdkPixbuf structures are reference counted. This means that
195
an application can share a single pixbuf among many parts of the
196
code. When a piece of the program needs to keep a pointer to a
197
pixbuf, it should add a reference to it. When it no longer needs
198
the pixbuf, it should subtract a reference. The pixbuf will be
199
destroyed when its reference count drops to zero. Newly-created
200
GdkPixbuf structures start with a reference count of one.
209
> a pixbuf means to free its pixel
210
data and to free the GdkPixbuf structure itself. Most of the
211
library functions that create GdkPixbuf structures create the
212
pixel data by themselves and define the way it should be freed;
213
you do not need to worry about those. The only function that lets
214
you specify how to free the pixel data is
216
HREF="gdk-pixbuf-creating.html#GDK-PIXBUF-NEW-FROM-DATA"
217
>gdk_pixbuf_new_from_data</A
218
>(). Since you pass it a pre-allocated
219
pixel buffer, you must also specify a way to free that data. This
220
is done with a function of type <A
221
HREF="gdk-pixbuf-refcounting.html#GDKPIXBUFDESTROYNOTIFY"
222
>GdkPixbufDestroyNotify</A
224
pixbuf created with <A
225
HREF="gdk-pixbuf-creating.html#GDK-PIXBUF-NEW-FROM-DATA"
226
>gdk_pixbuf_new_from_data</A
227
>() is finalized, your
228
destroy notification function will be called, and it is its
229
responsibility to free the pixel array.
232
> As an extension to traditional reference counting, GdkPixbuf
233
structures support defining a handler for the last unref
235
HREF="gdk-pixbuf-refcounting.html#GDK-PIXBUF-UNREF"
237
>() is called on a GdkPixbuf
238
structure that has a reference count of 1, i.e. its last
239
reference, then the pixbuf's last unref handler function will be
240
called. It is up to this function to determine whether to
241
finalize the pixbuf using <A
242
HREF="gdk-pixbuf-refcounting.html#GDK-PIXBUF-FINALIZE"
243
>gdk_pixbuf_finalize</A
245
continue execution. This can be used to implement a pixbuf cache
246
efficiently; please see the programmer's documentation for
264
NAME="GDKPIXBUFDESTROYNOTIFY"
266
>GdkPixbufDestroyNotify ()</H3
275
CLASS="PROGRAMLISTING"
276
>void (*GdkPixbufDestroyNotify) (guchar *pixels,
282
> A function of this type is responsible for freeing the pixel array
284
HREF="gdk-pixbuf-creating.html#GDK-PIXBUF-NEW-FROM-DATA"
285
>gdk_pixbuf_new_from_data</A
286
>() function lets you
287
pass in a pre-allocated pixel array so that a pixbuf can be
288
created from it; in this case you will need to pass in a function
290
HREF="gdk-pixbuf-refcounting.html#GDKPIXBUFDESTROYNOTIFY"
291
>GdkPixbufDestroyNotify</A
292
> so that the pixel data can be freed
293
when the pixbuf is finalized.
296
CLASS="INFORMALTABLE"
323
>The pixel array of the pixbuf that is being finalized.</TD
356
NAME="GDKPIXBUFLASTUNREF"
358
>GdkPixbufLastUnref ()</H3
367
CLASS="PROGRAMLISTING"
368
>void (*GdkPixbufLastUnref) (GdkPixbuf *pixbuf,
374
> A function of this type can be used to override the default
375
operation when a pixbuf loses its last reference, i.e. when
377
HREF="gdk-pixbuf-refcounting.html#GDK-PIXBUF-UNREF"
379
>() is called on a GdkPixbuf structure that has a
380
reference count of 1. This function should determine whether to
381
finalize the pixbuf by calling <A
382
HREF="gdk-pixbuf-refcounting.html#GDK-PIXBUF-FINALIZE"
383
>gdk_pixbuf_finalize</A
385
to just resume normal execution. The last unref handler for a
386
GdkPixbuf can be set using the
388
HREF="gdk-pixbuf-refcounting.html#GDK-PIXBUF-SET-LAST-UNREF-HANDLER"
389
>gdk_pixbuf_set_last_unref_handler</A
390
>() function. By default, pixbufs
391
will be finalized automatically if no last unref handler has been
395
CLASS="INFORMALTABLE"
422
>The pixbuf that is losing its last reference.</TD
455
NAME="GDK-PIXBUF-REF"
457
>gdk_pixbuf_ref ()</H3
466
CLASS="PROGRAMLISTING"
467
>GdkPixbuf* gdk_pixbuf_ref (GdkPixbuf *pixbuf);</PRE
472
>Adds a reference to a pixbuf. It must be released afterwards using
474
HREF="gdk-pixbuf-refcounting.html#GDK-PIXBUF-UNREF"
480
CLASS="INFORMALTABLE"
525
> The same as the <TT
545
NAME="GDK-PIXBUF-UNREF"
547
>gdk_pixbuf_unref ()</H3
556
CLASS="PROGRAMLISTING"
557
>void gdk_pixbuf_unref (GdkPixbuf *pixbuf);</PRE
562
>Removes a reference from a pixbuf. If this is the last reference for the
568
>, then its last unref handler function will be called; if no handler
569
has been defined, then the pixbuf will be finalized.</P
572
HREF="gdk-pixbuf-refcounting.html#GDK-PIXBUF-SET-LAST-UNREF-HANDLER"
573
>gdk_pixbuf_set_last_unref_handler</A
578
CLASS="INFORMALTABLE"
620
NAME="GDK-PIXBUF-SET-LAST-UNREF-HANDLER"
622
>gdk_pixbuf_set_last_unref_handler ()</H3
631
CLASS="PROGRAMLISTING"
632
>void gdk_pixbuf_set_last_unref_handler
635
HREF="gdk-pixbuf-refcounting.html#GDKPIXBUFLASTUNREF"
636
>GdkPixbufLastUnref</A
638
gpointer last_unref_fn_data);</PRE
643
>Sets the handler function for the <TT
648
>'s last unref handler. When
650
HREF="gdk-pixbuf-refcounting.html#GDK-PIXBUF-UNREF"
652
>() is called on this pixbuf and it has a reference count of
653
1, i.e. its last reference, then the last unref handler will be called. This
654
function should determine whether to finalize the pixbuf or just continue.
655
If it wishes to finalize the pixbuf, it should do so by calling
657
HREF="gdk-pixbuf-refcounting.html#GDK-PIXBUF-FINALIZE"
658
>gdk_pixbuf_finalize</A
662
HREF="gdk-pixbuf-refcounting.html#GDK-PIXBUF-FINALIZE"
663
>gdk_pixbuf_finalize</A
668
CLASS="INFORMALTABLE"
712
> Handler function for the last unref.</TD
722
>last_unref_fn_data</I
729
> Closure data to pass to the last unref handler function.</TD
744
NAME="GDK-PIXBUF-FINALIZE"
746
>gdk_pixbuf_finalize ()</H3
755
CLASS="PROGRAMLISTING"
756
>void gdk_pixbuf_finalize (GdkPixbuf *pixbuf);</PRE
761
>Finalizes a pixbuf by calling its destroy notification function to free the
762
pixel data and freeing the pixbuf itself. This function is meant to be
763
called only from within a <A
764
HREF="gdk-pixbuf-refcounting.html#GDKPIXBUFLASTUNREF"
765
>GdkPixbufLastUnref</A
766
> handler function, and the
772
> must have a reference count of 1, i.e. its last reference.</P
776
CLASS="INFORMALTABLE"
803
> A pixbuf with a reference count of 1.</TD
821
HREF="gdk-pixbuf-creating.html#GDK-PIXBUF-NEW-FROM-DATA"
822
>gdk_pixbuf_new_from_data</A
829
CLEAR="all"><BR><TABLE
841
HREF="gdk-pixbuf-gdk-pixbuf.html"
846
><<< Previous Page</B
895
HREF="gdk-pixbuf-file-loading.html"
900
>Next Page >>></B
913
>The GdkPixbuf Structure</B
b'\\ No newline at end of file'
added
removed
doc/html/gdk-pixbuf-refcounting.html
