From 704852ff097f848dcb89ba553431b460938d8d91 Mon Sep 17 00:00:00 2001 From: Philip Withnall Date: Tue, 29 Apr 2014 08:47:14 +0100 Subject: [PATCH] gobject: Document that classes/objects/interfaces are zero-filled MIME-Version: 1.0 Content-Type: text/plain; charset=utf8 Content-Transfer-Encoding: 8bit On initialisation, GObject guarantees to zero-fill class/object/interface structures. Document this so people don’t spend forever writing: my_object->priv->some_member = NULL; my_object->priv->some_other_member = NULL; https://bugzilla.gnome.org/show_bug.cgi?id=729167 --- docs/reference/gobject/tut_howto.xml | 9 ++++++--- gobject/gtype.c | 11 +++++++++-- gobject/gtype.h | 7 +++++++ 3 files changed, 22 insertions(+), 5 deletions(-) diff --git a/docs/reference/gobject/tut_howto.xml b/docs/reference/gobject/tut_howto.xml index 35b212a..8d1b12c 100644 --- a/docs/reference/gobject/tut_howto.xml +++ b/docs/reference/gobject/tut_howto.xml @@ -147,7 +147,9 @@ GType maman_bar_get_type (void); macro with the G_DEFINE_TYPE_WITH_CODE() or the G_DEFINE_TYPE_EXTENDED() macros. The private structure is then defined in the .c file, and can be accessed using the get_instance_private() - function generated by the G_DEFINE_TYPE_* macros. + function generated by the G_DEFINE_TYPE_* macros. It is automatically + zero-filled on creation, so it is unnecessary to explicitly + initialize pointer members to NULL. struct _MamanBarPrivate { @@ -333,7 +335,8 @@ maman_bar_init (MamanBar *self) { self->priv = maman_bar_get_instance_private (self); - /* initialize all public and private members to reasonable default values. */ + /* initialize all public and private members to reasonable default values. + * They are all automatically initialized to 0 to begin with. */ } @@ -574,7 +577,7 @@ maman_bar_do_action (MamanBar *self, /* parameters */) implementation for this class method in the object's class_init function: initialize the klass->do_action field to a pointer to the actual implementation. - By default, class method that are not inherited are initialized to + By default, class methods that are not inherited are initialized to NULL, and thus are to be considered "pure virtual". static void diff --git a/gobject/gtype.c b/gobject/gtype.c index 2909f8a..3db19e6 100644 --- a/gobject/gtype.c +++ b/gobject/gtype.c @@ -1780,6 +1780,9 @@ type_iface_blow_holder_info_Wm (TypeNode *iface, * directly through g_type_create_instance() which doesn't handle things * like singleton objects or object construction. * + * The extended members of the returned instance are guaranteed to be filled + * with zeros. + * * Note: Do not use this function, unless you're implementing a * fundamental type. Also language bindings should not use this * function, but g_object_new() instead. @@ -4409,7 +4412,7 @@ gobject_init_ctor (void) * When an object is allocated, the private structures for * the type and all of its parent types are allocated * sequentially in the same memory block as the public - * structures. + * structures, and are zero-filled. * * Note that the accumulated size of the private structures of * a type and all its parent types cannot exceed 64 KiB. @@ -4451,6 +4454,8 @@ gobject_init_ctor (void) * my_object->priv = G_TYPE_INSTANCE_GET_PRIVATE (my_object, * MY_TYPE_OBJECT, * MyObjectPrivate); + * /* my_object->priv->some_field will be + * * automatically initialised to 0 */ * } * * static int @@ -4687,7 +4692,9 @@ g_type_class_get_instance_private_offset (gpointer g_class) * when the class is allocated, the private structures for * the class and all of its parent types are allocated * sequentially in the same memory block as the public - * structures. This function should be called in the + * structures, and are zero-filled. + * + * This function should be called in the * type's get_type() function after the type is registered. * The private structure can be retrieved using the * G_TYPE_CLASS_GET_PRIVATE() macro. diff --git a/gobject/gtype.h b/gobject/gtype.h index 8ceeb96..41dd857 100644 --- a/gobject/gtype.h +++ b/gobject/gtype.h @@ -882,10 +882,14 @@ typedef void (*GClassFinalizeFunc) (gpointer g_class, * 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 required by it. + * * Initialization of a derived instance involves calling all its parent * types instance initializers, so 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. + * + * The extended members of @instance are guaranteed to have been filled with + * zeros before this function is called. */ typedef void (*GInstanceInitFunc) (GTypeInstance *instance, gpointer g_class); @@ -897,6 +901,9 @@ typedef void (*GInstanceInitFunc) (GTypeInstance *instance, * 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. + * + * The members of @iface_data are guaranteed to have been filled with + * zeros before this function is called. */ typedef void (*GInterfaceInitFunc) (gpointer g_iface, gpointer iface_data); -- 2.7.4