diff --git a/docs/reference/ChangeLog b/docs/reference/ChangeLog index 1720ba249..9b881ec30 100644 --- a/docs/reference/ChangeLog +++ b/docs/reference/ChangeLog @@ -1,3 +1,8 @@ +Fri Feb 16 06:52:20 2001 Tim Janik + + * gobject/tmpl/types.sgml: incorporated huge docu patch from Eric + Lemings with a bunch of editing on my part. + Mon Feb 12 12:42:45 2001 Owen Taylor * {glib,gobject}/Makefile.am: The ultimate gtk-doc makefile. diff --git a/docs/reference/gobject/tmpl/types.sgml b/docs/reference/gobject/tmpl/types.sgml index 3c9e3abdb..23c92a1e0 100644 --- a/docs/reference/gobject/tmpl/types.sgml +++ b/docs/reference/gobject/tmpl/types.sgml @@ -22,6 +22,15 @@ Dynamic types are created with g_type_register_dynamic() which takes a #GTypePlugin structure instead. The remaining type information (the #GTypeInfo structure) is retrived during runtime through #GTypePlugin and the g_type_plugin_*() API. +These registration functions are usually called only once from a +function whose only purpose is to return the type identifier for a +specific class. Once the type (or class or interface) is registered, +it may be instantiated, inherited, or implemented depending on exactly +what sort of type it is. +There is also a third registration function for registering fundamental +types called g_type_register_fundamental() which requires both a #GTypeInfo +structure and a GTypeFundamentalInfo structure but it is seldom used +since most fundamental types are predefined rather than user-defined. @@ -43,7 +52,7 @@ Returns #TRUE if @type is a fundamental data type such as #G_TYPE_INT or the derived types, thus they are the roots of distinct inheritance heirachies. -@type: a #GType value +@type: A #GType value. @@ -103,7 +112,7 @@ types). - +Returns #TRUE if @type is a fundamental type. @type: A #GType value. @@ -119,7 +128,7 @@ types). - +Returns #TRUE if @type is a classed type. @type: A #GType value. @@ -136,7 +145,8 @@ process of creating an instance (object) of this type. - +Returns #TRUE if @type is a derivable type. A derivable type can +be used as the base class of a flat (single-level) class hierarchy. @type: A #GType value. @@ -144,7 +154,8 @@ process of creating an instance (object) of this type. - +Returns #TRUE if @type is a deep derivable type. A deep derivable type +can be used as the base class of a deep (multi-level) class hierarchy. @type: A #GType value. @@ -155,7 +166,8 @@ process of creating an instance (object) of this type. Returns #TRUE if @type is an interface type. Interface types are types that provide pure APIs, the implementation of which is provided by another type (which is then said to conform -to the interface). +to the interface). GLib interfaces are somewhat analogous to Java +interfaces and C++ classes containing only pure virtual functions. @type: A #GType value. @@ -163,63 +175,63 @@ to the interface). - +The predefined identifiers of the reserved fundamental types. -@G_TYPE_INVALID: -@G_TYPE_NONE: -@G_TYPE_INTERFACE: -@G_TYPE_CHAR: -@G_TYPE_UCHAR: -@G_TYPE_BOOLEAN: -@G_TYPE_INT: -@G_TYPE_UINT: -@G_TYPE_LONG: -@G_TYPE_ULONG: -@G_TYPE_ENUM: -@G_TYPE_FLAGS: -@G_TYPE_FLOAT: -@G_TYPE_DOUBLE: -@G_TYPE_STRING: -@G_TYPE_PARAM: -@G_TYPE_BOXED: -@G_TYPE_POINTER: -@G_TYPE_CCALLBACK: -@G_TYPE_OBJECT: -@G_TYPE_GTK_SIGNAL: -@G_TYPE_BSE_PROCEDURE: -@G_TYPE_BSE_TIME: -@G_TYPE_BSE_NOTE: -@G_TYPE_BSE_DOTS: -@G_TYPE_GLE_GOBJECT: -@G_TYPE_LAST_RESERVED_FUNDAMENTAL: -@G_TYPE_PARAM_CHAR: -@G_TYPE_PARAM_UCHAR: -@G_TYPE_PARAM_BOOLEAN: -@G_TYPE_PARAM_INT: -@G_TYPE_PARAM_UINT: -@G_TYPE_PARAM_LONG: -@G_TYPE_PARAM_ULONG: -@G_TYPE_PARAM_ENUM: -@G_TYPE_PARAM_FLAGS: -@G_TYPE_PARAM_FLOAT: -@G_TYPE_PARAM_DOUBLE: -@G_TYPE_PARAM_STRING: -@G_TYPE_PARAM_PARAM: -@G_TYPE_PARAM_POINTER: -@G_TYPE_PARAM_CCALLBACK: -@G_TYPE_PARAM_BOXED: -@G_TYPE_PARAM_OBJECT: +@G_TYPE_INVALID: Usually a return value indicating an error. +@G_TYPE_NONE: A synonym for the "void" type in C. +@G_TYPE_INTERFACE: Root type of all interface types. +@G_TYPE_CHAR: Identifier for the built-in type "gchar". +@G_TYPE_UCHAR: Identifier for the built-in type "guchar". +@G_TYPE_BOOLEAN: Identifier for the built-in type "gboolean". +@G_TYPE_INT: Identifier for the built-in type "gint". +@G_TYPE_UINT: Identifier for the built-in type "guint". +@G_TYPE_LONG: Identifier for the built-in type "glong". +@G_TYPE_ULONG: Identifier for the built-in type "gulong". +@G_TYPE_ENUM: Identifier for the "#GEnum" type. +@G_TYPE_FLAGS: Identifier for the "#GFlags" type. +@G_TYPE_FLOAT: Identifier for the built-in type "gfloat". +@G_TYPE_DOUBLE: Identifier for the built-in type "gdouble". +@G_TYPE_STRING: Identifier for a pointer to a null-terminated string "gchar*". +@G_TYPE_PARAM: Identifier for the "#GParam" type. +@G_TYPE_BOXED: Identifier for the "#GBoxed" type. +@G_TYPE_POINTER: Identifier for anonymous pointers "void*". +@G_TYPE_CCALLBACK: Identifier for a pointer to a C function. +@G_TYPE_OBJECT: Identifier for the "#GObject" type. +@G_TYPE_GTK_SIGNAL: Reserved for use by the Gtk+ software package. +@G_TYPE_BSE_PROCEDURE: Reserved for use by the BSE software package. +@G_TYPE_BSE_TIME: Reserved for use by the BSE software package. +@G_TYPE_BSE_NOTE: Reserved for use by the BSE software package. +@G_TYPE_BSE_DOTS: Reserved for use by the BSE software package. +@G_TYPE_GLE_GOBJECT: Reserved for use by the GLE software package. +@G_TYPE_LAST_RESERVED_FUNDAMENTAL: New third-party fundamental types have to use IDs higher than this. +@G_TYPE_PARAM_CHAR: Identifier for the "#GParamSpecChar" type. +@G_TYPE_PARAM_UCHAR: Identifier for the "#GParamSpecUChar" type. +@G_TYPE_PARAM_BOOLEAN: Identifier for the "#GParamSpecBoolean" type. +@G_TYPE_PARAM_INT: Identifier for the "#GParamSpecInt" type. +@G_TYPE_PARAM_UINT: Identifier for the "#GParamSpecUInt" type. +@G_TYPE_PARAM_LONG: Identifier for the "#GParamSpecLong" type. +@G_TYPE_PARAM_ULONG: Identifier for the "#GParamSpecULong" type. +@G_TYPE_PARAM_ENUM: Identifier for the "#GParamSpecEnum" type. +@G_TYPE_PARAM_FLAGS: Identifier for the "#GParamSpecFlags" type. +@G_TYPE_PARAM_FLOAT: Identifier for the "#GParamSpecFloat" type. +@G_TYPE_PARAM_DOUBLE: Identifier for the "#GParamSpecDouble" type. +@G_TYPE_PARAM_STRING: Identifier for the "#GParamSpecString" type. +@G_TYPE_PARAM_PARAM: Identifier for the "#GParamSpecParam" type. +@G_TYPE_PARAM_POINTER: Identifier for the "#GParamSpecPointer" type. +@G_TYPE_PARAM_CCALLBACK: Identifier for the "#GParamSpecCCallback" type. +@G_TYPE_PARAM_BOXED: Identifier for the "#GParamSpecBoxed" type. +@G_TYPE_PARAM_OBJECT: Identifier for the "#GParamSpecObject" type. - +An opaque structure used as the base of all interface types. - +An opaque structure used as the base of all type instances. @@ -237,31 +249,34 @@ across invocation of g_type_register_static(). @class_size: Size of the class structure (required for interface, classed and instantiatable types). @base_init: Location of the base initialization function (optional). -@base_finalize: Location of the base finalization function (optional). +@base_finalize: Location of the base finalization function (optional). @class_init: Location of the class initialization function (optional, for classed and instantiatable types only). @class_finalize: Location of the class finalization function (optional). @class_data: User-supplied data passed to the class init/finalize functions. -@instance_size: Size of the instance (object) structure (required for instantiatable types only). +@instance_size: Size of the instance (object) structure (required for instantiatable types only). @n_preallocs: Number of pre-allocated (cached) instances to reserve memory for (0 indicates no caching). -@instance_init: The location of the instance initialization function (optional, for instantiatable types only). +@instance_init: Location of the instance initialization function (optional, for instantiatable types only). @value_table: Function table for generic handling of GValues of this type (usualy only usefull for fundamental types). - +A structure that provides information to the type system which is +used specifically for managing fundamental types. @type_flags: - +A structure that provides information to the type system which is +used specifically for managing interface types. -@interface_init: -@interface_finalize: -@interface_data: +@interface_init: Location of the function that initializes the interface. +@interface_finalize: Location of the function that finalizes the interface. +@interface_data: Location of user data passed to the @interface_init and + @interface_finalize functions (optional). @@ -279,36 +294,37 @@ across invocation of g_type_register_static(). - +Returns the type identifier from a given @instance structure. -@instance: +@instance: Location of a valid #GTypeInstance structure. - +Returns the type identifier from a given @class structure. -@g_class: +@g_class: Location of a valid #GTypeClass structure. - +Returns the type identifier from a given @interface structure. -@g_iface: +@g_iface: Location of a valid #GTypeInterface structure. - +Returns the class structure of a given @instance, casted +to a specified anchestor type @g_type of the instance. -@instance: -@g_type: -@c_type: +@instance: Location of the #GTypeInstance structure. +@g_type: The anchestor type of the class to be returned. +@c_type: The corresponding C type of @g_Type. @@ -398,7 +414,7 @@ the type system and assorted other code portions (such as the various fundamenta type implementations or the signal system). -@debug_flags: +@debug_flags: Bitwise combination of #GTypeDebugFlags values for debugging purposes. @@ -476,37 +492,56 @@ Check whether @type is a descendant of @is_a_type. - +Increments the reference count of the class structure belonging to +@type. This function will demand-create the class if it doesn't +exist already. -@type: -@Returns: +@type: Type ID of a classed type. +@Returns: The #GTypeClass structure for the given type ID. - +This function is essentially the same as g_type_class_ref(), except that +the classes reference count isn't incremented. Therefore, this function +may return NULL if the class of the type passed in does not currently +exist (hasn't been referenced before). -@type: -@Returns: +@type: Type ID of a classed type. +@Returns: The #GTypeClass structure for the given type ID or NULL + if the class does not currently exist. - +Decrements the reference count of the class structure being passed in. +Once the last reference count of a class has been released, classes +may be finalized by the type system, so further dereferencing of a +class pointer after g_type_class_unref() are invalid. -@g_class: +@g_class: The #GTypeClass structure to unreference. +This is a convenience function, often needed in class intializers. +It essentially takes the immediate parent type of the class passed in, +and returns the class structure thereof. Since derived classes hold +a reference count on their parent classes as long as they are instantiated, +the returned class will always exist. This function is essentially +equivalent to: + + +g_type_class_peek (g_type_parent (G_TYPE_FROM_CLASS (g_class))); + -@g_class: -@Returns: +@g_class: The #GTypeClass structure to retrive the parent class for. +@Returns: The parent class of @g_class. @@ -564,63 +599,187 @@ g_free()ed after use. - +A callback function used by the type system to do base initialization +of the class structures of derived types. It is called as part of the +initialization process of all derived classes and should reallocate +or reset all dynamic class members copied over from the parent class. +Therefore class members, e.g. strings, that are not sufficiently +handled by a plain memory copy of the parent class into the derived class +have to be altered. See GClassInitFunc() for a discussion of the class +intialization process. -@g_class: +@g_class: The #GTypeClass structure to initialize. - +A callback function used by the type system to finalize those portions +of a derived types class structure that were setup from the corresponding +GBaseInitFunc() function. Class finalization basically works the inverse +way in which class intialization is performed. +See GClassInitFunc() for a discussion of the class intialization process. -@g_class: +@g_class: The #GTypeClass structure to finalize. +A callback function used by the type system to initialize the class +of a specific type. This function should initialize all static class +members. +The initialization process of a class involves: + + + 1 - Copying common members from the parent class over to the + derived class structure. + + + 2 - Zero initialization of the remaining members not copied + over from the parent class. + + + 3 - Invocation of the GBaseInitFunc initializers of all parent + types and the class' type. + + + 4 - Invocation of the class' GClassInitFunc initializer. + + +Since derived classes are partially initialized through a memory copy +of the parent class, the general rule is that GBaseInitFunc() and +GBaseFinalizeFunc() should take care of necessary reinitialization +and release of those class members that were introduced by the type +that specified these GBaseInitFunc()/GBaseFinalizeFunc(). +GClassInitFunc() should only care about intializing static +class members, while dynamic class members (such as allocated strings +or reference counted resources) are better handled by a GBaseInitFunc() +for this type, so proper initialization of the dynamic class members +are performed for class intialization of derived types as well. +An example may help to corrsepond the intend of the different class +initializers: + +typedef struct { + GObjectClass parent_class; + gint static_integer; + gchar *dynamic_string; +} TypeAClass; +static void +type_a_base_class_init (TypeAClass *class) +{ + class->dynamic_string = g_strdup ("some string"); +} +static void +type_a_base_class_finalize (TypeAClass *class) +{ + g_free (class->dynamic_string); +} +static void +type_a_class_init (TypeAClass *class) +{ + class->static_integer = 42; +} + +typedef struct { + TypeAClass parent_class; + gfloat static_float; + GString *dynamic_gstring; +} TypeBClass; +static void +type_b_base_class_init (TypeBClass *class) +{ + class->dynamic_gstring = g_string_new ("some other string); +} +static void +type_b_base_class_finalize (TypeBClass *class) +{ + g_string_free (class->dynamic_gstring); +} +static void +type_b_class_init (TypeBClass *class) +{ + class->static_float = 3.14159265358979323846; +} + +Initialization of TypeBClass will first cause initialization of +TypeAClass (derived classes reference their parent classes, see +g_type_class_ref() on this). +Initialization of TypeAClass roughly involves zero-intializing its fields, +then calling its GBaseInitFunc() type_a_base_class_init() that allocates +its dynamic members (dynamic_string) and finally calling its GClassInitFunc() +type_a_class_init() to initialize its static members (static_integer). +The first step in the initialization process of TypeBClass is then +a plain memory copy of the contents of TypeAClass into TypeBClass and +zero intialization of the remaining fields in TypeBClass. +The dynamic members of TypeAClass within TypeBClass now need +reinitialization which is performed by calling type_a_base_class_init() +with an argument of TypeBClass. +After that, the GBaseInitFunc() of TypeBClass, type_b_base_class_init() +is called to allocate the dynamic members of TypeBClass (dynamic_gstring), +and finally the GClassInitFunc() of TypeBClass, type_b_class_init(), +is called to complete the initialization process with the static members +(static_float). +Corresponding finalization counter parts to the GBaseInitFunc() functions +have to be provided to release allocated resources at class finalization +time. -@g_class: -@class_data: +@g_class: The #GTypeClass structure to initialize. +@class_data: The @class_data member supplied via the #GTypeInfo structure. - +A callback function used by the type system to finalize a class. +This function is rarely needed, as dynamically allocated class resources +should be handled by GBaseInitFunc() and GBaseFinalizeFunc(). +Also, specification of a GClassFinalizeFunc in the #GTypeInfo +structure of a static type is invalid, because classes of static types +will never be finalized (they are artificially kept alive when their +reference count drops to zero). -@g_class: -@class_data: +@g_class: The #GTypeClass structure to finalize. +@class_data: The @class_data member supplied via the #GTypeInfo structure. - +A callback function used by the type system to initialize a new +instance of a type. This function initializes all instance members and +allocates any resources require by it. +Initialization of a derived instance involves calling all its parent +types instance initializers, therefore the class member of the instance +is altered during its initialization to always point to the class that +belongs to the type the current initializer was introduced for. -@instance: -@g_class: +@instance: The instance to initialize. +@g_class: The class of the type the instance is created for. - +A callback function used by the type system to initialize a new +interface. This function should initialize all internal data and +allocate any resources required by the interface. -@g_iface: -@iface_data: +@g_iface: The interface structure to initialize. +@iface_data: The @class_data supplied via the #GTypeInfo structure. - +A callback function used by the type system to finalize an interface. +This function should destroy any internal data and release any resources +allocated by the corresponding GInterfaceInitFunc() function. -@g_iface: -@iface_data: +@g_iface: The interface structure to finalize. +@iface_data: The @class_data supplied via the #GTypeInfo structure. @@ -635,71 +794,90 @@ g_free()ed after use. - +Bit masks used to check or determine characteristics of a type. -@G_TYPE_FLAG_ABSTRACT: +@G_TYPE_FLAG_ABSTRACT: Indicates an abstract type. No instances can be + created for an abstract type. - +Bit masks used to check or determine specific characteristics of a +fundamental type. -@G_TYPE_FLAG_CLASSED: -@G_TYPE_FLAG_INSTANTIATABLE: -@G_TYPE_FLAG_DERIVABLE: -@G_TYPE_FLAG_DEEP_DERIVABLE: +@G_TYPE_FLAG_CLASSED: Indicates a classed type. +@G_TYPE_FLAG_INSTANTIATABLE: Indicates an instantiable type (implies classed). +@G_TYPE_FLAG_DERIVABLE: Indicates a flat derivable type. +@G_TYPE_FLAG_DEEP_DERIVABLE: Indicates a deep derivable type (implies derivable). - +Registers @type_name as the name of a new static type derived from +@parent_type. The type system uses the information contained in the +#GTypeInfo structure pointed to by @info to manage the type and its +instances (if not abstract). The value of @flags determines the nature +(e.g. abstract or not) of the type. -@parent_type: -@type_name: -@info: -@flags: -@Returns: +@parent_type: Type which this type will be derived from. +@type_name: Null-terminated string used as the name of the new type. +@info: The #GTypeInfo structure for this type. +@flags: Bitwise combination of #GTypeFlags values. +@Returns: The new type identifier. - +Registers @type_name as the name of a new dynamic type derived from +@parent_type. The type system uses the information contained in the +#GTypePlugin structure pointed to by @plugin to manage the type and its +instances (if not abstract). The value of @flags determines the nature +(e.g. abstract or not) of the type. -@parent_type: -@type_name: -@plugin: -@flags: -@Returns: +@parent_type: Type which this type will be derived from. +@type_name: Null-terminated string used as the name of the new type. +@plugin: The #GTypePlugin structure to retrive the #GTypeInfo from. +@flags: Bitwise combination of #GTypeFlags values. +@Returns: The new type identifier. + +@Returns: #G_TYPE_INVALID if registration failed or the new type identifier. - +Registers @type_id as the predefined identifier and @type_name as the +name of a fundamental type. The type system uses the information +contained in the #GTypeInfo structure pointed to by @info and the +#GTypeFundamentalInfo structure pointed to by @finfo to manage the +type and its instances. The value of @flags determines additional +characteristics of the funamental type. -@type_id: -@type_name: -@info: -@finfo: -@flags: -@Returns: +@type_id: A predefined #GTypeFundamentals value. +@type_name: Null-terminated string used as the name of the new type. +@info: The #GTypeInfo structure for this type. +@finfo: The #GTypeFundamentalInfo structure for this type. +@flags: Bitwise combination of #GTypeFlags values. +@Returns: The predefined type identifier. - +Adds the static @interface_type to @instantiable_type. The information +contained in the #GTypeInterfaceInfo structure pointed to by @info +is used to manage the relationship. -@instance_type: -@interface_type: -@info: +@instance_type: #GType value of an instantiable type. +@interface_type: #GType value of an interface type. +@info: The #GInterfaceInfo structure for this + (@instance_type, @interface_type) combination. - @instance_type: @@ -709,16 +887,17 @@ g_free()ed after use. - +Returns the the #GTypePlugin structure for @type or +#NULL if @type does not have a #GTypePlugin structure. -@type: -@Returns: +@type: The #GType to retrive the plugin for. +@Returns: The corresponding plugin if @type is a dynamic type, + NULL otherwise. - @instance_type: @@ -728,34 +907,44 @@ g_free()ed after use. - +Returns the last fundamental type which is registered plus one, +i.e. the next fundamental type ID that may be registered. -@Returns: +@Returns: The nextmost not registered fundamental type ID. - +Determines whether a given set of #GTypeFlags and #GTypeFundamentalFlags +are set for @type. -@type: -@flags: -@Returns: +@type: The type to check for flags. +@flags: Bitwise combination of #GTypeFlags and #GTypeFundamentalFlags. +@Returns: #TRUE if all @flags are set for @type, #FALSE otherwise. - +Creates and initializes an instance of @type if @type is valid and can +be instantiated. The type system only performs basic allocation and +structure setups for instances, actuall instance creation should happen +through functions supplied by the types fundamental type implementation. +So use of g_type_create_instance() is reserved for implementators of +fundamental types only. E.g. instances of the #GObject heirachy +should be created via g_object_new() and never +directly through g_type_create_instance() which doesn't handle +things like singleton objects or object construction. -@type: -@Returns: +@type: An instantiabtable type to create an instance for. +@Returns: An allocated and initialized instance, subject to further + treatment by the fundamental type implementation. - @instance: @@ -789,16 +978,16 @@ g_free()ed after use. - +Private helper function to aid implementation of the G_TYPE_CHECK_INSTANCE() +macro. -@instance: -@Returns: +@instance: A valid #GTypeInstance structure. +@Returns: #TRUE if @instance is valid, #FALSE otherwise. - @instance: @@ -808,17 +997,19 @@ g_free()ed after use. - +Determines if @instance adhears to the interface exported +by @iface_type. @iface_type is eitehr a type that @instance +is derived from, or an interface type that is suppoted by +the anchestry of @instance. -@instance: -@iface_type: -@Returns: +@instance: A valid #GTypeInstance structure. +@iface_type: A #GType value. +@Returns: #TRUE if @instance conforms to @iface_type, #FALSE otherwise. - @g_class: @@ -828,7 +1019,6 @@ g_free()ed after use. - @g_class: @@ -838,7 +1028,6 @@ g_free()ed after use. - @value: @@ -847,20 +1036,24 @@ g_free()ed after use. - +Determines if @value is a #GValue whose type conforms to @type. -@value: -@type: -@Returns: +@value: A valid #GValue structure. +@type: A #GType value. +@Returns: #TRUE if @value is a #GValue of @type or #FALSE if not. - +Returns the location of the #GTypeValueTable associated with @type. +Note, this function should only be used from source code +that implements or has internal knowledge of the implementation of +@type. -@type: -@Returns: +@type: A #GType value. +@Returns: Location of the #GTypeValueTable associated with @type or + #NULL if there is no #GTypeValueTable associated with @type. diff --git a/gobject/ChangeLog b/gobject/ChangeLog index 2f75fe124..70e850a02 100644 --- a/gobject/ChangeLog +++ b/gobject/ChangeLog @@ -1,3 +1,19 @@ +Fri Feb 16 07:10:44 2001 Tim Janik + + * gclosure.c: + (g_closure_ref): + (g_closure_sink): make closure sinking explicit. + + * gsignal.c: + (g_signal_connect_data): + (g_signal_connect_closure): + (g_signal_connect_closure_by_id): + (g_signal_newv): perform explicit closure sinking. + +Thu Feb 8 00:31:45 2001 Tim Janik + + * gtype.h: added G_TYPE_DEBUG_NONE for/from Eric Lemings ;) + 2001-02-04 Tor Lillqvist * gobject.def: Remove glib_debug_objects. diff --git a/gobject/gclosure.c b/gobject/gclosure.c index d303f2b44..5b386d6b8 100644 --- a/gobject/gclosure.c +++ b/gobject/gclosure.c @@ -311,14 +311,7 @@ g_closure_ref (GClosure *closure) g_return_val_if_fail (closure->ref_count > 0, NULL); g_return_val_if_fail (closure->ref_count < CLOSURE_MAX_REF_COUNT, NULL); - /* floating is basically a kludge to avoid creating closures - * with a ref_count of 0. so the first one doing _ref() will - * own the closure's initial ref_count - */ - if (closure->floating) - closure->floating = FALSE; - else - closure->ref_count += 1; + closure->ref_count += 1; return closure; } @@ -356,6 +349,27 @@ g_closure_unref (GClosure *closure) } } +void +g_closure_sink (GClosure *closure) +{ + g_return_if_fail (closure != NULL); + g_return_if_fail (closure->ref_count > 0); + + /* floating is basically a kludge to avoid creating closures + * with a ref_count of 0. so the intial ref_count a closure has + * is unowned. with invoking g_closure_sink() code may + * indicate that it takes over that intiial ref_count. + */ + if (closure->floating) + { + closure->floating = FALSE; + if (closure->ref_count > 1) + closure->ref_count -= 1; + else + g_closure_unref (closure); + } +} + void g_closure_remove_inotify (GClosure *closure, gpointer notify_data, diff --git a/gobject/gclosure.h b/gobject/gclosure.h index c3ff79357..df766413a 100644 --- a/gobject/gclosure.h +++ b/gobject/gclosure.h @@ -112,6 +112,7 @@ GClosure* g_signal_type_cclosure_new (GType itype, /* --- prototypes --- */ GClosure* g_closure_ref (GClosure *closure); +void g_closure_sink (GClosure *closure); void g_closure_unref (GClosure *closure); /* intimidating */ GClosure* g_closure_new_simple (guint sizeof_closure, diff --git a/gobject/gsignal.c b/gobject/gsignal.c index 827f64014..abdd927e6 100644 --- a/gobject/gsignal.c +++ b/gobject/gsignal.c @@ -1047,6 +1047,8 @@ g_signal_newv (const gchar *signal_name, node->param_types = g_memdup (param_types, sizeof (GType) * n_params); node->return_type = return_type; node->class_closure = class_closure ? g_closure_ref (class_closure) : NULL; + if (class_closure) + g_closure_sink (class_closure); node->accumulator = accumulator; node->c_marshaller = c_marshaller; node->emission_hooks = NULL; @@ -1128,6 +1130,7 @@ g_signal_connect_closure_by_id (gpointer instance, handler_id = handler->id; handler->detail = detail; handler->closure = g_closure_ref (closure); + g_closure_sink (closure); handler_insert (signal_id, instance, handler); if (node->c_marshaller && G_CLOSURE_NEEDS_MARSHAL (closure)) g_closure_set_marshal (closure, node->c_marshaller); @@ -1172,6 +1175,7 @@ g_signal_connect_closure (gpointer instance, handler_id = handler->id; handler->detail = detail; handler->closure = g_closure_ref (closure); + g_closure_sink (closure); handler_insert (signal_id, instance, handler); if (node->c_marshaller && G_CLOSURE_NEEDS_MARSHAL (handler->closure)) g_closure_set_marshal (handler->closure, node->c_marshaller); @@ -1219,6 +1223,7 @@ g_signal_connect_data (gpointer instance, handler_id = handler->id; handler->detail = detail; handler->closure = g_closure_ref ((swapped ? g_cclosure_new_swap : g_cclosure_new) (c_handler, data, destroy_data)); + g_closure_sink (handler->closure); handler_insert (signal_id, instance, handler); if (node->c_marshaller && G_CLOSURE_NEEDS_MARSHAL (handler->closure)) g_closure_set_marshal (handler->closure, node->c_marshaller); diff --git a/gobject/gtype.h b/gobject/gtype.h index 2e318b99e..4a29e4c43 100644 --- a/gobject/gtype.h +++ b/gobject/gtype.h @@ -171,6 +171,7 @@ struct _GTypeInterface /* debug flags for g_type_init() */ typedef enum /*< skip >*/ { + G_TYPE_DEBUG_NONE = 0, G_TYPE_DEBUG_OBJECTS = 1 << 0, G_TYPE_DEBUG_SIGNALS = 1 << 1, G_TYPE_DEBUG_MASK = 0x03