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 aprropriate finalization code and free the memory. No user visible actions should take place, like destryoing windows, etc. GtkObjects also provide the following functions: *_destroy: Render an object `unusable', but as long as there are references to it, it's 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 explicitely 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 inital 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. 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 noops. 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_append (GTK_MENU (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 loplevel list and its ref_count * drops to zero. The destroy code of `window' destroyes `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' destroyes `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 performes 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 it's reference count to be decremented by one. */ gtk_widget_ref (widget); gtk_container_remove (container, widget); /* without the reference count, the widget would have been destroyed here. */ gtk_container_add (container, widget); gtk_widget_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) { gtk_widget_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; gtk_widget_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); Gnits to care about ------------------- On another note, though somewhat unrelated, the notification nature of the signal mechanism might cause events to be emitted that have their GdkWindow pointer set to NULL. This is due to the fact that certain events need to be emitted after the real GdkWindow of a widget is not any longer pertinent. It's up to the application to check for the window field of the event structure to be != NULL, if it is going to perform any operations through Gdk calls on it. Events that a likely to trigger a missing check for the window pointer currently are (and correspond to the trailing signals): GDK_SELECTION_CLEAR GtkWidget::selection_clear_event GDK_FOCUS_CHANGE GtkWidget::focus_in_event GtkWidget::focus_out_event Initial proposal: - Marius Vollmer Small fixups, "Taking care of proper referencing" and reference counting solution for GtkMenus: - Tim Janik