316 lines
12 KiB
Plaintext
316 lines
12 KiB
Plaintext
The Reference Counting Scheme of GDK an GTK+
|
|
============================================
|
|
|
|
Each data structure that provides reference counting offers a bunch of
|
|
functions that follow these conventions:
|
|
|
|
*_new: Create a new structure with a reference count of 1.
|
|
*_ref: Increase ref count by one.
|
|
*_unref: Decrease ref count by one. If the count drops to zero,
|
|
run appropriate finalization code and free the memory.
|
|
For data structures with a _destroy function, it will be
|
|
invoked at this point, if the data structure is not
|
|
already in a destroyed state.
|
|
|
|
GtkObjects also provide the following functions:
|
|
|
|
*_destroy: Render an object `unusable', but as long as there are
|
|
references to it, its allocated memory will not be freed.
|
|
*_sink: Clear a GtkObjects `floating' state and decrement the
|
|
reference count by 1.
|
|
|
|
GdkWindow
|
|
---------
|
|
|
|
A GdkWindow has to be explicitly destroyed with gdk_window_destroy.
|
|
This will send out a request to destroy this window and all its
|
|
children, and will decrement the ref_count of the GdkWindow by one.
|
|
Thus, it releases the initial reference created by gdk_window_new.
|
|
|
|
All GdkWindows are kept in a hash table to translate from their XId to
|
|
the actual structure and the pointer in the hash table is reflected in
|
|
the reference count. When a DestroyNotify event is received for a
|
|
particular GdkWindow, it is removed from the hash table and the
|
|
ref_count is updated accordingly.
|
|
|
|
You can call gdk_window_destroy more than once on a particular
|
|
GdkWindow, it will only be destroyed when it hasn't been yet. The
|
|
ref_count is *always* decremented, tho. Be careful.
|
|
|
|
Remark: When writing NO_WINDOW widgets, care should be taken about
|
|
proper referencing/unreferencing of the parent's GdkWindow
|
|
that is used by the widget.
|
|
|
|
GdkPixmap
|
|
---------
|
|
|
|
There is no gdk_pixmap_destroy function. The Pixmap is destroyed when
|
|
the last reference to it vanishes.
|
|
|
|
GdkPixmaps are kept in the same hash table as GdkWindows but the
|
|
pointer in the hash table is *not* reflected in the ref_count.
|
|
|
|
This works only when Pixmaps never get XEvents. I'm not sure if this
|
|
is the case.
|
|
|
|
GdkBitmap
|
|
---------
|
|
|
|
A GdkBitmap is only another name for a special use of GdkPixmap.
|
|
|
|
GdkVisual
|
|
---------
|
|
|
|
There are no *_new or *_destroy functions and the *_ref and *_unref
|
|
functions are no-ops. GdkVisuals are static structures and thus do not
|
|
need reference counting. The ref counting functions are only there
|
|
for extra defensive programming.
|
|
|
|
GdkColormap
|
|
-----------
|
|
|
|
Nothing special. There is no gdk_colormap_destroy function.
|
|
|
|
GdkFont / GdkFontSet
|
|
--------------------
|
|
|
|
GdkFont and GdkFontSet are equivalent as far as ref counting is
|
|
concerned. Use gdk_font_ref and gdk_font_unref for both.
|
|
|
|
There is no gdk_font_free or gdk_fontset_free function.
|
|
|
|
GtkAcceleratorTable
|
|
-------------------
|
|
|
|
There is no gtk_accelerator_table_destroy function.
|
|
|
|
GtkTooltips
|
|
-----------
|
|
|
|
There is no gtk_tooltips_destroy function.
|
|
|
|
GtkStyle
|
|
--------
|
|
|
|
There is no gtk_style_destroy function.
|
|
|
|
GtkObject
|
|
---------
|
|
|
|
GtkObjects follow the usual ref_counting strategy, but with a twist.
|
|
|
|
They are created with a ref_count of 1. GtkObjects are able to
|
|
run finalization code when the ref_count drops to zero but you cannot
|
|
register arbitrary signal handlers to run at finalization time.
|
|
|
|
There is also the old gtk_object_destroy function and the "destroy"
|
|
signal but they are somewhat independent from finalization. Just as
|
|
stated at the top of this text, gtk_object_destroy merely renders an
|
|
object unusable. When the object is a container widget for example,
|
|
it unrealizes that widget, removes all children and disconnects all
|
|
signal handlers. The finalization code is different, it would for
|
|
example free associated memory for text strings and release the
|
|
attached style.
|
|
|
|
This is the biggest change. Every widget must be revised to have a
|
|
proper "destroy" function, etc. Such a destroy function will only
|
|
be called once and is expected to leave the widget in a minimal but
|
|
consistent state. Widgets that have been "destroyed" but not yet
|
|
finalized are flagged with GTK_DESTROY. The "finalization" function
|
|
is new and should perform last-minute cleanup actions, in contrast
|
|
to the destroy function it will not be emitted as signal though.
|
|
It can assume that the "destroy" function has been called as the
|
|
last function on this widget.
|
|
|
|
Essentially, the old "destroy" function has been split into a
|
|
"finalize" plus a "destroy" function.
|
|
|
|
It is not possible to create GtkObjects with a ref_count of 0
|
|
because the first ref/unref pair will destroy it unintentionally.
|
|
|
|
To be mostly backward compatible with existing practice, a GtkObject
|
|
leads a more complicated life than the other reference counted structures.
|
|
|
|
When a GtkObject is created, it starts out in a special state called
|
|
"floating" (this is the twist). This means that it is alive and has a
|
|
reference to it, but the `owner' of this reference is not known.
|
|
There are certain `potential owners' that will adopt a floating
|
|
GtkObject. For GtkWidgets the most common adopters are the parent
|
|
widget.
|
|
|
|
When you want to adopt a possibly floating GtkObject, you call
|
|
gtk_object_sink on it. This clears the floating state of the
|
|
GtkObject and decrements the ref_count by one, if it has been floating
|
|
previously. Once the floating state has been cleared, it will never
|
|
be set again.
|
|
|
|
All widgets that are part of the display are linked into a
|
|
parent/child tree. The link from the parent to a child is reflected
|
|
in the ref_count of the child, but the link from the child to the
|
|
parent is not reflected in the ref_count of the parent.
|
|
|
|
Like a GtkObject, a GtkWidget is created with a ref_count of 1 and
|
|
initially flagged as `floating'. As soon as it is added as a child to
|
|
a parent, the `floating' flag is cleared and never will be set again.
|
|
Not even when it is later unparented. The act of clearing the
|
|
`floating' flag also decrements the ref_count of the widget by one.
|
|
|
|
When the widget is unparented, its underlying GdkWindow is destroyed
|
|
(when it has one), it loses its reference from the parent and
|
|
naturally the ref_count is decremented.
|
|
|
|
It is considered a bug if a widget still has a GdkWindow when it is
|
|
being freed.
|
|
|
|
Toplevel widgets, which don't have a `natural' parent, are adopted by
|
|
special registering functions. Because the of the reference count that
|
|
is set by the registering functions, toplevel widgets will have to be
|
|
explicitly destroyed, with the exception of GtkMenus. GtkMenus are a
|
|
special case of toplevel widgets in that they will be `attached' to and
|
|
`detached' from other widgets. The act of attaching a GtkMenu to a
|
|
widget will be reflected in its reference count. The act of detaching
|
|
a GtkMenu will revert that. Therefore GtkMenus naturally get destroyed
|
|
and finalized once they are detached from their reference holder.
|
|
|
|
So, the typical career of a GtkWindow a GtMenu attached to a
|
|
GtkOptionMenu looks like this:
|
|
|
|
window = gtk_window_new (GTK_WINDOW_TOPLEVEL);
|
|
/* window is created with ref_count == 1. It is not flagged as
|
|
* `floating' because it has already been registered as a toplevel
|
|
* widget.
|
|
*/
|
|
|
|
option_menu = gtk_option_menu_new ();
|
|
/* option_menu->ref_count == 1 and it is flagged as `floating'.
|
|
*/
|
|
|
|
gtk_container_add (window, option_menu);
|
|
/* option_menu->ref_count still == 1, but it is no longer `floating'.
|
|
*/
|
|
|
|
menu = gtk_menu_new ();
|
|
/* menu->ref_count == 1 and it is flagged as `floating'.
|
|
*/
|
|
|
|
menu_item = gtk_menu_item_new_with_label ("Choose Me");
|
|
/* menu_item->ref_count == 1 and it is flagged as `floating'.
|
|
*/
|
|
|
|
gtk_menu_shell_append (GTK_MENU_SHELL (menu), menu_item);
|
|
/* menu_item->ref_count still == 1, but it is no longer `floating'.
|
|
*/
|
|
|
|
gtk_option_menu_set_menu (GTK_OPTION_MENU (option_menu), menu);
|
|
/* menu->ref_count still == 1, but it is no longer `floating'.
|
|
*/
|
|
|
|
gtk_widget_show (menu_item);
|
|
gtk_widget_show (option_menu);
|
|
gtk_widget_show (window);
|
|
|
|
/* The widgets get their GdkWindows, nothing significant happens to
|
|
* the ref_counts.
|
|
*/
|
|
|
|
Then, when the user wants to get rid of the window:
|
|
|
|
gtk_widget_destroy (window);
|
|
|
|
/* The GdkWindow of `window' and all its child GdkWindows are
|
|
* destroyed.
|
|
*
|
|
* window is unregistered from the toplevel list and its ref_count
|
|
* drops to zero. The destroy code of `window' destroys `option_menu'.
|
|
*
|
|
* The destroy code of `option_menu' causes the `menu' to be detached
|
|
* from it and its reference count drops to zero.
|
|
*
|
|
* The destroy code of `menu' destroys `menu_item'.
|
|
*
|
|
* The destruction of `menu_item' removes it from its parent, the
|
|
* menu_item->ref_count drops to zero and `menu_item' is finalized (freed).
|
|
*
|
|
* Now `menu', `option_menu' and `window' will be destroyed and finalized,
|
|
* in this order, since the reference count of each is zero.
|
|
*/
|
|
|
|
|
|
Taking care of proper referencing
|
|
---------------------------------
|
|
|
|
There are some cases where referencing of widgets from outside the toolkit
|
|
(on the application side) is needed.
|
|
Once the application performs an operation on a widget that will cause
|
|
its reference count to drop, if it wants to take further actions on the
|
|
widget, it needs to hold a reference to it.
|
|
|
|
Example code sequences that require reference wraps:
|
|
|
|
/* gtk_container_remove() will unparent the child and therefore
|
|
* cause its reference count to be decremented by one.
|
|
*/
|
|
g_object_ref (widget);
|
|
gtk_container_remove (container, widget);
|
|
/* without the reference count, the widget would have been destroyed here.
|
|
*/
|
|
gtk_container_add (container, widget);
|
|
g_object_unref (widget);
|
|
|
|
|
|
/* all items in item_list need to be referenced
|
|
* before gtk_list_remove_items() is invoked.
|
|
* this is somewhat tricky as gtk_list_append_items/gtk_list_prepend_items/
|
|
* gtk_list_insert_items will take over the lists nodes.
|
|
* we therefore have an extra GSList `*slist' for later unreferencing.
|
|
*/
|
|
slist = NULL;
|
|
for (list = item_list; list; list = list->next)
|
|
{
|
|
g_object_ref (GTK_WIDGET (list->data));
|
|
slist = g_slist_prepend (slist, list->data);
|
|
}
|
|
gtk_list_remove_items (list, item_list);
|
|
gtk_list_append_items (other_list, item_list);
|
|
/* gtk_list_prepend_items (other_list, item_list); */
|
|
/* gtk_list_insert_items (other_list, item_list, 3); */
|
|
while (slist)
|
|
{
|
|
GSList *tmp;
|
|
|
|
tmp = slist;
|
|
slist = slist->next;
|
|
g_object_unref (GTK_WIDGET (tmp->data));
|
|
g_slist_free_1 (tmp);
|
|
}
|
|
|
|
/* Alternatively to the removal above you could just use
|
|
* gtk_list_remove_items_no_unref() which will add the additional
|
|
* reference count to the widget.
|
|
*/
|
|
gtk_list_remove_items_no_unref (list, item_list);
|
|
gtk_list_prepend_items (other_list, item_list);
|
|
|
|
|
|
Now a (hopefully) complete list of functions that require
|
|
wrappers similar to the examples above:
|
|
|
|
void gtk_container_remove (GtkContainer *container,
|
|
GtkWidget *widget);
|
|
void gtk_list_remove_items (GtkList *list,
|
|
GList *items);
|
|
void gtk_tree_remove_items (GtkTree *tree,
|
|
GList *items);
|
|
void gtk_tree_item_remove_subtree (GtkTreeItem *tree_item);
|
|
void gtk_menu_item_remove_submenu (GtkMenuItem *menu_item);
|
|
void gtk_option_menu_remove_menu (GtkOptionMenu *option_menu);
|
|
|
|
|
|
|
|
Initial proposal:
|
|
- Marius Vollmer <mvo@zagadka.ping.de>
|
|
|
|
Some modifications/additions, "Taking care of proper referencing" and
|
|
reference counting solution for GtkMenus:
|
|
- Tim Janik <timj@gimp.org>
|