GWeakRef: add a weak GObject reference believed to be thread-safe
[platform/upstream/glib.git] / gobject / gobject.c
1 /* GObject - GLib Type, Object, Parameter and Signal Library
2  * Copyright (C) 1998-1999, 2000-2001 Tim Janik and Red Hat, Inc.
3  *
4  * This library is free software; you can redistribute it and/or
5  * modify it under the terms of the GNU Lesser General Public
6  * License as published by the Free Software Foundation; either
7  * version 2 of the License, or (at your option) any later version.
8  *
9  * This library is distributed in the hope that it will be useful,
10  * but WITHOUT ANY WARRANTY; without even the implied warranty of
11  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
12  * Lesser General Public License for more details.
13  *
14  * You should have received a copy of the GNU Lesser General
15  * Public License along with this library; if not, write to the
16  * Free Software Foundation, Inc., 59 Temple Place, Suite 330,
17  * Boston, MA 02111-1307, USA.
18  */
19
20 /*
21  * MT safe with regards to reference counting.
22  */
23
24 #include "config.h"
25
26 #include <string.h>
27 #include <signal.h>
28
29 #include "gobject.h"
30 #include "gtype-private.h"
31 #include "gvaluecollector.h"
32 #include "gsignal.h"
33 #include "gparamspecs.h"
34 #include "gvaluetypes.h"
35 #include "gobject_trace.h"
36
37 /**
38  * SECTION:objects
39  * @title: GObject
40  * @short_description: The base object type
41  * @see_also: #GParamSpecObject, g_param_spec_object()
42  *
43  * GObject is the fundamental type providing the common attributes and
44  * methods for all object types in GTK+, Pango and other libraries
45  * based on GObject.  The GObject class provides methods for object
46  * construction and destruction, property access methods, and signal
47  * support.  Signals are described in detail in <xref
48  * linkend="gobject-Signals"/>.
49  *
50  * <para id="floating-ref">
51  * GInitiallyUnowned is derived from GObject. The only difference between
52  * the two is that the initial reference of a GInitiallyUnowned is flagged
53  * as a <firstterm>floating</firstterm> reference.
54  * This means that it is not specifically claimed to be "owned" by
55  * any code portion. The main motivation for providing floating references is
56  * C convenience. In particular, it allows code to be written as:
57  * |[
58  * container = create_container ();
59  * container_add_child (container, create_child());
60  * ]|
61  * If <function>container_add_child()</function> will g_object_ref_sink() the
62  * passed in child, no reference of the newly created child is leaked.
63  * Without floating references, <function>container_add_child()</function>
64  * can only g_object_ref() the new child, so to implement this code without
65  * reference leaks, it would have to be written as:
66  * |[
67  * Child *child;
68  * container = create_container ();
69  * child = create_child ();
70  * container_add_child (container, child);
71  * g_object_unref (child);
72  * ]|
73  * The floating reference can be converted into
74  * an ordinary reference by calling g_object_ref_sink().
75  * For already sunken objects (objects that don't have a floating reference
76  * anymore), g_object_ref_sink() is equivalent to g_object_ref() and returns
77  * a new reference.
78  * Since floating references are useful almost exclusively for C convenience,
79  * language bindings that provide automated reference and memory ownership
80  * maintenance (such as smart pointers or garbage collection) should not
81  * expose floating references in their API.
82  * </para>
83  *
84  * Some object implementations may need to save an objects floating state
85  * across certain code portions (an example is #GtkMenu), to achieve this,
86  * the following sequence can be used:
87  *
88  * |[
89  * /&ast; save floating state &ast;/
90  * gboolean was_floating = g_object_is_floating (object);
91  * g_object_ref_sink (object);
92  * /&ast; protected code portion &ast;/
93  * ...;
94  * /&ast; restore floating state &ast;/
95  * if (was_floating)
96  *   g_object_force_floating (object);
97  * g_object_unref (object); /&ast; release previously acquired reference &ast;/
98  * ]|
99  */
100
101
102 /* --- macros --- */
103 #define PARAM_SPEC_PARAM_ID(pspec)              ((pspec)->param_id)
104 #define PARAM_SPEC_SET_PARAM_ID(pspec, id)      ((pspec)->param_id = (id))
105
106 #define OBJECT_HAS_TOGGLE_REF_FLAG 0x1
107 #define OBJECT_HAS_TOGGLE_REF(object) \
108     ((g_datalist_get_flags (&(object)->qdata) & OBJECT_HAS_TOGGLE_REF_FLAG) != 0)
109 #define OBJECT_FLOATING_FLAG 0x2
110
111 #define CLASS_HAS_PROPS_FLAG 0x1
112 #define CLASS_HAS_PROPS(class) \
113     ((class)->flags & CLASS_HAS_PROPS_FLAG)
114 #define CLASS_HAS_CUSTOM_CONSTRUCTOR(class) \
115     ((class)->constructor != g_object_constructor)
116 #define CLASS_HAS_CUSTOM_CONSTRUCTED(class) \
117     ((class)->constructed != g_object_constructed)
118
119 #define CLASS_HAS_DERIVED_CLASS_FLAG 0x2
120 #define CLASS_HAS_DERIVED_CLASS(class) \
121     ((class)->flags & CLASS_HAS_DERIVED_CLASS_FLAG)
122
123 /* --- signals --- */
124 enum {
125   NOTIFY,
126   LAST_SIGNAL
127 };
128
129
130 /* --- properties --- */
131 enum {
132   PROP_NONE
133 };
134
135
136 /* --- prototypes --- */
137 static void     g_object_base_class_init                (GObjectClass   *class);
138 static void     g_object_base_class_finalize            (GObjectClass   *class);
139 static void     g_object_do_class_init                  (GObjectClass   *class);
140 static void     g_object_init                           (GObject        *object,
141                                                          GObjectClass   *class);
142 static GObject* g_object_constructor                    (GType                  type,
143                                                          guint                  n_construct_properties,
144                                                          GObjectConstructParam *construct_params);
145 static void     g_object_constructed                    (GObject        *object);
146 static void     g_object_real_dispose                   (GObject        *object);
147 static void     g_object_finalize                       (GObject        *object);
148 static void     g_object_do_set_property                (GObject        *object,
149                                                          guint           property_id,
150                                                          const GValue   *value,
151                                                          GParamSpec     *pspec);
152 static void     g_object_do_get_property                (GObject        *object,
153                                                          guint           property_id,
154                                                          GValue         *value,
155                                                          GParamSpec     *pspec);
156 static void     g_value_object_init                     (GValue         *value);
157 static void     g_value_object_free_value               (GValue         *value);
158 static void     g_value_object_copy_value               (const GValue   *src_value,
159                                                          GValue         *dest_value);
160 static void     g_value_object_transform_value          (const GValue   *src_value,
161                                                          GValue         *dest_value);
162 static gpointer g_value_object_peek_pointer             (const GValue   *value);
163 static gchar*   g_value_object_collect_value            (GValue         *value,
164                                                          guint           n_collect_values,
165                                                          GTypeCValue    *collect_values,
166                                                          guint           collect_flags);
167 static gchar*   g_value_object_lcopy_value              (const GValue   *value,
168                                                          guint           n_collect_values,
169                                                          GTypeCValue    *collect_values,
170                                                          guint           collect_flags);
171 static void     g_object_dispatch_properties_changed    (GObject        *object,
172                                                          guint           n_pspecs,
173                                                          GParamSpec    **pspecs);
174 static guint               object_floating_flag_handler (GObject        *object,
175                                                          gint            job);
176
177 static void object_interface_check_properties           (gpointer        func_data,
178                                                          gpointer        g_iface);
179
180 /* --- typedefs --- */
181 typedef struct _GObjectNotifyQueue            GObjectNotifyQueue;
182
183 struct _GObjectNotifyQueue
184 {
185   GSList  *pspecs;
186   guint16  n_pspecs;
187   guint16  freeze_count;
188 };
189
190 /* --- variables --- */
191 G_LOCK_DEFINE_STATIC (closure_array_mutex);
192 G_LOCK_DEFINE_STATIC (weak_refs_mutex);
193 G_LOCK_DEFINE_STATIC (toggle_refs_mutex);
194 static GQuark               quark_closure_array = 0;
195 static GQuark               quark_weak_refs = 0;
196 static GQuark               quark_toggle_refs = 0;
197 static GQuark               quark_notify_queue;
198 static GParamSpecPool      *pspec_pool = NULL;
199 static gulong               gobject_signals[LAST_SIGNAL] = { 0, };
200 static guint (*floating_flag_handler) (GObject*, gint) = object_floating_flag_handler;
201 G_LOCK_DEFINE_STATIC (construction_mutex);
202 static GSList *construction_objects = NULL;
203 /* qdata pointing to GSList<GWeakRef *>, protected by weak_locations_lock */
204 static GQuark               quark_weak_locations = 0;
205 static GRWLock              weak_locations_lock;
206
207 G_LOCK_DEFINE_STATIC(notify_lock);
208
209 /* --- functions --- */
210 static void
211 g_object_notify_queue_free (gpointer data)
212 {
213   GObjectNotifyQueue *nqueue = data;
214
215   g_slist_free (nqueue->pspecs);
216   g_slice_free (GObjectNotifyQueue, nqueue);
217 }
218
219 static GObjectNotifyQueue*
220 g_object_notify_queue_freeze (GObject  *object,
221                               gboolean  conditional)
222 {
223   GObjectNotifyQueue *nqueue;
224
225   G_LOCK(notify_lock);
226   nqueue = g_datalist_id_get_data (&object->qdata, quark_notify_queue);
227   if (!nqueue)
228     {
229       if (conditional)
230         {
231           G_UNLOCK(notify_lock);
232           return NULL;
233         }
234
235       nqueue = g_slice_new0 (GObjectNotifyQueue);
236       g_datalist_id_set_data_full (&object->qdata, quark_notify_queue,
237                                    nqueue, g_object_notify_queue_free);
238     }
239
240   if (nqueue->freeze_count >= 65535)
241     g_critical("Free queue for %s (%p) is larger than 65535,"
242                " called g_object_freeze_notify() too often."
243                " Forgot to call g_object_thaw_notify() or infinite loop",
244                G_OBJECT_TYPE_NAME (object), object);
245   else
246     nqueue->freeze_count++;
247   G_UNLOCK(notify_lock);
248
249   return nqueue;
250 }
251
252 static void
253 g_object_notify_queue_thaw (GObject            *object,
254                             GObjectNotifyQueue *nqueue)
255 {
256   GParamSpec *pspecs_mem[16], **pspecs, **free_me = NULL;
257   GSList *slist;
258   guint n_pspecs = 0;
259
260   g_return_if_fail (nqueue->freeze_count > 0);
261   g_return_if_fail (g_atomic_int_get(&object->ref_count) > 0);
262
263   G_LOCK(notify_lock);
264
265   /* Just make sure we never get into some nasty race condition */
266   if (G_UNLIKELY(nqueue->freeze_count == 0)) {
267     G_UNLOCK(notify_lock);
268     g_warning ("%s: property-changed notification for %s(%p) is not frozen",
269                G_STRFUNC, G_OBJECT_TYPE_NAME (object), object);
270     return;
271   }
272
273   nqueue->freeze_count--;
274   if (nqueue->freeze_count) {
275     G_UNLOCK(notify_lock);
276     return;
277   }
278
279   pspecs = nqueue->n_pspecs > 16 ? free_me = g_new (GParamSpec*, nqueue->n_pspecs) : pspecs_mem;
280
281   for (slist = nqueue->pspecs; slist; slist = slist->next)
282     {
283       pspecs[n_pspecs++] = slist->data;
284     }
285   g_datalist_id_set_data (&object->qdata, quark_notify_queue, NULL);
286
287   G_UNLOCK(notify_lock);
288
289   if (n_pspecs)
290     G_OBJECT_GET_CLASS (object)->dispatch_properties_changed (object, n_pspecs, pspecs);
291   g_free (free_me);
292 }
293
294 static void
295 g_object_notify_queue_add (GObject            *object,
296                            GObjectNotifyQueue *nqueue,
297                            GParamSpec         *pspec)
298 {
299   G_LOCK(notify_lock);
300
301   g_return_if_fail (nqueue->n_pspecs < 65535);
302
303   if (g_slist_find (nqueue->pspecs, pspec) == NULL)
304     {
305       nqueue->pspecs = g_slist_prepend (nqueue->pspecs, pspec);
306       nqueue->n_pspecs++;
307     }
308
309   G_UNLOCK(notify_lock);
310 }
311
312 #ifdef  G_ENABLE_DEBUG
313 #define IF_DEBUG(debug_type)    if (_g_type_debug_flags & G_TYPE_DEBUG_ ## debug_type)
314 G_LOCK_DEFINE_STATIC     (debug_objects);
315 static volatile GObject *g_trap_object_ref = NULL;
316 static guint             debug_objects_count = 0;
317 static GHashTable       *debug_objects_ht = NULL;
318
319 static void
320 debug_objects_foreach (gpointer key,
321                        gpointer value,
322                        gpointer user_data)
323 {
324   GObject *object = value;
325
326   g_message ("[%p] stale %s\tref_count=%u",
327              object,
328              G_OBJECT_TYPE_NAME (object),
329              object->ref_count);
330 }
331
332 static void
333 debug_objects_atexit (void)
334 {
335   IF_DEBUG (OBJECTS)
336     {
337       G_LOCK (debug_objects);
338       g_message ("stale GObjects: %u", debug_objects_count);
339       g_hash_table_foreach (debug_objects_ht, debug_objects_foreach, NULL);
340       G_UNLOCK (debug_objects);
341     }
342 }
343 #endif  /* G_ENABLE_DEBUG */
344
345 void
346 _g_object_type_init (void)
347 {
348   static gboolean initialized = FALSE;
349   static const GTypeFundamentalInfo finfo = {
350     G_TYPE_FLAG_CLASSED | G_TYPE_FLAG_INSTANTIATABLE | G_TYPE_FLAG_DERIVABLE | G_TYPE_FLAG_DEEP_DERIVABLE,
351   };
352   GTypeInfo info = {
353     sizeof (GObjectClass),
354     (GBaseInitFunc) g_object_base_class_init,
355     (GBaseFinalizeFunc) g_object_base_class_finalize,
356     (GClassInitFunc) g_object_do_class_init,
357     NULL        /* class_destroy */,
358     NULL        /* class_data */,
359     sizeof (GObject),
360     0           /* n_preallocs */,
361     (GInstanceInitFunc) g_object_init,
362     NULL,       /* value_table */
363   };
364   static const GTypeValueTable value_table = {
365     g_value_object_init,          /* value_init */
366     g_value_object_free_value,    /* value_free */
367     g_value_object_copy_value,    /* value_copy */
368     g_value_object_peek_pointer,  /* value_peek_pointer */
369     "p",                          /* collect_format */
370     g_value_object_collect_value, /* collect_value */
371     "p",                          /* lcopy_format */
372     g_value_object_lcopy_value,   /* lcopy_value */
373   };
374   GType type;
375   
376   g_return_if_fail (initialized == FALSE);
377   initialized = TRUE;
378   
379   /* G_TYPE_OBJECT
380    */
381   info.value_table = &value_table;
382   type = g_type_register_fundamental (G_TYPE_OBJECT, g_intern_static_string ("GObject"), &info, &finfo, 0);
383   g_assert (type == G_TYPE_OBJECT);
384   g_value_register_transform_func (G_TYPE_OBJECT, G_TYPE_OBJECT, g_value_object_transform_value);
385   
386 #ifdef  G_ENABLE_DEBUG
387   IF_DEBUG (OBJECTS)
388     {
389       debug_objects_ht = g_hash_table_new (g_direct_hash, NULL);
390       g_atexit (debug_objects_atexit);
391     }
392 #endif  /* G_ENABLE_DEBUG */
393 }
394
395 static void
396 g_object_base_class_init (GObjectClass *class)
397 {
398   GObjectClass *pclass = g_type_class_peek_parent (class);
399
400   /* Don't inherit HAS_DERIVED_CLASS flag from parent class */
401   class->flags &= ~CLASS_HAS_DERIVED_CLASS_FLAG;
402
403   if (pclass)
404     pclass->flags |= CLASS_HAS_DERIVED_CLASS_FLAG;
405
406   /* reset instance specific fields and methods that don't get inherited */
407   class->construct_properties = pclass ? g_slist_copy (pclass->construct_properties) : NULL;
408   class->get_property = NULL;
409   class->set_property = NULL;
410 }
411
412 static void
413 g_object_base_class_finalize (GObjectClass *class)
414 {
415   GList *list, *node;
416   
417   _g_signals_destroy (G_OBJECT_CLASS_TYPE (class));
418
419   g_slist_free (class->construct_properties);
420   class->construct_properties = NULL;
421   list = g_param_spec_pool_list_owned (pspec_pool, G_OBJECT_CLASS_TYPE (class));
422   for (node = list; node; node = node->next)
423     {
424       GParamSpec *pspec = node->data;
425       
426       g_param_spec_pool_remove (pspec_pool, pspec);
427       PARAM_SPEC_SET_PARAM_ID (pspec, 0);
428       g_param_spec_unref (pspec);
429     }
430   g_list_free (list);
431 }
432
433 static void
434 g_object_do_class_init (GObjectClass *class)
435 {
436   /* read the comment about typedef struct CArray; on why not to change this quark */
437   quark_closure_array = g_quark_from_static_string ("GObject-closure-array");
438
439   quark_weak_refs = g_quark_from_static_string ("GObject-weak-references");
440   quark_weak_locations = g_quark_from_static_string ("GObject-weak-locations");
441   quark_toggle_refs = g_quark_from_static_string ("GObject-toggle-references");
442   quark_notify_queue = g_quark_from_static_string ("GObject-notify-queue");
443   pspec_pool = g_param_spec_pool_new (TRUE);
444
445   class->constructor = g_object_constructor;
446   class->constructed = g_object_constructed;
447   class->set_property = g_object_do_set_property;
448   class->get_property = g_object_do_get_property;
449   class->dispose = g_object_real_dispose;
450   class->finalize = g_object_finalize;
451   class->dispatch_properties_changed = g_object_dispatch_properties_changed;
452   class->notify = NULL;
453
454   /**
455    * GObject::notify:
456    * @gobject: the object which received the signal.
457    * @pspec: the #GParamSpec of the property which changed.
458    *
459    * The notify signal is emitted on an object when one of its
460    * properties has been changed. Note that getting this signal
461    * doesn't guarantee that the value of the property has actually
462    * changed, it may also be emitted when the setter for the property
463    * is called to reinstate the previous value.
464    *
465    * This signal is typically used to obtain change notification for a
466    * single property, by specifying the property name as a detail in the
467    * g_signal_connect() call, like this:
468    * |[
469    * g_signal_connect (text_view->buffer, "notify::paste-target-list",
470    *                   G_CALLBACK (gtk_text_view_target_list_notify),
471    *                   text_view)
472    * ]|
473    * It is important to note that you must use
474    * <link linkend="canonical-parameter-name">canonical</link> parameter names as
475    * detail strings for the notify signal.
476    */
477   gobject_signals[NOTIFY] =
478     g_signal_new (g_intern_static_string ("notify"),
479                   G_TYPE_FROM_CLASS (class),
480                   G_SIGNAL_RUN_FIRST | G_SIGNAL_NO_RECURSE | G_SIGNAL_DETAILED | G_SIGNAL_NO_HOOKS | G_SIGNAL_ACTION,
481                   G_STRUCT_OFFSET (GObjectClass, notify),
482                   NULL, NULL,
483                   g_cclosure_marshal_VOID__PARAM,
484                   G_TYPE_NONE,
485                   1, G_TYPE_PARAM);
486
487   /* Install a check function that we'll use to verify that classes that
488    * implement an interface implement all properties for that interface
489    */
490   g_type_add_interface_check (NULL, object_interface_check_properties);
491 }
492
493 static inline void
494 install_property_internal (GType       g_type,
495                            guint       property_id,
496                            GParamSpec *pspec)
497 {
498   if (g_param_spec_pool_lookup (pspec_pool, pspec->name, g_type, FALSE))
499     {
500       g_warning ("When installing property: type `%s' already has a property named `%s'",
501                  g_type_name (g_type),
502                  pspec->name);
503       return;
504     }
505
506   g_param_spec_ref_sink (pspec);
507   PARAM_SPEC_SET_PARAM_ID (pspec, property_id);
508   g_param_spec_pool_insert (pspec_pool, pspec, g_type);
509 }
510
511 /**
512  * g_object_class_install_property:
513  * @oclass: a #GObjectClass
514  * @property_id: the id for the new property
515  * @pspec: the #GParamSpec for the new property
516  *
517  * Installs a new property. This is usually done in the class initializer.
518  *
519  * Note that it is possible to redefine a property in a derived class,
520  * by installing a property with the same name. This can be useful at times,
521  * e.g. to change the range of allowed values or the default value.
522  */
523 void
524 g_object_class_install_property (GObjectClass *class,
525                                  guint         property_id,
526                                  GParamSpec   *pspec)
527 {
528   g_return_if_fail (G_IS_OBJECT_CLASS (class));
529   g_return_if_fail (G_IS_PARAM_SPEC (pspec));
530
531   if (CLASS_HAS_DERIVED_CLASS (class))
532     g_error ("Attempt to add property %s::%s to class after it was derived",
533              G_OBJECT_CLASS_NAME (class), pspec->name);
534
535   class->flags |= CLASS_HAS_PROPS_FLAG;
536
537   g_return_if_fail (pspec->flags & (G_PARAM_READABLE | G_PARAM_WRITABLE));
538   if (pspec->flags & G_PARAM_WRITABLE)
539     g_return_if_fail (class->set_property != NULL);
540   if (pspec->flags & G_PARAM_READABLE)
541     g_return_if_fail (class->get_property != NULL);
542   g_return_if_fail (property_id > 0);
543   g_return_if_fail (PARAM_SPEC_PARAM_ID (pspec) == 0);  /* paranoid */
544   if (pspec->flags & G_PARAM_CONSTRUCT)
545     g_return_if_fail ((pspec->flags & G_PARAM_CONSTRUCT_ONLY) == 0);
546   if (pspec->flags & (G_PARAM_CONSTRUCT | G_PARAM_CONSTRUCT_ONLY))
547     g_return_if_fail (pspec->flags & G_PARAM_WRITABLE);
548
549   install_property_internal (G_OBJECT_CLASS_TYPE (class), property_id, pspec);
550
551   if (pspec->flags & (G_PARAM_CONSTRUCT | G_PARAM_CONSTRUCT_ONLY))
552     class->construct_properties = g_slist_prepend (class->construct_properties, pspec);
553
554   /* for property overrides of construct properties, we have to get rid
555    * of the overidden inherited construct property
556    */
557   pspec = g_param_spec_pool_lookup (pspec_pool, pspec->name, g_type_parent (G_OBJECT_CLASS_TYPE (class)), TRUE);
558   if (pspec && pspec->flags & (G_PARAM_CONSTRUCT | G_PARAM_CONSTRUCT_ONLY))
559     class->construct_properties = g_slist_remove (class->construct_properties, pspec);
560 }
561
562 /**
563  * g_object_class_install_properties:
564  * @oclass: a #GObjectClass
565  * @n_pspecs: the length of the #GParamSpec<!-- -->s array
566  * @pspecs: (array length=n_pspecs): the #GParamSpec<!-- -->s array
567  *   defining the new properties
568  *
569  * Installs new properties from an array of #GParamSpec<!-- -->s. This is
570  * usually done in the class initializer.
571  *
572  * The property id of each property is the index of each #GParamSpec in
573  * the @pspecs array.
574  *
575  * The property id of 0 is treated specially by #GObject and it should not
576  * be used to store a #GParamSpec.
577  *
578  * This function should be used if you plan to use a static array of
579  * #GParamSpec<!-- -->s and g_object_notify_by_pspec(). For instance, this
580  * class initialization:
581  *
582  * |[
583  * enum {
584  *   PROP_0, PROP_FOO, PROP_BAR, N_PROPERTIES
585  * };
586  *
587  * static GParamSpec *obj_properties[N_PROPERTIES] = { NULL, };
588  *
589  * static void
590  * my_object_class_init (MyObjectClass *klass)
591  * {
592  *   GObjectClass *gobject_class = G_OBJECT_CLASS (klass);
593  *
594  *   obj_properties[PROP_FOO] =
595  *     g_param_spec_int ("foo", "Foo", "Foo",
596  *                       -1, G_MAXINT,
597  *                       0,
598  *                       G_PARAM_READWRITE);
599  *
600  *   obj_properties[PROP_BAR] =
601  *     g_param_spec_string ("bar", "Bar", "Bar",
602  *                          NULL,
603  *                          G_PARAM_READWRITE);
604  *
605  *   gobject_class->set_property = my_object_set_property;
606  *   gobject_class->get_property = my_object_get_property;
607  *   g_object_class_install_properties (gobject_class,
608  *                                      N_PROPERTIES,
609  *                                      obj_properties);
610  * }
611  * ]|
612  *
613  * allows calling g_object_notify_by_pspec() to notify of property changes:
614  *
615  * |[
616  * void
617  * my_object_set_foo (MyObject *self, gint foo)
618  * {
619  *   if (self->foo != foo)
620  *     {
621  *       self->foo = foo;
622  *       g_object_notify_by_pspec (G_OBJECT (self), obj_properties[PROP_FOO]);
623  *     }
624  *  }
625  * ]|
626  *
627  * Since: 2.26
628  */
629 void
630 g_object_class_install_properties (GObjectClass  *oclass,
631                                    guint          n_pspecs,
632                                    GParamSpec   **pspecs)
633 {
634   GType oclass_type, parent_type;
635   gint i;
636
637   g_return_if_fail (G_IS_OBJECT_CLASS (oclass));
638   g_return_if_fail (n_pspecs > 1);
639   g_return_if_fail (pspecs[0] == NULL);
640
641   if (CLASS_HAS_DERIVED_CLASS (oclass))
642     g_error ("Attempt to add properties to %s after it was derived",
643              G_OBJECT_CLASS_NAME (oclass));
644
645   oclass_type = G_OBJECT_CLASS_TYPE (oclass);
646   parent_type = g_type_parent (oclass_type);
647
648   /* we skip the first element of the array as it would have a 0 prop_id */
649   for (i = 1; i < n_pspecs; i++)
650     {
651       GParamSpec *pspec = pspecs[i];
652
653       g_return_if_fail (pspec != NULL);
654
655       if (pspec->flags & G_PARAM_WRITABLE)
656         g_return_if_fail (oclass->set_property != NULL);
657       if (pspec->flags & G_PARAM_READABLE)
658         g_return_if_fail (oclass->get_property != NULL);
659       g_return_if_fail (PARAM_SPEC_PARAM_ID (pspec) == 0);      /* paranoid */
660       if (pspec->flags & G_PARAM_CONSTRUCT)
661         g_return_if_fail ((pspec->flags & G_PARAM_CONSTRUCT_ONLY) == 0);
662       if (pspec->flags & (G_PARAM_CONSTRUCT | G_PARAM_CONSTRUCT_ONLY))
663         g_return_if_fail (pspec->flags & G_PARAM_WRITABLE);
664
665       oclass->flags |= CLASS_HAS_PROPS_FLAG;
666       install_property_internal (oclass_type, i, pspec);
667
668       if (pspec->flags & (G_PARAM_CONSTRUCT | G_PARAM_CONSTRUCT_ONLY))
669         oclass->construct_properties = g_slist_prepend (oclass->construct_properties, pspec);
670
671       /* for property overrides of construct properties, we have to get rid
672        * of the overidden inherited construct property
673        */
674       pspec = g_param_spec_pool_lookup (pspec_pool, pspec->name, parent_type, TRUE);
675       if (pspec && pspec->flags & (G_PARAM_CONSTRUCT | G_PARAM_CONSTRUCT_ONLY))
676         oclass->construct_properties = g_slist_remove (oclass->construct_properties, pspec);
677     }
678 }
679
680 /**
681  * g_object_interface_install_property:
682  * @g_iface: any interface vtable for the interface, or the default
683  *  vtable for the interface.
684  * @pspec: the #GParamSpec for the new property
685  *
686  * Add a property to an interface; this is only useful for interfaces
687  * that are added to GObject-derived types. Adding a property to an
688  * interface forces all objects classes with that interface to have a
689  * compatible property. The compatible property could be a newly
690  * created #GParamSpec, but normally
691  * g_object_class_override_property() will be used so that the object
692  * class only needs to provide an implementation and inherits the
693  * property description, default value, bounds, and so forth from the
694  * interface property.
695  *
696  * This function is meant to be called from the interface's default
697  * vtable initialization function (the @class_init member of
698  * #GTypeInfo.) It must not be called after after @class_init has
699  * been called for any object types implementing this interface.
700  *
701  * Since: 2.4
702  */
703 void
704 g_object_interface_install_property (gpointer      g_iface,
705                                      GParamSpec   *pspec)
706 {
707   GTypeInterface *iface_class = g_iface;
708         
709   g_return_if_fail (G_TYPE_IS_INTERFACE (iface_class->g_type));
710   g_return_if_fail (G_IS_PARAM_SPEC (pspec));
711   g_return_if_fail (!G_IS_PARAM_SPEC_OVERRIDE (pspec)); /* paranoid */
712   g_return_if_fail (PARAM_SPEC_PARAM_ID (pspec) == 0);  /* paranoid */
713
714   g_return_if_fail (pspec->flags & (G_PARAM_READABLE | G_PARAM_WRITABLE));
715   if (pspec->flags & G_PARAM_CONSTRUCT)
716     g_return_if_fail ((pspec->flags & G_PARAM_CONSTRUCT_ONLY) == 0);
717   if (pspec->flags & (G_PARAM_CONSTRUCT | G_PARAM_CONSTRUCT_ONLY))
718     g_return_if_fail (pspec->flags & G_PARAM_WRITABLE);
719
720   install_property_internal (iface_class->g_type, 0, pspec);
721 }
722
723 /**
724  * g_object_class_find_property:
725  * @oclass: a #GObjectClass
726  * @property_name: the name of the property to look up
727  *
728  * Looks up the #GParamSpec for a property of a class.
729  *
730  * Returns: (transfer none): the #GParamSpec for the property, or
731  *          %NULL if the class doesn't have a property of that name
732  */
733 GParamSpec*
734 g_object_class_find_property (GObjectClass *class,
735                               const gchar  *property_name)
736 {
737   GParamSpec *pspec;
738   GParamSpec *redirect;
739         
740   g_return_val_if_fail (G_IS_OBJECT_CLASS (class), NULL);
741   g_return_val_if_fail (property_name != NULL, NULL);
742   
743   pspec = g_param_spec_pool_lookup (pspec_pool,
744                                     property_name,
745                                     G_OBJECT_CLASS_TYPE (class),
746                                     TRUE);
747   if (pspec)
748     {
749       redirect = g_param_spec_get_redirect_target (pspec);
750       if (redirect)
751         return redirect;
752       else
753         return pspec;
754     }
755   else
756     return NULL;
757 }
758
759 /**
760  * g_object_interface_find_property:
761  * @g_iface: any interface vtable for the interface, or the default
762  *  vtable for the interface
763  * @property_name: name of a property to lookup.
764  *
765  * Find the #GParamSpec with the given name for an
766  * interface. Generally, the interface vtable passed in as @g_iface
767  * will be the default vtable from g_type_default_interface_ref(), or,
768  * if you know the interface has already been loaded,
769  * g_type_default_interface_peek().
770  *
771  * Since: 2.4
772  *
773  * Returns: (transfer none): the #GParamSpec for the property of the
774  *          interface with the name @property_name, or %NULL if no
775  *          such property exists.
776  */
777 GParamSpec*
778 g_object_interface_find_property (gpointer      g_iface,
779                                   const gchar  *property_name)
780 {
781   GTypeInterface *iface_class = g_iface;
782         
783   g_return_val_if_fail (G_TYPE_IS_INTERFACE (iface_class->g_type), NULL);
784   g_return_val_if_fail (property_name != NULL, NULL);
785   
786   return g_param_spec_pool_lookup (pspec_pool,
787                                    property_name,
788                                    iface_class->g_type,
789                                    FALSE);
790 }
791
792 /**
793  * g_object_class_override_property:
794  * @oclass: a #GObjectClass
795  * @property_id: the new property ID
796  * @name: the name of a property registered in a parent class or
797  *  in an interface of this class.
798  *
799  * Registers @property_id as referring to a property with the
800  * name @name in a parent class or in an interface implemented
801  * by @oclass. This allows this class to <firstterm>override</firstterm>
802  * a property implementation in a parent class or to provide
803  * the implementation of a property from an interface.
804  *
805  * <note>
806  * Internally, overriding is implemented by creating a property of type
807  * #GParamSpecOverride; generally operations that query the properties of
808  * the object class, such as g_object_class_find_property() or
809  * g_object_class_list_properties() will return the overridden
810  * property. However, in one case, the @construct_properties argument of
811  * the @constructor virtual function, the #GParamSpecOverride is passed
812  * instead, so that the @param_id field of the #GParamSpec will be
813  * correct.  For virtually all uses, this makes no difference. If you
814  * need to get the overridden property, you can call
815  * g_param_spec_get_redirect_target().
816  * </note>
817  *
818  * Since: 2.4
819  */
820 void
821 g_object_class_override_property (GObjectClass *oclass,
822                                   guint         property_id,
823                                   const gchar  *name)
824 {
825   GParamSpec *overridden = NULL;
826   GParamSpec *new;
827   GType parent_type;
828   
829   g_return_if_fail (G_IS_OBJECT_CLASS (oclass));
830   g_return_if_fail (property_id > 0);
831   g_return_if_fail (name != NULL);
832
833   /* Find the overridden property; first check parent types
834    */
835   parent_type = g_type_parent (G_OBJECT_CLASS_TYPE (oclass));
836   if (parent_type != G_TYPE_NONE)
837     overridden = g_param_spec_pool_lookup (pspec_pool,
838                                            name,
839                                            parent_type,
840                                            TRUE);
841   if (!overridden)
842     {
843       GType *ifaces;
844       guint n_ifaces;
845       
846       /* Now check interfaces
847        */
848       ifaces = g_type_interfaces (G_OBJECT_CLASS_TYPE (oclass), &n_ifaces);
849       while (n_ifaces-- && !overridden)
850         {
851           overridden = g_param_spec_pool_lookup (pspec_pool,
852                                                  name,
853                                                  ifaces[n_ifaces],
854                                                  FALSE);
855         }
856       
857       g_free (ifaces);
858     }
859
860   if (!overridden)
861     {
862       g_warning ("%s: Can't find property to override for '%s::%s'",
863                  G_STRFUNC, G_OBJECT_CLASS_NAME (oclass), name);
864       return;
865     }
866
867   new = g_param_spec_override (name, overridden);
868   g_object_class_install_property (oclass, property_id, new);
869 }
870
871 /**
872  * g_object_class_list_properties:
873  * @oclass: a #GObjectClass
874  * @n_properties: (out): return location for the length of the returned array
875  *
876  * Get an array of #GParamSpec* for all properties of a class.
877  *
878  * Returns: (array length=n_properties) (transfer container): an array of
879  *          #GParamSpec* which should be freed after use
880  */
881 GParamSpec** /* free result */
882 g_object_class_list_properties (GObjectClass *class,
883                                 guint        *n_properties_p)
884 {
885   GParamSpec **pspecs;
886   guint n;
887
888   g_return_val_if_fail (G_IS_OBJECT_CLASS (class), NULL);
889
890   pspecs = g_param_spec_pool_list (pspec_pool,
891                                    G_OBJECT_CLASS_TYPE (class),
892                                    &n);
893   if (n_properties_p)
894     *n_properties_p = n;
895
896   return pspecs;
897 }
898
899 /**
900  * g_object_interface_list_properties:
901  * @g_iface: any interface vtable for the interface, or the default
902  *  vtable for the interface
903  * @n_properties_p: (out): location to store number of properties returned.
904  *
905  * Lists the properties of an interface.Generally, the interface
906  * vtable passed in as @g_iface will be the default vtable from
907  * g_type_default_interface_ref(), or, if you know the interface has
908  * already been loaded, g_type_default_interface_peek().
909  *
910  * Since: 2.4
911  *
912  * Returns: (array length=n_properties_p) (transfer container): a
913  *          pointer to an array of pointers to #GParamSpec
914  *          structures. The paramspecs are owned by GLib, but the
915  *          array should be freed with g_free() when you are done with
916  *          it.
917  */
918 GParamSpec**
919 g_object_interface_list_properties (gpointer      g_iface,
920                                     guint        *n_properties_p)
921 {
922   GTypeInterface *iface_class = g_iface;
923   GParamSpec **pspecs;
924   guint n;
925
926   g_return_val_if_fail (G_TYPE_IS_INTERFACE (iface_class->g_type), NULL);
927
928   pspecs = g_param_spec_pool_list (pspec_pool,
929                                    iface_class->g_type,
930                                    &n);
931   if (n_properties_p)
932     *n_properties_p = n;
933
934   return pspecs;
935 }
936
937 static void
938 g_object_init (GObject          *object,
939                GObjectClass     *class)
940 {
941   object->ref_count = 1;
942   object->qdata = NULL;
943
944   if (CLASS_HAS_PROPS (class))
945     {
946       /* freeze object's notification queue, g_object_newv() preserves pairedness */
947       g_object_notify_queue_freeze (object, FALSE);
948     }
949
950   if (CLASS_HAS_CUSTOM_CONSTRUCTOR (class))
951     {
952       /* enter construction list for notify_queue_thaw() and to allow construct-only properties */
953       G_LOCK (construction_mutex);
954       construction_objects = g_slist_prepend (construction_objects, object);
955       G_UNLOCK (construction_mutex);
956     }
957
958 #ifdef  G_ENABLE_DEBUG
959   IF_DEBUG (OBJECTS)
960     {
961       G_LOCK (debug_objects);
962       debug_objects_count++;
963       g_hash_table_insert (debug_objects_ht, object, object);
964       G_UNLOCK (debug_objects);
965     }
966 #endif  /* G_ENABLE_DEBUG */
967 }
968
969 static void
970 g_object_do_set_property (GObject      *object,
971                           guint         property_id,
972                           const GValue *value,
973                           GParamSpec   *pspec)
974 {
975   switch (property_id)
976     {
977     default:
978       G_OBJECT_WARN_INVALID_PROPERTY_ID (object, property_id, pspec);
979       break;
980     }
981 }
982
983 static void
984 g_object_do_get_property (GObject     *object,
985                           guint        property_id,
986                           GValue      *value,
987                           GParamSpec  *pspec)
988 {
989   switch (property_id)
990     {
991     default:
992       G_OBJECT_WARN_INVALID_PROPERTY_ID (object, property_id, pspec);
993       break;
994     }
995 }
996
997 static void
998 g_object_real_dispose (GObject *object)
999 {
1000   g_signal_handlers_destroy (object);
1001   g_datalist_id_set_data (&object->qdata, quark_closure_array, NULL);
1002   g_datalist_id_set_data (&object->qdata, quark_weak_refs, NULL);
1003 }
1004
1005 static void
1006 g_object_finalize (GObject *object)
1007 {
1008   g_datalist_clear (&object->qdata);
1009   
1010 #ifdef  G_ENABLE_DEBUG
1011   IF_DEBUG (OBJECTS)
1012     {
1013       G_LOCK (debug_objects);
1014       g_assert (g_hash_table_lookup (debug_objects_ht, object) == object);
1015       g_hash_table_remove (debug_objects_ht, object);
1016       debug_objects_count--;
1017       G_UNLOCK (debug_objects);
1018     }
1019 #endif  /* G_ENABLE_DEBUG */
1020 }
1021
1022
1023 static void
1024 g_object_dispatch_properties_changed (GObject     *object,
1025                                       guint        n_pspecs,
1026                                       GParamSpec **pspecs)
1027 {
1028   guint i;
1029
1030   for (i = 0; i < n_pspecs; i++)
1031     g_signal_emit (object, gobject_signals[NOTIFY], g_quark_from_string (pspecs[i]->name), pspecs[i]);
1032 }
1033
1034 /**
1035  * g_object_run_dispose:
1036  * @object: a #GObject
1037  *
1038  * Releases all references to other objects. This can be used to break
1039  * reference cycles.
1040  *
1041  * This functions should only be called from object system implementations.
1042  */
1043 void
1044 g_object_run_dispose (GObject *object)
1045 {
1046   g_return_if_fail (G_IS_OBJECT (object));
1047   g_return_if_fail (object->ref_count > 0);
1048
1049   g_object_ref (object);
1050   TRACE (GOBJECT_OBJECT_DISPOSE(object,G_TYPE_FROM_INSTANCE(object), 0));
1051   G_OBJECT_GET_CLASS (object)->dispose (object);
1052   TRACE (GOBJECT_OBJECT_DISPOSE_END(object,G_TYPE_FROM_INSTANCE(object), 0));
1053   g_object_unref (object);
1054 }
1055
1056 /**
1057  * g_object_freeze_notify:
1058  * @object: a #GObject
1059  *
1060  * Increases the freeze count on @object. If the freeze count is
1061  * non-zero, the emission of "notify" signals on @object is
1062  * stopped. The signals are queued until the freeze count is decreased
1063  * to zero.
1064  *
1065  * This is necessary for accessors that modify multiple properties to prevent
1066  * premature notification while the object is still being modified.
1067  */
1068 void
1069 g_object_freeze_notify (GObject *object)
1070 {
1071   g_return_if_fail (G_IS_OBJECT (object));
1072
1073   if (g_atomic_int_get (&object->ref_count) == 0)
1074     return;
1075
1076   g_object_ref (object);
1077   g_object_notify_queue_freeze (object, FALSE);
1078   g_object_unref (object);
1079 }
1080
1081 static GParamSpec *
1082 get_notify_pspec (GParamSpec *pspec)
1083 {
1084   GParamSpec *redirected;
1085
1086   /* we don't notify on non-READABLE parameters */
1087   if (~pspec->flags & G_PARAM_READABLE)
1088     return NULL;
1089
1090   /* if the paramspec is redirected, notify on the target */
1091   redirected = g_param_spec_get_redirect_target (pspec);
1092   if (redirected != NULL)
1093     return redirected;
1094
1095   /* else, notify normally */
1096   return pspec;
1097 }
1098
1099 static inline void
1100 g_object_notify_by_spec_internal (GObject    *object,
1101                                   GParamSpec *pspec)
1102 {
1103   GParamSpec *notify_pspec;
1104
1105   notify_pspec = get_notify_pspec (pspec);
1106
1107   if (notify_pspec != NULL)
1108     {
1109       GObjectNotifyQueue *nqueue;
1110
1111       /* conditional freeze: only increase freeze count if already frozen */
1112       nqueue = g_object_notify_queue_freeze (object, TRUE);
1113
1114       if (nqueue != NULL)
1115         {
1116           /* we're frozen, so add to the queue and release our freeze */
1117           g_object_notify_queue_add (object, nqueue, notify_pspec);
1118           g_object_notify_queue_thaw (object, nqueue);
1119         }
1120       else
1121         /* not frozen, so just dispatch the notification directly */
1122         G_OBJECT_GET_CLASS (object)
1123           ->dispatch_properties_changed (object, 1, &notify_pspec);
1124     }
1125 }
1126
1127 /**
1128  * g_object_notify:
1129  * @object: a #GObject
1130  * @property_name: the name of a property installed on the class of @object.
1131  *
1132  * Emits a "notify" signal for the property @property_name on @object.
1133  *
1134  * When possible, eg. when signaling a property change from within the class
1135  * that registered the property, you should use g_object_notify_by_pspec()
1136  * instead.
1137  */
1138 void
1139 g_object_notify (GObject     *object,
1140                  const gchar *property_name)
1141 {
1142   GParamSpec *pspec;
1143   
1144   g_return_if_fail (G_IS_OBJECT (object));
1145   g_return_if_fail (property_name != NULL);
1146   if (g_atomic_int_get (&object->ref_count) == 0)
1147     return;
1148   
1149   g_object_ref (object);
1150   /* We don't need to get the redirect target
1151    * (by, e.g. calling g_object_class_find_property())
1152    * because g_object_notify_queue_add() does that
1153    */
1154   pspec = g_param_spec_pool_lookup (pspec_pool,
1155                                     property_name,
1156                                     G_OBJECT_TYPE (object),
1157                                     TRUE);
1158
1159   if (!pspec)
1160     g_warning ("%s: object class `%s' has no property named `%s'",
1161                G_STRFUNC,
1162                G_OBJECT_TYPE_NAME (object),
1163                property_name);
1164   else
1165     g_object_notify_by_spec_internal (object, pspec);
1166   g_object_unref (object);
1167 }
1168
1169 /**
1170  * g_object_notify_by_pspec:
1171  * @object: a #GObject
1172  * @pspec: the #GParamSpec of a property installed on the class of @object.
1173  *
1174  * Emits a "notify" signal for the property specified by @pspec on @object.
1175  *
1176  * This function omits the property name lookup, hence it is faster than
1177  * g_object_notify().
1178  *
1179  * One way to avoid using g_object_notify() from within the
1180  * class that registered the properties, and using g_object_notify_by_pspec()
1181  * instead, is to store the GParamSpec used with
1182  * g_object_class_install_property() inside a static array, e.g.:
1183  *
1184  *|[
1185  *   enum
1186  *   {
1187  *     PROP_0,
1188  *     PROP_FOO,
1189  *     PROP_LAST
1190  *   };
1191  *
1192  *   static GParamSpec *properties[PROP_LAST];
1193  *
1194  *   static void
1195  *   my_object_class_init (MyObjectClass *klass)
1196  *   {
1197  *     properties[PROP_FOO] = g_param_spec_int ("foo", "Foo", "The foo",
1198  *                                              0, 100,
1199  *                                              50,
1200  *                                              G_PARAM_READWRITE);
1201  *     g_object_class_install_property (gobject_class,
1202  *                                      PROP_FOO,
1203  *                                      properties[PROP_FOO]);
1204  *   }
1205  * ]|
1206  *
1207  * and then notify a change on the "foo" property with:
1208  *
1209  * |[
1210  *   g_object_notify_by_pspec (self, properties[PROP_FOO]);
1211  * ]|
1212  *
1213  * Since: 2.26
1214  */
1215 void
1216 g_object_notify_by_pspec (GObject    *object,
1217                           GParamSpec *pspec)
1218 {
1219
1220   g_return_if_fail (G_IS_OBJECT (object));
1221   g_return_if_fail (G_IS_PARAM_SPEC (pspec));
1222
1223   g_object_ref (object);
1224   g_object_notify_by_spec_internal (object, pspec);
1225   g_object_unref (object);
1226 }
1227
1228 /**
1229  * g_object_thaw_notify:
1230  * @object: a #GObject
1231  *
1232  * Reverts the effect of a previous call to
1233  * g_object_freeze_notify(). The freeze count is decreased on @object
1234  * and when it reaches zero, all queued "notify" signals are emitted.
1235  *
1236  * It is an error to call this function when the freeze count is zero.
1237  */
1238 void
1239 g_object_thaw_notify (GObject *object)
1240 {
1241   GObjectNotifyQueue *nqueue;
1242   
1243   g_return_if_fail (G_IS_OBJECT (object));
1244   if (g_atomic_int_get (&object->ref_count) == 0)
1245     return;
1246   
1247   g_object_ref (object);
1248
1249   /* FIXME: Freezing is the only way to get at the notify queue.
1250    * So we freeze once and then thaw twice.
1251    */
1252   nqueue = g_object_notify_queue_freeze (object, FALSE);
1253   g_object_notify_queue_thaw (object, nqueue);
1254   g_object_notify_queue_thaw (object, nqueue);
1255
1256   g_object_unref (object);
1257 }
1258
1259 static inline void
1260 object_get_property (GObject     *object,
1261                      GParamSpec  *pspec,
1262                      GValue      *value)
1263 {
1264   GObjectClass *class = g_type_class_peek (pspec->owner_type);
1265   guint param_id = PARAM_SPEC_PARAM_ID (pspec);
1266   GParamSpec *redirect;
1267
1268   if (class == NULL)
1269     {
1270       g_warning ("'%s::%s' is not a valid property name; '%s' is not a GObject subtype",
1271                  g_type_name (pspec->owner_type), pspec->name, g_type_name (pspec->owner_type));
1272       return;
1273     }
1274
1275   redirect = g_param_spec_get_redirect_target (pspec);
1276   if (redirect)
1277     pspec = redirect;    
1278   
1279   class->get_property (object, param_id, value, pspec);
1280 }
1281
1282 static inline void
1283 object_set_property (GObject             *object,
1284                      GParamSpec          *pspec,
1285                      const GValue        *value,
1286                      GObjectNotifyQueue  *nqueue)
1287 {
1288   GValue tmp_value = G_VALUE_INIT;
1289   GObjectClass *class = g_type_class_peek (pspec->owner_type);
1290   guint param_id = PARAM_SPEC_PARAM_ID (pspec);
1291   GParamSpec *redirect;
1292   static const gchar * enable_diagnostic = NULL;
1293
1294   if (class == NULL)
1295     {
1296       g_warning ("'%s::%s' is not a valid property name; '%s' is not a GObject subtype",
1297                  g_type_name (pspec->owner_type), pspec->name, g_type_name (pspec->owner_type));
1298       return;
1299     }
1300
1301   redirect = g_param_spec_get_redirect_target (pspec);
1302   if (redirect)
1303     pspec = redirect;
1304
1305   if (G_UNLIKELY (!enable_diagnostic))
1306     {
1307       enable_diagnostic = g_getenv ("G_ENABLE_DIAGNOSTIC");
1308       if (!enable_diagnostic)
1309         enable_diagnostic = "0";
1310     }
1311
1312   if (enable_diagnostic[0] == '1')
1313     {
1314       if (pspec->flags & G_PARAM_DEPRECATED)
1315         g_warning ("The property %s:%s is deprecated and shouldn't be used "
1316                    "anymore. It will be removed in a future version.",
1317                    G_OBJECT_TYPE_NAME (object), pspec->name);
1318     }
1319
1320   /* provide a copy to work from, convert (if necessary) and validate */
1321   g_value_init (&tmp_value, pspec->value_type);
1322   if (!g_value_transform (value, &tmp_value))
1323     g_warning ("unable to set property `%s' of type `%s' from value of type `%s'",
1324                pspec->name,
1325                g_type_name (pspec->value_type),
1326                G_VALUE_TYPE_NAME (value));
1327   else if (g_param_value_validate (pspec, &tmp_value) && !(pspec->flags & G_PARAM_LAX_VALIDATION))
1328     {
1329       gchar *contents = g_strdup_value_contents (value);
1330
1331       g_warning ("value \"%s\" of type `%s' is invalid or out of range for property `%s' of type `%s'",
1332                  contents,
1333                  G_VALUE_TYPE_NAME (value),
1334                  pspec->name,
1335                  g_type_name (pspec->value_type));
1336       g_free (contents);
1337     }
1338   else
1339     {
1340       GParamSpec *notify_pspec;
1341
1342       class->set_property (object, param_id, &tmp_value, pspec);
1343
1344       notify_pspec = get_notify_pspec (pspec);
1345
1346       if (notify_pspec != NULL)
1347         g_object_notify_queue_add (object, nqueue, notify_pspec);
1348     }
1349   g_value_unset (&tmp_value);
1350 }
1351
1352 static void
1353 object_interface_check_properties (gpointer func_data,
1354                                    gpointer g_iface)
1355 {
1356   GTypeInterface *iface_class = g_iface;
1357   GObjectClass *class;
1358   GType iface_type = iface_class->g_type;
1359   GParamSpec **pspecs;
1360   guint n;
1361
1362   class = g_type_class_ref (iface_class->g_instance_type);
1363
1364   if (!G_IS_OBJECT_CLASS (class))
1365     return;
1366
1367   pspecs = g_param_spec_pool_list (pspec_pool, iface_type, &n);
1368
1369   while (n--)
1370     {
1371       GParamSpec *class_pspec = g_param_spec_pool_lookup (pspec_pool,
1372                                                           pspecs[n]->name,
1373                                                           G_OBJECT_CLASS_TYPE (class),
1374                                                           TRUE);
1375
1376       if (!class_pspec)
1377         {
1378           g_critical ("Object class %s doesn't implement property "
1379                       "'%s' from interface '%s'",
1380                       g_type_name (G_OBJECT_CLASS_TYPE (class)),
1381                       pspecs[n]->name,
1382                       g_type_name (iface_type));
1383
1384           continue;
1385         }
1386
1387       /* We do a number of checks on the properties of an interface to
1388        * make sure that all classes implementing the interface are
1389        * overriding the properties in a sane way.
1390        *
1391        * We do the checks in order of importance so that we can give
1392        * more useful error messages first.
1393        *
1394        * First, we check that the implementation doesn't remove the
1395        * basic functionality (readability, writability) advertised by
1396        * the interface.  Next, we check that it doesn't introduce
1397        * additional restrictions (such as construct-only).  Finally, we
1398        * make sure the types are compatible.
1399        */
1400
1401 #define SUBSET(a,b,mask) (((a) & ~(b) & (mask)) == 0)
1402       /* If the property on the interface is readable then the
1403        * implementation must be readable.  If the interface is writable
1404        * then the implementation must be writable.
1405        */
1406       if (!SUBSET (pspecs[n]->flags, class_pspec->flags, G_PARAM_READABLE | G_PARAM_WRITABLE))
1407         {
1408           g_critical ("Flags for property '%s' on class '%s' remove functionality compared with the "
1409                       "property on interface '%s'\n", pspecs[n]->name,
1410                       g_type_name (G_OBJECT_CLASS_TYPE (class)), g_type_name (iface_type));
1411           continue;
1412         }
1413
1414       /* If the property on the interface is writable then we need to
1415        * make sure the implementation doesn't introduce new restrictions
1416        * on that writability (ie: construct-only).
1417        *
1418        * If the interface was not writable to begin with then we don't
1419        * really have any problems here because "writable at construct
1420        * type only" is still more permissive than "read only".
1421        */
1422       if (pspecs[n]->flags & G_PARAM_WRITABLE)
1423         {
1424           if (!SUBSET (class_pspec->flags, pspecs[n]->flags, G_PARAM_CONSTRUCT_ONLY))
1425             {
1426               g_critical ("Flags for property '%s' on class '%s' introduce additional restrictions on "
1427                           "writability compared with the property on interface '%s'\n", pspecs[n]->name,
1428                           g_type_name (G_OBJECT_CLASS_TYPE (class)), g_type_name (iface_type));
1429               continue;
1430             }
1431         }
1432 #undef SUBSET
1433
1434       /* If the property on the interface is readable then we are
1435        * effectively advertising that reading the property will return a
1436        * value of a specific type.  All implementations of the interface
1437        * need to return items of this type -- but may be more
1438        * restrictive.  For example, it is legal to have:
1439        *
1440        *   GtkWidget *get_item();
1441        *
1442        * that is implemented by a function that always returns a
1443        * GtkEntry.  In short: readability implies that the
1444        * implementation  value type must be equal or more restrictive.
1445        *
1446        * Similarly, if the property on the interface is writable then
1447        * must be able to accept the property being set to any value of
1448        * that type, including subclasses.  In this case, we may also be
1449        * less restrictive.  For example, it is legal to have:
1450        *
1451        *   set_item (GtkEntry *);
1452        *
1453        * that is implemented by a function that will actually work with
1454        * any GtkWidget.  In short: writability implies that the
1455        * implementation value type must be equal or less restrictive.
1456        *
1457        * In the case that the property is both readable and writable
1458        * then the only way that both of the above can be satisfied is
1459        * with a type that is exactly equal.
1460        */
1461       switch (pspecs[n]->flags & (G_PARAM_READABLE | G_PARAM_WRITABLE))
1462         {
1463         case G_PARAM_READABLE | G_PARAM_WRITABLE:
1464           /* class pspec value type must have exact equality with interface */
1465           if (pspecs[n]->value_type != class_pspec->value_type)
1466             g_critical ("Read/writable property '%s' on class '%s' has type '%s' which is not exactly equal to the "
1467                         "type '%s' of the property on the interface '%s'\n", pspecs[n]->name,
1468                         g_type_name (G_OBJECT_CLASS_TYPE (class)), g_type_name (G_PARAM_SPEC_VALUE_TYPE (class_pspec)),
1469                         g_type_name (G_PARAM_SPEC_VALUE_TYPE (pspecs[n])), g_type_name (iface_type));
1470           break;
1471
1472         case G_PARAM_READABLE:
1473           /* class pspec value type equal or more restrictive than interface */
1474           if (!g_type_is_a (class_pspec->value_type, pspecs[n]->value_type))
1475             g_critical ("Read-only property '%s' on class '%s' has type '%s' which is not equal to or more "
1476                         "restrictive than the type '%s' of the property on the interface '%s'\n", pspecs[n]->name,
1477                         g_type_name (G_OBJECT_CLASS_TYPE (class)), g_type_name (G_PARAM_SPEC_VALUE_TYPE (class_pspec)),
1478                         g_type_name (G_PARAM_SPEC_VALUE_TYPE (pspecs[n])), g_type_name (iface_type));
1479           break;
1480
1481         case G_PARAM_WRITABLE:
1482           /* class pspec value type equal or less restrictive than interface */
1483           if (!g_type_is_a (pspecs[n]->value_type, class_pspec->value_type))
1484             g_critical ("Write-only property '%s' on class '%s' has type '%s' which is not equal to or less "
1485                         "restrictive than the type '%s' of the property on the interface '%s' \n", pspecs[n]->name,
1486                         g_type_name (G_OBJECT_CLASS_TYPE (class)), g_type_name (G_PARAM_SPEC_VALUE_TYPE (class_pspec)),
1487                         g_type_name (G_PARAM_SPEC_VALUE_TYPE (pspecs[n])), g_type_name (iface_type));
1488           break;
1489
1490         default:
1491           g_assert_not_reached ();
1492         }
1493     }
1494
1495   g_free (pspecs);
1496
1497   g_type_class_unref (class);
1498 }
1499
1500 GType
1501 g_object_get_type (void)
1502 {
1503     return G_TYPE_OBJECT;
1504 }
1505
1506 /**
1507  * g_object_new: (skip)
1508  * @object_type: the type id of the #GObject subtype to instantiate
1509  * @first_property_name: the name of the first property
1510  * @...: the value of the first property, followed optionally by more
1511  *  name/value pairs, followed by %NULL
1512  *
1513  * Creates a new instance of a #GObject subtype and sets its properties.
1514  *
1515  * Construction parameters (see #G_PARAM_CONSTRUCT, #G_PARAM_CONSTRUCT_ONLY)
1516  * which are not explicitly specified are set to their default values.
1517  *
1518  * Returns: (transfer full): a new instance of @object_type
1519  */
1520 gpointer
1521 g_object_new (GType        object_type,
1522               const gchar *first_property_name,
1523               ...)
1524 {
1525   GObject *object;
1526   va_list var_args;
1527   
1528   g_return_val_if_fail (G_TYPE_IS_OBJECT (object_type), NULL);
1529   
1530   /* short circuit for calls supplying no properties */
1531   if (!first_property_name)
1532     return g_object_newv (object_type, 0, NULL);
1533
1534   va_start (var_args, first_property_name);
1535   object = g_object_new_valist (object_type, first_property_name, var_args);
1536   va_end (var_args);
1537   
1538   return object;
1539 }
1540
1541 static gboolean
1542 slist_maybe_remove (GSList       **slist,
1543                     gconstpointer  data)
1544 {
1545   GSList *last = NULL, *node = *slist;
1546   while (node)
1547     {
1548       if (node->data == data)
1549         {
1550           if (last)
1551             last->next = node->next;
1552           else
1553             *slist = node->next;
1554           g_slist_free_1 (node);
1555           return TRUE;
1556         }
1557       last = node;
1558       node = last->next;
1559     }
1560   return FALSE;
1561 }
1562
1563 static inline gboolean
1564 object_in_construction_list (GObject *object)
1565 {
1566   gboolean in_construction;
1567   G_LOCK (construction_mutex);
1568   in_construction = g_slist_find (construction_objects, object) != NULL;
1569   G_UNLOCK (construction_mutex);
1570   return in_construction;
1571 }
1572
1573 /**
1574  * g_object_newv:
1575  * @object_type: the type id of the #GObject subtype to instantiate
1576  * @n_parameters: the length of the @parameters array
1577  * @parameters: (array length=n_parameters): an array of #GParameter
1578  *
1579  * Creates a new instance of a #GObject subtype and sets its properties.
1580  *
1581  * Construction parameters (see #G_PARAM_CONSTRUCT, #G_PARAM_CONSTRUCT_ONLY)
1582  * which are not explicitly specified are set to their default values.
1583  *
1584  * Rename to: g_object_new
1585  * Returns: (type GObject.Object) (transfer full): a new instance of
1586  * @object_type
1587  */
1588 gpointer
1589 g_object_newv (GType       object_type,
1590                guint       n_parameters,
1591                GParameter *parameters)
1592 {
1593   GObjectConstructParam *cparams = NULL, *oparams;
1594   GObjectNotifyQueue *nqueue = NULL; /* shouldn't be initialized, just to silence compiler */
1595   GObject *object;
1596   GObjectClass *class, *unref_class = NULL;
1597   GSList *slist;
1598   guint n_total_cparams = 0, n_cparams = 0, n_oparams = 0, n_cvalues;
1599   GValue *cvalues;
1600   GList *clist = NULL;
1601   gboolean newly_constructed;
1602   guint i;
1603
1604   g_return_val_if_fail (G_TYPE_IS_OBJECT (object_type), NULL);
1605
1606   class = g_type_class_peek_static (object_type);
1607   if (!class)
1608     class = unref_class = g_type_class_ref (object_type);
1609   for (slist = class->construct_properties; slist; slist = slist->next)
1610     {
1611       clist = g_list_prepend (clist, slist->data);
1612       n_total_cparams += 1;
1613     }
1614
1615   if (n_parameters == 0 && n_total_cparams == 0)
1616     {
1617       /* This is a simple object with no construct properties, and
1618        * no properties are being set, so short circuit the parameter
1619        * handling. This speeds up simple object construction.
1620        */
1621       oparams = NULL;
1622       object = class->constructor (object_type, 0, NULL);
1623       goto did_construction;
1624     }
1625
1626   /* collect parameters, sort into construction and normal ones */
1627   oparams = g_new (GObjectConstructParam, n_parameters);
1628   cparams = g_new (GObjectConstructParam, n_total_cparams);
1629   for (i = 0; i < n_parameters; i++)
1630     {
1631       GValue *value = &parameters[i].value;
1632       GParamSpec *pspec = g_param_spec_pool_lookup (pspec_pool,
1633                                                     parameters[i].name,
1634                                                     object_type,
1635                                                     TRUE);
1636       if (!pspec)
1637         {
1638           g_warning ("%s: object class `%s' has no property named `%s'",
1639                      G_STRFUNC,
1640                      g_type_name (object_type),
1641                      parameters[i].name);
1642           continue;
1643         }
1644       if (!(pspec->flags & G_PARAM_WRITABLE))
1645         {
1646           g_warning ("%s: property `%s' of object class `%s' is not writable",
1647                      G_STRFUNC,
1648                      pspec->name,
1649                      g_type_name (object_type));
1650           continue;
1651         }
1652       if (pspec->flags & (G_PARAM_CONSTRUCT | G_PARAM_CONSTRUCT_ONLY))
1653         {
1654           GList *list = g_list_find (clist, pspec);
1655
1656           if (!list)
1657             {
1658               g_warning ("%s: construct property \"%s\" for object `%s' can't be set twice",
1659                          G_STRFUNC, pspec->name, g_type_name (object_type));
1660               continue;
1661             }
1662           cparams[n_cparams].pspec = pspec;
1663           cparams[n_cparams].value = value;
1664           n_cparams++;
1665           if (!list->prev)
1666             clist = list->next;
1667           else
1668             list->prev->next = list->next;
1669           if (list->next)
1670             list->next->prev = list->prev;
1671           g_list_free_1 (list);
1672         }
1673       else
1674         {
1675           oparams[n_oparams].pspec = pspec;
1676           oparams[n_oparams].value = value;
1677           n_oparams++;
1678         }
1679     }
1680
1681   /* set remaining construction properties to default values */
1682   n_cvalues = n_total_cparams - n_cparams;
1683   cvalues = g_new (GValue, n_cvalues);
1684   while (clist)
1685     {
1686       GList *tmp = clist->next;
1687       GParamSpec *pspec = clist->data;
1688       GValue *value = cvalues + n_total_cparams - n_cparams - 1;
1689
1690       value->g_type = 0;
1691       g_value_init (value, pspec->value_type);
1692       g_param_value_set_default (pspec, value);
1693
1694       cparams[n_cparams].pspec = pspec;
1695       cparams[n_cparams].value = value;
1696       n_cparams++;
1697
1698       g_list_free_1 (clist);
1699       clist = tmp;
1700     }
1701
1702   /* construct object from construction parameters */
1703   object = class->constructor (object_type, n_total_cparams, cparams);
1704   /* free construction values */
1705   g_free (cparams);
1706   while (n_cvalues--)
1707     g_value_unset (cvalues + n_cvalues);
1708   g_free (cvalues);
1709
1710  did_construction:
1711   if (CLASS_HAS_CUSTOM_CONSTRUCTOR (class))
1712     {
1713       /* adjust freeze_count according to g_object_init() and remaining properties */
1714       G_LOCK (construction_mutex);
1715       newly_constructed = slist_maybe_remove (&construction_objects, object);
1716       G_UNLOCK (construction_mutex);
1717     }
1718   else
1719     newly_constructed = TRUE;
1720
1721   if (CLASS_HAS_PROPS (class))
1722     {
1723       if (newly_constructed || n_oparams)
1724         nqueue = g_object_notify_queue_freeze (object, FALSE);
1725       if (newly_constructed)
1726         g_object_notify_queue_thaw (object, nqueue);
1727     }
1728
1729   /* run 'constructed' handler if there is a custom one */
1730   if (newly_constructed && CLASS_HAS_CUSTOM_CONSTRUCTED (class))
1731     class->constructed (object);
1732
1733   /* set remaining properties */
1734   for (i = 0; i < n_oparams; i++)
1735     object_set_property (object, oparams[i].pspec, oparams[i].value, nqueue);
1736   g_free (oparams);
1737
1738   if (CLASS_HAS_PROPS (class))
1739     {
1740       /* release our own freeze count and handle notifications */
1741       if (newly_constructed || n_oparams)
1742         g_object_notify_queue_thaw (object, nqueue);
1743     }
1744
1745   if (unref_class)
1746     g_type_class_unref (unref_class);
1747
1748   return object;
1749 }
1750
1751 /**
1752  * g_object_new_valist: (skip)
1753  * @object_type: the type id of the #GObject subtype to instantiate
1754  * @first_property_name: the name of the first property
1755  * @var_args: the value of the first property, followed optionally by more
1756  *  name/value pairs, followed by %NULL
1757  *
1758  * Creates a new instance of a #GObject subtype and sets its properties.
1759  *
1760  * Construction parameters (see #G_PARAM_CONSTRUCT, #G_PARAM_CONSTRUCT_ONLY)
1761  * which are not explicitly specified are set to their default values.
1762  *
1763  * Returns: a new instance of @object_type
1764  */
1765 GObject*
1766 g_object_new_valist (GType        object_type,
1767                      const gchar *first_property_name,
1768                      va_list      var_args)
1769 {
1770   GObjectClass *class;
1771   GParameter *params;
1772   const gchar *name;
1773   GObject *object;
1774   guint n_params = 0, n_alloced_params = 16;
1775   
1776   g_return_val_if_fail (G_TYPE_IS_OBJECT (object_type), NULL);
1777
1778   if (!first_property_name)
1779     return g_object_newv (object_type, 0, NULL);
1780
1781   class = g_type_class_ref (object_type);
1782
1783   params = g_new0 (GParameter, n_alloced_params);
1784   name = first_property_name;
1785   while (name)
1786     {
1787       gchar *error = NULL;
1788       GParamSpec *pspec = g_param_spec_pool_lookup (pspec_pool,
1789                                                     name,
1790                                                     object_type,
1791                                                     TRUE);
1792       if (!pspec)
1793         {
1794           g_warning ("%s: object class `%s' has no property named `%s'",
1795                      G_STRFUNC,
1796                      g_type_name (object_type),
1797                      name);
1798           break;
1799         }
1800       if (n_params >= n_alloced_params)
1801         {
1802           n_alloced_params += 16;
1803           params = g_renew (GParameter, params, n_alloced_params);
1804           memset (params + n_params, 0, 16 * (sizeof *params));
1805         }
1806       params[n_params].name = name;
1807       G_VALUE_COLLECT_INIT (&params[n_params].value, pspec->value_type,
1808                             var_args, 0, &error);
1809       if (error)
1810         {
1811           g_warning ("%s: %s", G_STRFUNC, error);
1812           g_free (error);
1813           g_value_unset (&params[n_params].value);
1814           break;
1815         }
1816       n_params++;
1817       name = va_arg (var_args, gchar*);
1818     }
1819
1820   object = g_object_newv (object_type, n_params, params);
1821
1822   while (n_params--)
1823     g_value_unset (&params[n_params].value);
1824   g_free (params);
1825
1826   g_type_class_unref (class);
1827
1828   return object;
1829 }
1830
1831 static GObject*
1832 g_object_constructor (GType                  type,
1833                       guint                  n_construct_properties,
1834                       GObjectConstructParam *construct_params)
1835 {
1836   GObject *object;
1837
1838   /* create object */
1839   object = (GObject*) g_type_create_instance (type);
1840   
1841   /* set construction parameters */
1842   if (n_construct_properties)
1843     {
1844       GObjectNotifyQueue *nqueue = g_object_notify_queue_freeze (object, FALSE);
1845       
1846       /* set construct properties */
1847       while (n_construct_properties--)
1848         {
1849           GValue *value = construct_params->value;
1850           GParamSpec *pspec = construct_params->pspec;
1851
1852           construct_params++;
1853           object_set_property (object, pspec, value, nqueue);
1854         }
1855       g_object_notify_queue_thaw (object, nqueue);
1856       /* the notification queue is still frozen from g_object_init(), so
1857        * we don't need to handle it here, g_object_newv() takes
1858        * care of that
1859        */
1860     }
1861
1862   return object;
1863 }
1864
1865 static void
1866 g_object_constructed (GObject *object)
1867 {
1868   /* empty default impl to allow unconditional upchaining */
1869 }
1870
1871 /**
1872  * g_object_set_valist: (skip)
1873  * @object: a #GObject
1874  * @first_property_name: name of the first property to set
1875  * @var_args: value for the first property, followed optionally by more
1876  *  name/value pairs, followed by %NULL
1877  *
1878  * Sets properties on an object.
1879  */
1880 void
1881 g_object_set_valist (GObject     *object,
1882                      const gchar *first_property_name,
1883                      va_list      var_args)
1884 {
1885   GObjectNotifyQueue *nqueue;
1886   const gchar *name;
1887   
1888   g_return_if_fail (G_IS_OBJECT (object));
1889   
1890   g_object_ref (object);
1891   nqueue = g_object_notify_queue_freeze (object, FALSE);
1892   
1893   name = first_property_name;
1894   while (name)
1895     {
1896       GValue value = G_VALUE_INIT;
1897       GParamSpec *pspec;
1898       gchar *error = NULL;
1899       
1900       pspec = g_param_spec_pool_lookup (pspec_pool,
1901                                         name,
1902                                         G_OBJECT_TYPE (object),
1903                                         TRUE);
1904       if (!pspec)
1905         {
1906           g_warning ("%s: object class `%s' has no property named `%s'",
1907                      G_STRFUNC,
1908                      G_OBJECT_TYPE_NAME (object),
1909                      name);
1910           break;
1911         }
1912       if (!(pspec->flags & G_PARAM_WRITABLE))
1913         {
1914           g_warning ("%s: property `%s' of object class `%s' is not writable",
1915                      G_STRFUNC,
1916                      pspec->name,
1917                      G_OBJECT_TYPE_NAME (object));
1918           break;
1919         }
1920       if ((pspec->flags & G_PARAM_CONSTRUCT_ONLY) && !object_in_construction_list (object))
1921         {
1922           g_warning ("%s: construct property \"%s\" for object `%s' can't be set after construction",
1923                      G_STRFUNC, pspec->name, G_OBJECT_TYPE_NAME (object));
1924           break;
1925         }
1926
1927       G_VALUE_COLLECT_INIT (&value, pspec->value_type, var_args,
1928                             0, &error);
1929       if (error)
1930         {
1931           g_warning ("%s: %s", G_STRFUNC, error);
1932           g_free (error);
1933           g_value_unset (&value);
1934           break;
1935         }
1936       
1937       object_set_property (object, pspec, &value, nqueue);
1938       g_value_unset (&value);
1939       
1940       name = va_arg (var_args, gchar*);
1941     }
1942
1943   g_object_notify_queue_thaw (object, nqueue);
1944   g_object_unref (object);
1945 }
1946
1947 /**
1948  * g_object_get_valist: (skip)
1949  * @object: a #GObject
1950  * @first_property_name: name of the first property to get
1951  * @var_args: return location for the first property, followed optionally by more
1952  *  name/return location pairs, followed by %NULL
1953  *
1954  * Gets properties of an object.
1955  *
1956  * In general, a copy is made of the property contents and the caller
1957  * is responsible for freeing the memory in the appropriate manner for
1958  * the type, for instance by calling g_free() or g_object_unref().
1959  *
1960  * See g_object_get().
1961  */
1962 void
1963 g_object_get_valist (GObject     *object,
1964                      const gchar *first_property_name,
1965                      va_list      var_args)
1966 {
1967   const gchar *name;
1968   
1969   g_return_if_fail (G_IS_OBJECT (object));
1970   
1971   g_object_ref (object);
1972   
1973   name = first_property_name;
1974   
1975   while (name)
1976     {
1977       GValue value = G_VALUE_INIT;
1978       GParamSpec *pspec;
1979       gchar *error;
1980       
1981       pspec = g_param_spec_pool_lookup (pspec_pool,
1982                                         name,
1983                                         G_OBJECT_TYPE (object),
1984                                         TRUE);
1985       if (!pspec)
1986         {
1987           g_warning ("%s: object class `%s' has no property named `%s'",
1988                      G_STRFUNC,
1989                      G_OBJECT_TYPE_NAME (object),
1990                      name);
1991           break;
1992         }
1993       if (!(pspec->flags & G_PARAM_READABLE))
1994         {
1995           g_warning ("%s: property `%s' of object class `%s' is not readable",
1996                      G_STRFUNC,
1997                      pspec->name,
1998                      G_OBJECT_TYPE_NAME (object));
1999           break;
2000         }
2001       
2002       g_value_init (&value, pspec->value_type);
2003       
2004       object_get_property (object, pspec, &value);
2005       
2006       G_VALUE_LCOPY (&value, var_args, 0, &error);
2007       if (error)
2008         {
2009           g_warning ("%s: %s", G_STRFUNC, error);
2010           g_free (error);
2011           g_value_unset (&value);
2012           break;
2013         }
2014       
2015       g_value_unset (&value);
2016       
2017       name = va_arg (var_args, gchar*);
2018     }
2019   
2020   g_object_unref (object);
2021 }
2022
2023 /**
2024  * g_object_set: (skip)
2025  * @object: a #GObject
2026  * @first_property_name: name of the first property to set
2027  * @...: value for the first property, followed optionally by more
2028  *  name/value pairs, followed by %NULL
2029  *
2030  * Sets properties on an object.
2031  */
2032 void
2033 g_object_set (gpointer     _object,
2034               const gchar *first_property_name,
2035               ...)
2036 {
2037   GObject *object = _object;
2038   va_list var_args;
2039   
2040   g_return_if_fail (G_IS_OBJECT (object));
2041   
2042   va_start (var_args, first_property_name);
2043   g_object_set_valist (object, first_property_name, var_args);
2044   va_end (var_args);
2045 }
2046
2047 /**
2048  * g_object_get: (skip)
2049  * @object: a #GObject
2050  * @first_property_name: name of the first property to get
2051  * @...: return location for the first property, followed optionally by more
2052  *  name/return location pairs, followed by %NULL
2053  *
2054  * Gets properties of an object.
2055  *
2056  * In general, a copy is made of the property contents and the caller
2057  * is responsible for freeing the memory in the appropriate manner for
2058  * the type, for instance by calling g_free() or g_object_unref().
2059  *
2060  * <example>
2061  * <title>Using g_object_get(<!-- -->)</title>
2062  * An example of using g_object_get() to get the contents
2063  * of three properties - one of type #G_TYPE_INT,
2064  * one of type #G_TYPE_STRING, and one of type #G_TYPE_OBJECT:
2065  * <programlisting>
2066  *  gint intval;
2067  *  gchar *strval;
2068  *  GObject *objval;
2069  *
2070  *  g_object_get (my_object,
2071  *                "int-property", &intval,
2072  *                "str-property", &strval,
2073  *                "obj-property", &objval,
2074  *                NULL);
2075  *
2076  *  // Do something with intval, strval, objval
2077  *
2078  *  g_free (strval);
2079  *  g_object_unref (objval);
2080  * </programlisting>
2081  * </example>
2082  */
2083 void
2084 g_object_get (gpointer     _object,
2085               const gchar *first_property_name,
2086               ...)
2087 {
2088   GObject *object = _object;
2089   va_list var_args;
2090   
2091   g_return_if_fail (G_IS_OBJECT (object));
2092   
2093   va_start (var_args, first_property_name);
2094   g_object_get_valist (object, first_property_name, var_args);
2095   va_end (var_args);
2096 }
2097
2098 /**
2099  * g_object_set_property:
2100  * @object: a #GObject
2101  * @property_name: the name of the property to set
2102  * @value: the value
2103  *
2104  * Sets a property on an object.
2105  */
2106 void
2107 g_object_set_property (GObject      *object,
2108                        const gchar  *property_name,
2109                        const GValue *value)
2110 {
2111   GObjectNotifyQueue *nqueue;
2112   GParamSpec *pspec;
2113   
2114   g_return_if_fail (G_IS_OBJECT (object));
2115   g_return_if_fail (property_name != NULL);
2116   g_return_if_fail (G_IS_VALUE (value));
2117   
2118   g_object_ref (object);
2119   nqueue = g_object_notify_queue_freeze (object, FALSE);
2120   
2121   pspec = g_param_spec_pool_lookup (pspec_pool,
2122                                     property_name,
2123                                     G_OBJECT_TYPE (object),
2124                                     TRUE);
2125   if (!pspec)
2126     g_warning ("%s: object class `%s' has no property named `%s'",
2127                G_STRFUNC,
2128                G_OBJECT_TYPE_NAME (object),
2129                property_name);
2130   else if (!(pspec->flags & G_PARAM_WRITABLE))
2131     g_warning ("%s: property `%s' of object class `%s' is not writable",
2132                G_STRFUNC,
2133                pspec->name,
2134                G_OBJECT_TYPE_NAME (object));
2135   else if ((pspec->flags & G_PARAM_CONSTRUCT_ONLY) && !object_in_construction_list (object))
2136     g_warning ("%s: construct property \"%s\" for object `%s' can't be set after construction",
2137                G_STRFUNC, pspec->name, G_OBJECT_TYPE_NAME (object));
2138   else
2139     object_set_property (object, pspec, value, nqueue);
2140   
2141   g_object_notify_queue_thaw (object, nqueue);
2142   g_object_unref (object);
2143 }
2144
2145 /**
2146  * g_object_get_property:
2147  * @object: a #GObject
2148  * @property_name: the name of the property to get
2149  * @value: return location for the property value
2150  *
2151  * Gets a property of an object. @value must have been initialized to the
2152  * expected type of the property (or a type to which the expected type can be
2153  * transformed) using g_value_init().
2154  *
2155  * In general, a copy is made of the property contents and the caller is
2156  * responsible for freeing the memory by calling g_value_unset().
2157  *
2158  * Note that g_object_get_property() is really intended for language
2159  * bindings, g_object_get() is much more convenient for C programming.
2160  */
2161 void
2162 g_object_get_property (GObject     *object,
2163                        const gchar *property_name,
2164                        GValue      *value)
2165 {
2166   GParamSpec *pspec;
2167   
2168   g_return_if_fail (G_IS_OBJECT (object));
2169   g_return_if_fail (property_name != NULL);
2170   g_return_if_fail (G_IS_VALUE (value));
2171   
2172   g_object_ref (object);
2173   
2174   pspec = g_param_spec_pool_lookup (pspec_pool,
2175                                     property_name,
2176                                     G_OBJECT_TYPE (object),
2177                                     TRUE);
2178   if (!pspec)
2179     g_warning ("%s: object class `%s' has no property named `%s'",
2180                G_STRFUNC,
2181                G_OBJECT_TYPE_NAME (object),
2182                property_name);
2183   else if (!(pspec->flags & G_PARAM_READABLE))
2184     g_warning ("%s: property `%s' of object class `%s' is not readable",
2185                G_STRFUNC,
2186                pspec->name,
2187                G_OBJECT_TYPE_NAME (object));
2188   else
2189     {
2190       GValue *prop_value, tmp_value = G_VALUE_INIT;
2191       
2192       /* auto-conversion of the callers value type
2193        */
2194       if (G_VALUE_TYPE (value) == pspec->value_type)
2195         {
2196           g_value_reset (value);
2197           prop_value = value;
2198         }
2199       else if (!g_value_type_transformable (pspec->value_type, G_VALUE_TYPE (value)))
2200         {
2201           g_warning ("%s: can't retrieve property `%s' of type `%s' as value of type `%s'",
2202                      G_STRFUNC, pspec->name,
2203                      g_type_name (pspec->value_type),
2204                      G_VALUE_TYPE_NAME (value));
2205           g_object_unref (object);
2206           return;
2207         }
2208       else
2209         {
2210           g_value_init (&tmp_value, pspec->value_type);
2211           prop_value = &tmp_value;
2212         }
2213       object_get_property (object, pspec, prop_value);
2214       if (prop_value != value)
2215         {
2216           g_value_transform (prop_value, value);
2217           g_value_unset (&tmp_value);
2218         }
2219     }
2220   
2221   g_object_unref (object);
2222 }
2223
2224 /**
2225  * g_object_connect: (skip)
2226  * @object: a #GObject
2227  * @signal_spec: the spec for the first signal
2228  * @...: #GCallback for the first signal, followed by data for the
2229  *       first signal, followed optionally by more signal
2230  *       spec/callback/data triples, followed by %NULL
2231  *
2232  * A convenience function to connect multiple signals at once.
2233  *
2234  * The signal specs expected by this function have the form
2235  * "modifier::signal_name", where modifier can be one of the following:
2236  * <variablelist>
2237  * <varlistentry>
2238  * <term>signal</term>
2239  * <listitem><para>
2240  * equivalent to <literal>g_signal_connect_data (..., NULL, 0)</literal>
2241  * </para></listitem>
2242  * </varlistentry>
2243  * <varlistentry>
2244  * <term>object_signal</term>
2245  * <term>object-signal</term>
2246  * <listitem><para>
2247  * equivalent to <literal>g_signal_connect_object (..., 0)</literal>
2248  * </para></listitem>
2249  * </varlistentry>
2250  * <varlistentry>
2251  * <term>swapped_signal</term>
2252  * <term>swapped-signal</term>
2253  * <listitem><para>
2254  * equivalent to <literal>g_signal_connect_data (..., NULL, G_CONNECT_SWAPPED)</literal>
2255  * </para></listitem>
2256  * </varlistentry>
2257  * <varlistentry>
2258  * <term>swapped_object_signal</term>
2259  * <term>swapped-object-signal</term>
2260  * <listitem><para>
2261  * equivalent to <literal>g_signal_connect_object (..., G_CONNECT_SWAPPED)</literal>
2262  * </para></listitem>
2263  * </varlistentry>
2264  * <varlistentry>
2265  * <term>signal_after</term>
2266  * <term>signal-after</term>
2267  * <listitem><para>
2268  * equivalent to <literal>g_signal_connect_data (..., NULL, G_CONNECT_AFTER)</literal>
2269  * </para></listitem>
2270  * </varlistentry>
2271  * <varlistentry>
2272  * <term>object_signal_after</term>
2273  * <term>object-signal-after</term>
2274  * <listitem><para>
2275  * equivalent to <literal>g_signal_connect_object (..., G_CONNECT_AFTER)</literal>
2276  * </para></listitem>
2277  * </varlistentry>
2278  * <varlistentry>
2279  * <term>swapped_signal_after</term>
2280  * <term>swapped-signal-after</term>
2281  * <listitem><para>
2282  * equivalent to <literal>g_signal_connect_data (..., NULL, G_CONNECT_SWAPPED | G_CONNECT_AFTER)</literal>
2283  * </para></listitem>
2284  * </varlistentry>
2285  * <varlistentry>
2286  * <term>swapped_object_signal_after</term>
2287  * <term>swapped-object-signal-after</term>
2288  * <listitem><para>
2289  * equivalent to <literal>g_signal_connect_object (..., G_CONNECT_SWAPPED | G_CONNECT_AFTER)</literal>
2290  * </para></listitem>
2291  * </varlistentry>
2292  * </variablelist>
2293  *
2294  * |[
2295  *   menu->toplevel = g_object_connect (g_object_new (GTK_TYPE_WINDOW,
2296  *                                                 "type", GTK_WINDOW_POPUP,
2297  *                                                 "child", menu,
2298  *                                                 NULL),
2299  *                                   "signal::event", gtk_menu_window_event, menu,
2300  *                                   "signal::size_request", gtk_menu_window_size_request, menu,
2301  *                                   "signal::destroy", gtk_widget_destroyed, &amp;menu-&gt;toplevel,
2302  *                                   NULL);
2303  * ]|
2304  *
2305  * Returns: (transfer none): @object
2306  */
2307 gpointer
2308 g_object_connect (gpointer     _object,
2309                   const gchar *signal_spec,
2310                   ...)
2311 {
2312   GObject *object = _object;
2313   va_list var_args;
2314
2315   g_return_val_if_fail (G_IS_OBJECT (object), NULL);
2316   g_return_val_if_fail (object->ref_count > 0, object);
2317
2318   va_start (var_args, signal_spec);
2319   while (signal_spec)
2320     {
2321       GCallback callback = va_arg (var_args, GCallback);
2322       gpointer data = va_arg (var_args, gpointer);
2323
2324       if (strncmp (signal_spec, "signal::", 8) == 0)
2325         g_signal_connect_data (object, signal_spec + 8,
2326                                callback, data, NULL,
2327                                0);
2328       else if (strncmp (signal_spec, "object_signal::", 15) == 0 ||
2329                strncmp (signal_spec, "object-signal::", 15) == 0)
2330         g_signal_connect_object (object, signal_spec + 15,
2331                                  callback, data,
2332                                  0);
2333       else if (strncmp (signal_spec, "swapped_signal::", 16) == 0 ||
2334                strncmp (signal_spec, "swapped-signal::", 16) == 0)
2335         g_signal_connect_data (object, signal_spec + 16,
2336                                callback, data, NULL,
2337                                G_CONNECT_SWAPPED);
2338       else if (strncmp (signal_spec, "swapped_object_signal::", 23) == 0 ||
2339                strncmp (signal_spec, "swapped-object-signal::", 23) == 0)
2340         g_signal_connect_object (object, signal_spec + 23,
2341                                  callback, data,
2342                                  G_CONNECT_SWAPPED);
2343       else if (strncmp (signal_spec, "signal_after::", 14) == 0 ||
2344                strncmp (signal_spec, "signal-after::", 14) == 0)
2345         g_signal_connect_data (object, signal_spec + 14,
2346                                callback, data, NULL,
2347                                G_CONNECT_AFTER);
2348       else if (strncmp (signal_spec, "object_signal_after::", 21) == 0 ||
2349                strncmp (signal_spec, "object-signal-after::", 21) == 0)
2350         g_signal_connect_object (object, signal_spec + 21,
2351                                  callback, data,
2352                                  G_CONNECT_AFTER);
2353       else if (strncmp (signal_spec, "swapped_signal_after::", 22) == 0 ||
2354                strncmp (signal_spec, "swapped-signal-after::", 22) == 0)
2355         g_signal_connect_data (object, signal_spec + 22,
2356                                callback, data, NULL,
2357                                G_CONNECT_SWAPPED | G_CONNECT_AFTER);
2358       else if (strncmp (signal_spec, "swapped_object_signal_after::", 29) == 0 ||
2359                strncmp (signal_spec, "swapped-object-signal-after::", 29) == 0)
2360         g_signal_connect_object (object, signal_spec + 29,
2361                                  callback, data,
2362                                  G_CONNECT_SWAPPED | G_CONNECT_AFTER);
2363       else
2364         {
2365           g_warning ("%s: invalid signal spec \"%s\"", G_STRFUNC, signal_spec);
2366           break;
2367         }
2368       signal_spec = va_arg (var_args, gchar*);
2369     }
2370   va_end (var_args);
2371
2372   return object;
2373 }
2374
2375 /**
2376  * g_object_disconnect: (skip)
2377  * @object: a #GObject
2378  * @signal_spec: the spec for the first signal
2379  * @...: #GCallback for the first signal, followed by data for the first signal,
2380  *  followed optionally by more signal spec/callback/data triples,
2381  *  followed by %NULL
2382  *
2383  * A convenience function to disconnect multiple signals at once.
2384  *
2385  * The signal specs expected by this function have the form
2386  * "any_signal", which means to disconnect any signal with matching
2387  * callback and data, or "any_signal::signal_name", which only
2388  * disconnects the signal named "signal_name".
2389  */
2390 void
2391 g_object_disconnect (gpointer     _object,
2392                      const gchar *signal_spec,
2393                      ...)
2394 {
2395   GObject *object = _object;
2396   va_list var_args;
2397
2398   g_return_if_fail (G_IS_OBJECT (object));
2399   g_return_if_fail (object->ref_count > 0);
2400
2401   va_start (var_args, signal_spec);
2402   while (signal_spec)
2403     {
2404       GCallback callback = va_arg (var_args, GCallback);
2405       gpointer data = va_arg (var_args, gpointer);
2406       guint sid = 0, detail = 0, mask = 0;
2407
2408       if (strncmp (signal_spec, "any_signal::", 12) == 0 ||
2409           strncmp (signal_spec, "any-signal::", 12) == 0)
2410         {
2411           signal_spec += 12;
2412           mask = G_SIGNAL_MATCH_ID | G_SIGNAL_MATCH_FUNC | G_SIGNAL_MATCH_DATA;
2413         }
2414       else if (strcmp (signal_spec, "any_signal") == 0 ||
2415                strcmp (signal_spec, "any-signal") == 0)
2416         {
2417           signal_spec += 10;
2418           mask = G_SIGNAL_MATCH_FUNC | G_SIGNAL_MATCH_DATA;
2419         }
2420       else
2421         {
2422           g_warning ("%s: invalid signal spec \"%s\"", G_STRFUNC, signal_spec);
2423           break;
2424         }
2425
2426       if ((mask & G_SIGNAL_MATCH_ID) &&
2427           !g_signal_parse_name (signal_spec, G_OBJECT_TYPE (object), &sid, &detail, FALSE))
2428         g_warning ("%s: invalid signal name \"%s\"", G_STRFUNC, signal_spec);
2429       else if (!g_signal_handlers_disconnect_matched (object, mask | (detail ? G_SIGNAL_MATCH_DETAIL : 0),
2430                                                       sid, detail,
2431                                                       NULL, (gpointer)callback, data))
2432         g_warning ("%s: signal handler %p(%p) is not connected", G_STRFUNC, callback, data);
2433       signal_spec = va_arg (var_args, gchar*);
2434     }
2435   va_end (var_args);
2436 }
2437
2438 typedef struct {
2439   GObject *object;
2440   guint n_weak_refs;
2441   struct {
2442     GWeakNotify notify;
2443     gpointer    data;
2444   } weak_refs[1];  /* flexible array */
2445 } WeakRefStack;
2446
2447 static void
2448 weak_refs_notify (gpointer data)
2449 {
2450   WeakRefStack *wstack = data;
2451   guint i;
2452
2453   for (i = 0; i < wstack->n_weak_refs; i++)
2454     wstack->weak_refs[i].notify (wstack->weak_refs[i].data, wstack->object);
2455   g_free (wstack);
2456 }
2457
2458 /**
2459  * g_object_weak_ref: (skip)
2460  * @object: #GObject to reference weakly
2461  * @notify: callback to invoke before the object is freed
2462  * @data: extra data to pass to notify
2463  *
2464  * Adds a weak reference callback to an object. Weak references are
2465  * used for notification when an object is finalized. They are called
2466  * "weak references" because they allow you to safely hold a pointer
2467  * to an object without calling g_object_ref() (g_object_ref() adds a
2468  * strong reference, that is, forces the object to stay alive).
2469  *
2470  * Note that the weak references created by this method are not
2471  * thread-safe: they cannot safely be used in one thread if the
2472  * object's last g_object_unref() might happen in another thread.
2473  * Use #GWeakRef if thread-safety is required.
2474  */
2475 void
2476 g_object_weak_ref (GObject    *object,
2477                    GWeakNotify notify,
2478                    gpointer    data)
2479 {
2480   WeakRefStack *wstack;
2481   guint i;
2482   
2483   g_return_if_fail (G_IS_OBJECT (object));
2484   g_return_if_fail (notify != NULL);
2485   g_return_if_fail (object->ref_count >= 1);
2486
2487   G_LOCK (weak_refs_mutex);
2488   wstack = g_datalist_id_remove_no_notify (&object->qdata, quark_weak_refs);
2489   if (wstack)
2490     {
2491       i = wstack->n_weak_refs++;
2492       wstack = g_realloc (wstack, sizeof (*wstack) + sizeof (wstack->weak_refs[0]) * i);
2493     }
2494   else
2495     {
2496       wstack = g_renew (WeakRefStack, NULL, 1);
2497       wstack->object = object;
2498       wstack->n_weak_refs = 1;
2499       i = 0;
2500     }
2501   wstack->weak_refs[i].notify = notify;
2502   wstack->weak_refs[i].data = data;
2503   g_datalist_id_set_data_full (&object->qdata, quark_weak_refs, wstack, weak_refs_notify);
2504   G_UNLOCK (weak_refs_mutex);
2505 }
2506
2507 /**
2508  * g_object_weak_unref: (skip)
2509  * @object: #GObject to remove a weak reference from
2510  * @notify: callback to search for
2511  * @data: data to search for
2512  *
2513  * Removes a weak reference callback to an object.
2514  */
2515 void
2516 g_object_weak_unref (GObject    *object,
2517                      GWeakNotify notify,
2518                      gpointer    data)
2519 {
2520   WeakRefStack *wstack;
2521   gboolean found_one = FALSE;
2522
2523   g_return_if_fail (G_IS_OBJECT (object));
2524   g_return_if_fail (notify != NULL);
2525
2526   G_LOCK (weak_refs_mutex);
2527   wstack = g_datalist_id_get_data (&object->qdata, quark_weak_refs);
2528   if (wstack)
2529     {
2530       guint i;
2531
2532       for (i = 0; i < wstack->n_weak_refs; i++)
2533         if (wstack->weak_refs[i].notify == notify &&
2534             wstack->weak_refs[i].data == data)
2535           {
2536             found_one = TRUE;
2537             wstack->n_weak_refs -= 1;
2538             if (i != wstack->n_weak_refs)
2539               wstack->weak_refs[i] = wstack->weak_refs[wstack->n_weak_refs];
2540
2541             break;
2542           }
2543     }
2544   G_UNLOCK (weak_refs_mutex);
2545   if (!found_one)
2546     g_warning ("%s: couldn't find weak ref %p(%p)", G_STRFUNC, notify, data);
2547 }
2548
2549 /**
2550  * g_object_add_weak_pointer: (skip)
2551  * @object: The object that should be weak referenced.
2552  * @weak_pointer_location: (inout): The memory address of a pointer.
2553  *
2554  * Adds a weak reference from weak_pointer to @object to indicate that
2555  * the pointer located at @weak_pointer_location is only valid during
2556  * the lifetime of @object. When the @object is finalized,
2557  * @weak_pointer will be set to %NULL.
2558  *
2559  * Note that as with g_object_weak_ref(), the weak references created by
2560  * this method are not thread-safe: they cannot safely be used in one
2561  * thread if the object's last g_object_unref() might happen in another
2562  * thread. Use #GWeakRef if thread-safety is required.
2563  */
2564 void
2565 g_object_add_weak_pointer (GObject  *object, 
2566                            gpointer *weak_pointer_location)
2567 {
2568   g_return_if_fail (G_IS_OBJECT (object));
2569   g_return_if_fail (weak_pointer_location != NULL);
2570
2571   g_object_weak_ref (object, 
2572                      (GWeakNotify) g_nullify_pointer, 
2573                      weak_pointer_location);
2574 }
2575
2576 /**
2577  * g_object_remove_weak_pointer: (skip)
2578  * @object: The object that is weak referenced.
2579  * @weak_pointer_location: (inout): The memory address of a pointer.
2580  *
2581  * Removes a weak reference from @object that was previously added
2582  * using g_object_add_weak_pointer(). The @weak_pointer_location has
2583  * to match the one used with g_object_add_weak_pointer().
2584  */
2585 void
2586 g_object_remove_weak_pointer (GObject  *object, 
2587                               gpointer *weak_pointer_location)
2588 {
2589   g_return_if_fail (G_IS_OBJECT (object));
2590   g_return_if_fail (weak_pointer_location != NULL);
2591
2592   g_object_weak_unref (object, 
2593                        (GWeakNotify) g_nullify_pointer, 
2594                        weak_pointer_location);
2595 }
2596
2597 static guint
2598 object_floating_flag_handler (GObject        *object,
2599                               gint            job)
2600 {
2601   switch (job)
2602     {
2603       gpointer oldvalue;
2604     case +1:    /* force floating if possible */
2605       do
2606         oldvalue = g_atomic_pointer_get (&object->qdata);
2607       while (!g_atomic_pointer_compare_and_exchange ((void**) &object->qdata, oldvalue,
2608                                                      (gpointer) ((gsize) oldvalue | OBJECT_FLOATING_FLAG)));
2609       return (gsize) oldvalue & OBJECT_FLOATING_FLAG;
2610     case -1:    /* sink if possible */
2611       do
2612         oldvalue = g_atomic_pointer_get (&object->qdata);
2613       while (!g_atomic_pointer_compare_and_exchange ((void**) &object->qdata, oldvalue,
2614                                                      (gpointer) ((gsize) oldvalue & ~(gsize) OBJECT_FLOATING_FLAG)));
2615       return (gsize) oldvalue & OBJECT_FLOATING_FLAG;
2616     default:    /* check floating */
2617       return 0 != ((gsize) g_atomic_pointer_get (&object->qdata) & OBJECT_FLOATING_FLAG);
2618     }
2619 }
2620
2621 /**
2622  * g_object_is_floating:
2623  * @object: (type GObject.Object): a #GObject
2624  *
2625  * Checks whether @object has a <link linkend="floating-ref">floating</link>
2626  * reference.
2627  *
2628  * Since: 2.10
2629  *
2630  * Returns: %TRUE if @object has a floating reference
2631  */
2632 gboolean
2633 g_object_is_floating (gpointer _object)
2634 {
2635   GObject *object = _object;
2636   g_return_val_if_fail (G_IS_OBJECT (object), FALSE);
2637   return floating_flag_handler (object, 0);
2638 }
2639
2640 /**
2641  * g_object_ref_sink:
2642  * @object: (type GObject.Object): a #GObject
2643  *
2644  * Increase the reference count of @object, and possibly remove the
2645  * <link linkend="floating-ref">floating</link> reference, if @object
2646  * has a floating reference.
2647  *
2648  * In other words, if the object is floating, then this call "assumes
2649  * ownership" of the floating reference, converting it to a normal
2650  * reference by clearing the floating flag while leaving the reference
2651  * count unchanged.  If the object is not floating, then this call
2652  * adds a new normal reference increasing the reference count by one.
2653  *
2654  * Since: 2.10
2655  *
2656  * Returns: (type GObject.Object) (transfer none): @object
2657  */
2658 gpointer
2659 g_object_ref_sink (gpointer _object)
2660 {
2661   GObject *object = _object;
2662   gboolean was_floating;
2663   g_return_val_if_fail (G_IS_OBJECT (object), object);
2664   g_return_val_if_fail (object->ref_count >= 1, object);
2665   g_object_ref (object);
2666   was_floating = floating_flag_handler (object, -1);
2667   if (was_floating)
2668     g_object_unref (object);
2669   return object;
2670 }
2671
2672 /**
2673  * g_object_force_floating:
2674  * @object: a #GObject
2675  *
2676  * This function is intended for #GObject implementations to re-enforce a
2677  * <link linkend="floating-ref">floating</link> object reference.
2678  * Doing this is seldom required: all
2679  * #GInitiallyUnowned<!-- -->s are created with a floating reference which
2680  * usually just needs to be sunken by calling g_object_ref_sink().
2681  *
2682  * Since: 2.10
2683  */
2684 void
2685 g_object_force_floating (GObject *object)
2686 {
2687   g_return_if_fail (G_IS_OBJECT (object));
2688   g_return_if_fail (object->ref_count >= 1);
2689
2690   floating_flag_handler (object, +1);
2691 }
2692
2693 typedef struct {
2694   GObject *object;
2695   guint n_toggle_refs;
2696   struct {
2697     GToggleNotify notify;
2698     gpointer    data;
2699   } toggle_refs[1];  /* flexible array */
2700 } ToggleRefStack;
2701
2702 static void
2703 toggle_refs_notify (GObject *object,
2704                     gboolean is_last_ref)
2705 {
2706   ToggleRefStack tstack, *tstackptr;
2707
2708   G_LOCK (toggle_refs_mutex);
2709   tstackptr = g_datalist_id_get_data (&object->qdata, quark_toggle_refs);
2710   tstack = *tstackptr;
2711   G_UNLOCK (toggle_refs_mutex);
2712
2713   /* Reentrancy here is not as tricky as it seems, because a toggle reference
2714    * will only be notified when there is exactly one of them.
2715    */
2716   g_assert (tstack.n_toggle_refs == 1);
2717   tstack.toggle_refs[0].notify (tstack.toggle_refs[0].data, tstack.object, is_last_ref);
2718 }
2719
2720 /**
2721  * g_object_add_toggle_ref: (skip)
2722  * @object: a #GObject
2723  * @notify: a function to call when this reference is the
2724  *  last reference to the object, or is no longer
2725  *  the last reference.
2726  * @data: data to pass to @notify
2727  *
2728  * Increases the reference count of the object by one and sets a
2729  * callback to be called when all other references to the object are
2730  * dropped, or when this is already the last reference to the object
2731  * and another reference is established.
2732  *
2733  * This functionality is intended for binding @object to a proxy
2734  * object managed by another memory manager. This is done with two
2735  * paired references: the strong reference added by
2736  * g_object_add_toggle_ref() and a reverse reference to the proxy
2737  * object which is either a strong reference or weak reference.
2738  *
2739  * The setup is that when there are no other references to @object,
2740  * only a weak reference is held in the reverse direction from @object
2741  * to the proxy object, but when there are other references held to
2742  * @object, a strong reference is held. The @notify callback is called
2743  * when the reference from @object to the proxy object should be
2744  * <firstterm>toggled</firstterm> from strong to weak (@is_last_ref
2745  * true) or weak to strong (@is_last_ref false).
2746  *
2747  * Since a (normal) reference must be held to the object before
2748  * calling g_object_add_toggle_ref(), the initial state of the reverse
2749  * link is always strong.
2750  *
2751  * Multiple toggle references may be added to the same gobject,
2752  * however if there are multiple toggle references to an object, none
2753  * of them will ever be notified until all but one are removed.  For
2754  * this reason, you should only ever use a toggle reference if there
2755  * is important state in the proxy object.
2756  *
2757  * Since: 2.8
2758  */
2759 void
2760 g_object_add_toggle_ref (GObject       *object,
2761                          GToggleNotify  notify,
2762                          gpointer       data)
2763 {
2764   ToggleRefStack *tstack;
2765   guint i;
2766   
2767   g_return_if_fail (G_IS_OBJECT (object));
2768   g_return_if_fail (notify != NULL);
2769   g_return_if_fail (object->ref_count >= 1);
2770
2771   g_object_ref (object);
2772
2773   G_LOCK (toggle_refs_mutex);
2774   tstack = g_datalist_id_remove_no_notify (&object->qdata, quark_toggle_refs);
2775   if (tstack)
2776     {
2777       i = tstack->n_toggle_refs++;
2778       /* allocate i = tstate->n_toggle_refs - 1 positions beyond the 1 declared
2779        * in tstate->toggle_refs */
2780       tstack = g_realloc (tstack, sizeof (*tstack) + sizeof (tstack->toggle_refs[0]) * i);
2781     }
2782   else
2783     {
2784       tstack = g_renew (ToggleRefStack, NULL, 1);
2785       tstack->object = object;
2786       tstack->n_toggle_refs = 1;
2787       i = 0;
2788     }
2789
2790   /* Set a flag for fast lookup after adding the first toggle reference */
2791   if (tstack->n_toggle_refs == 1)
2792     g_datalist_set_flags (&object->qdata, OBJECT_HAS_TOGGLE_REF_FLAG);
2793   
2794   tstack->toggle_refs[i].notify = notify;
2795   tstack->toggle_refs[i].data = data;
2796   g_datalist_id_set_data_full (&object->qdata, quark_toggle_refs, tstack,
2797                                (GDestroyNotify)g_free);
2798   G_UNLOCK (toggle_refs_mutex);
2799 }
2800
2801 /**
2802  * g_object_remove_toggle_ref: (skip)
2803  * @object: a #GObject
2804  * @notify: a function to call when this reference is the
2805  *  last reference to the object, or is no longer
2806  *  the last reference.
2807  * @data: data to pass to @notify
2808  *
2809  * Removes a reference added with g_object_add_toggle_ref(). The
2810  * reference count of the object is decreased by one.
2811  *
2812  * Since: 2.8
2813  */
2814 void
2815 g_object_remove_toggle_ref (GObject       *object,
2816                             GToggleNotify  notify,
2817                             gpointer       data)
2818 {
2819   ToggleRefStack *tstack;
2820   gboolean found_one = FALSE;
2821
2822   g_return_if_fail (G_IS_OBJECT (object));
2823   g_return_if_fail (notify != NULL);
2824
2825   G_LOCK (toggle_refs_mutex);
2826   tstack = g_datalist_id_get_data (&object->qdata, quark_toggle_refs);
2827   if (tstack)
2828     {
2829       guint i;
2830
2831       for (i = 0; i < tstack->n_toggle_refs; i++)
2832         if (tstack->toggle_refs[i].notify == notify &&
2833             tstack->toggle_refs[i].data == data)
2834           {
2835             found_one = TRUE;
2836             tstack->n_toggle_refs -= 1;
2837             if (i != tstack->n_toggle_refs)
2838               tstack->toggle_refs[i] = tstack->toggle_refs[tstack->n_toggle_refs];
2839
2840             if (tstack->n_toggle_refs == 0)
2841               g_datalist_unset_flags (&object->qdata, OBJECT_HAS_TOGGLE_REF_FLAG);
2842
2843             break;
2844           }
2845     }
2846   G_UNLOCK (toggle_refs_mutex);
2847
2848   if (found_one)
2849     g_object_unref (object);
2850   else
2851     g_warning ("%s: couldn't find toggle ref %p(%p)", G_STRFUNC, notify, data);
2852 }
2853
2854 /**
2855  * g_object_ref:
2856  * @object: (type GObject.Object): a #GObject
2857  *
2858  * Increases the reference count of @object.
2859  *
2860  * Returns: (type GObject.Object) (transfer none): the same @object
2861  */
2862 gpointer
2863 g_object_ref (gpointer _object)
2864 {
2865   GObject *object = _object;
2866   gint old_val;
2867
2868   g_return_val_if_fail (G_IS_OBJECT (object), NULL);
2869   g_return_val_if_fail (object->ref_count > 0, NULL);
2870   
2871 #ifdef  G_ENABLE_DEBUG
2872   if (g_trap_object_ref == object)
2873     G_BREAKPOINT ();
2874 #endif  /* G_ENABLE_DEBUG */
2875
2876
2877   old_val = g_atomic_int_add (&object->ref_count, 1);
2878
2879   if (old_val == 1 && OBJECT_HAS_TOGGLE_REF (object))
2880     toggle_refs_notify (object, FALSE);
2881
2882   TRACE (GOBJECT_OBJECT_REF(object,G_TYPE_FROM_INSTANCE(object),old_val));
2883
2884   return object;
2885 }
2886
2887 /**
2888  * g_object_unref:
2889  * @object: (type GObject.Object): a #GObject
2890  *
2891  * Decreases the reference count of @object. When its reference count
2892  * drops to 0, the object is finalized (i.e. its memory is freed).
2893  */
2894 void
2895 g_object_unref (gpointer _object)
2896 {
2897   GObject *object = _object;
2898   gint old_ref;
2899   
2900   g_return_if_fail (G_IS_OBJECT (object));
2901   g_return_if_fail (object->ref_count > 0);
2902   
2903 #ifdef  G_ENABLE_DEBUG
2904   if (g_trap_object_ref == object)
2905     G_BREAKPOINT ();
2906 #endif  /* G_ENABLE_DEBUG */
2907
2908   /* here we want to atomically do: if (ref_count>1) { ref_count--; return; } */
2909  retry_atomic_decrement1:
2910   old_ref = g_atomic_int_get (&object->ref_count);
2911   if (old_ref > 1)
2912     {
2913       /* valid if last 2 refs are owned by this call to unref and the toggle_ref */
2914       gboolean has_toggle_ref = OBJECT_HAS_TOGGLE_REF (object);
2915
2916       if (!g_atomic_int_compare_and_exchange ((int *)&object->ref_count, old_ref, old_ref - 1))
2917         goto retry_atomic_decrement1;
2918
2919       TRACE (GOBJECT_OBJECT_UNREF(object,G_TYPE_FROM_INSTANCE(object),old_ref));
2920
2921       /* if we went from 2->1 we need to notify toggle refs if any */
2922       if (old_ref == 2 && has_toggle_ref) /* The last ref being held in this case is owned by the toggle_ref */
2923         toggle_refs_notify (object, TRUE);
2924     }
2925   else
2926     {
2927       GSList **weak_locations;
2928
2929       /* The only way that this object can live at this point is if
2930        * there are outstanding weak references already established
2931        * before we got here.
2932        *
2933        * If there were not already weak references then no more can be
2934        * established at this time, because the other thread would have
2935        * to hold a strong ref in order to call
2936        * g_object_add_weak_pointer() and then we wouldn't be here.
2937        */
2938       weak_locations = g_datalist_id_get_data (&object->qdata, quark_weak_locations);
2939
2940       if (weak_locations != NULL)
2941         {
2942           g_rw_lock_writer_lock (&weak_locations_lock);
2943
2944           /* It is possible that one of the weak references beat us to
2945            * the lock. Make sure the refcount is still what we expected
2946            * it to be.
2947            */
2948           old_ref = g_atomic_int_get (&object->ref_count);
2949           if (old_ref != 1)
2950             {
2951               g_rw_lock_writer_unlock (&weak_locations_lock);
2952               goto retry_atomic_decrement1;
2953             }
2954
2955           /* We got the lock first, so the object will definitely die
2956            * now. Clear out all the weak references.
2957            */
2958           while (*weak_locations)
2959             {
2960               GWeakRef *weak_ref_location = (*weak_locations)->data;
2961
2962               weak_ref_location->priv.p = NULL;
2963               *weak_locations = g_slist_delete_link (*weak_locations, *weak_locations);
2964             }
2965
2966           g_rw_lock_writer_unlock (&weak_locations_lock);
2967         }
2968
2969       /* we are about to remove the last reference */
2970       TRACE (GOBJECT_OBJECT_DISPOSE(object,G_TYPE_FROM_INSTANCE(object), 1));
2971       G_OBJECT_GET_CLASS (object)->dispose (object);
2972       TRACE (GOBJECT_OBJECT_DISPOSE_END(object,G_TYPE_FROM_INSTANCE(object), 1));
2973
2974       /* may have been re-referenced meanwhile */
2975     retry_atomic_decrement2:
2976       old_ref = g_atomic_int_get ((int *)&object->ref_count);
2977       if (old_ref > 1)
2978         {
2979           /* valid if last 2 refs are owned by this call to unref and the toggle_ref */
2980           gboolean has_toggle_ref = OBJECT_HAS_TOGGLE_REF (object);
2981
2982           if (!g_atomic_int_compare_and_exchange ((int *)&object->ref_count, old_ref, old_ref - 1))
2983             goto retry_atomic_decrement2;
2984
2985           TRACE (GOBJECT_OBJECT_UNREF(object,G_TYPE_FROM_INSTANCE(object),old_ref));
2986
2987           /* if we went from 2->1 we need to notify toggle refs if any */
2988           if (old_ref == 2 && has_toggle_ref) /* The last ref being held in this case is owned by the toggle_ref */
2989             toggle_refs_notify (object, TRUE);
2990
2991           return;
2992         }
2993
2994       /* we are still in the process of taking away the last ref */
2995       g_datalist_id_set_data (&object->qdata, quark_closure_array, NULL);
2996       g_signal_handlers_destroy (object);
2997       g_datalist_id_set_data (&object->qdata, quark_weak_refs, NULL);
2998       
2999       /* decrement the last reference */
3000       old_ref = g_atomic_int_add (&object->ref_count, -1);
3001
3002       TRACE (GOBJECT_OBJECT_UNREF(object,G_TYPE_FROM_INSTANCE(object),old_ref));
3003
3004       /* may have been re-referenced meanwhile */
3005       if (G_LIKELY (old_ref == 1))
3006         {
3007           TRACE (GOBJECT_OBJECT_FINALIZE(object,G_TYPE_FROM_INSTANCE(object)));
3008           G_OBJECT_GET_CLASS (object)->finalize (object);
3009
3010           TRACE (GOBJECT_OBJECT_FINALIZE_END(object,G_TYPE_FROM_INSTANCE(object)));
3011
3012 #ifdef  G_ENABLE_DEBUG
3013           IF_DEBUG (OBJECTS)
3014             {
3015               /* catch objects not chaining finalize handlers */
3016               G_LOCK (debug_objects);
3017               g_assert (g_hash_table_lookup (debug_objects_ht, object) == NULL);
3018               G_UNLOCK (debug_objects);
3019             }
3020 #endif  /* G_ENABLE_DEBUG */
3021           g_type_free_instance ((GTypeInstance*) object);
3022         }
3023     }
3024 }
3025
3026 /**
3027  * g_clear_object: (skip)
3028  * @object_ptr: a pointer to a #GObject reference
3029  *
3030  * Clears a reference to a #GObject.
3031  *
3032  * @object_ptr must not be %NULL.
3033  *
3034  * If the reference is %NULL then this function does nothing.
3035  * Otherwise, the reference count of the object is decreased and the
3036  * pointer is set to %NULL.
3037  *
3038  * This function is threadsafe and modifies the pointer atomically,
3039  * using memory barriers where needed.
3040  *
3041  * A macro is also included that allows this function to be used without
3042  * pointer casts.
3043  *
3044  * Since: 2.28
3045  **/
3046 #undef g_clear_object
3047 void
3048 g_clear_object (volatile GObject **object_ptr)
3049 {
3050   gpointer *ptr = (gpointer) object_ptr;
3051   gpointer old;
3052
3053   /* This is a little frustrating.
3054    * Would be nice to have an atomic exchange (with no compare).
3055    */
3056   do
3057     old = g_atomic_pointer_get (ptr);
3058   while G_UNLIKELY (!g_atomic_pointer_compare_and_exchange (ptr, old, NULL));
3059
3060   if (old)
3061     g_object_unref (old);
3062 }
3063
3064 /**
3065  * g_object_get_qdata:
3066  * @object: The GObject to get a stored user data pointer from
3067  * @quark: A #GQuark, naming the user data pointer
3068  * 
3069  * This function gets back user data pointers stored via
3070  * g_object_set_qdata().
3071  * 
3072  * Returns: (transfer none): The user data pointer set, or %NULL
3073  */
3074 gpointer
3075 g_object_get_qdata (GObject *object,
3076                     GQuark   quark)
3077 {
3078   g_return_val_if_fail (G_IS_OBJECT (object), NULL);
3079   
3080   return quark ? g_datalist_id_get_data (&object->qdata, quark) : NULL;
3081 }
3082
3083 /**
3084  * g_object_set_qdata: (skip)
3085  * @object: The GObject to set store a user data pointer
3086  * @quark: A #GQuark, naming the user data pointer
3087  * @data: An opaque user data pointer
3088  *
3089  * This sets an opaque, named pointer on an object.
3090  * The name is specified through a #GQuark (retrived e.g. via
3091  * g_quark_from_static_string()), and the pointer
3092  * can be gotten back from the @object with g_object_get_qdata()
3093  * until the @object is finalized.
3094  * Setting a previously set user data pointer, overrides (frees)
3095  * the old pointer set, using #NULL as pointer essentially
3096  * removes the data stored.
3097  */
3098 void
3099 g_object_set_qdata (GObject *object,
3100                     GQuark   quark,
3101                     gpointer data)
3102 {
3103   g_return_if_fail (G_IS_OBJECT (object));
3104   g_return_if_fail (quark > 0);
3105   
3106   g_datalist_id_set_data (&object->qdata, quark, data);
3107 }
3108
3109 /**
3110  * g_object_set_qdata_full: (skip)
3111  * @object: The GObject to set store a user data pointer
3112  * @quark: A #GQuark, naming the user data pointer
3113  * @data: An opaque user data pointer
3114  * @destroy: Function to invoke with @data as argument, when @data
3115  *           needs to be freed
3116  *
3117  * This function works like g_object_set_qdata(), but in addition,
3118  * a void (*destroy) (gpointer) function may be specified which is
3119  * called with @data as argument when the @object is finalized, or
3120  * the data is being overwritten by a call to g_object_set_qdata()
3121  * with the same @quark.
3122  */
3123 void
3124 g_object_set_qdata_full (GObject       *object,
3125                          GQuark         quark,
3126                          gpointer       data,
3127                          GDestroyNotify destroy)
3128 {
3129   g_return_if_fail (G_IS_OBJECT (object));
3130   g_return_if_fail (quark > 0);
3131   
3132   g_datalist_id_set_data_full (&object->qdata, quark, data,
3133                                data ? destroy : (GDestroyNotify) NULL);
3134 }
3135
3136 /**
3137  * g_object_steal_qdata:
3138  * @object: The GObject to get a stored user data pointer from
3139  * @quark: A #GQuark, naming the user data pointer
3140  *
3141  * This function gets back user data pointers stored via
3142  * g_object_set_qdata() and removes the @data from object
3143  * without invoking its destroy() function (if any was
3144  * set).
3145  * Usually, calling this function is only required to update
3146  * user data pointers with a destroy notifier, for example:
3147  * |[
3148  * void
3149  * object_add_to_user_list (GObject     *object,
3150  *                          const gchar *new_string)
3151  * {
3152  *   // the quark, naming the object data
3153  *   GQuark quark_string_list = g_quark_from_static_string ("my-string-list");
3154  *   // retrive the old string list
3155  *   GList *list = g_object_steal_qdata (object, quark_string_list);
3156  *
3157  *   // prepend new string
3158  *   list = g_list_prepend (list, g_strdup (new_string));
3159  *   // this changed 'list', so we need to set it again
3160  *   g_object_set_qdata_full (object, quark_string_list, list, free_string_list);
3161  * }
3162  * static void
3163  * free_string_list (gpointer data)
3164  * {
3165  *   GList *node, *list = data;
3166  *
3167  *   for (node = list; node; node = node->next)
3168  *     g_free (node->data);
3169  *   g_list_free (list);
3170  * }
3171  * ]|
3172  * Using g_object_get_qdata() in the above example, instead of
3173  * g_object_steal_qdata() would have left the destroy function set,
3174  * and thus the partial string list would have been freed upon
3175  * g_object_set_qdata_full().
3176  *
3177  * Returns: (transfer full): The user data pointer set, or %NULL
3178  */
3179 gpointer
3180 g_object_steal_qdata (GObject *object,
3181                       GQuark   quark)
3182 {
3183   g_return_val_if_fail (G_IS_OBJECT (object), NULL);
3184   g_return_val_if_fail (quark > 0, NULL);
3185   
3186   return g_datalist_id_remove_no_notify (&object->qdata, quark);
3187 }
3188
3189 /**
3190  * g_object_get_data:
3191  * @object: #GObject containing the associations
3192  * @key: name of the key for that association
3193  * 
3194  * Gets a named field from the objects table of associations (see g_object_set_data()).
3195  * 
3196  * Returns: (transfer none): the data if found, or %NULL if no such data exists.
3197  */
3198 gpointer
3199 g_object_get_data (GObject     *object,
3200                    const gchar *key)
3201 {
3202   g_return_val_if_fail (G_IS_OBJECT (object), NULL);
3203   g_return_val_if_fail (key != NULL, NULL);
3204
3205   return g_datalist_get_data (&object->qdata, key);
3206 }
3207
3208 /**
3209  * g_object_set_data:
3210  * @object: #GObject containing the associations.
3211  * @key: name of the key
3212  * @data: data to associate with that key
3213  *
3214  * Each object carries around a table of associations from
3215  * strings to pointers.  This function lets you set an association.
3216  *
3217  * If the object already had an association with that name,
3218  * the old association will be destroyed.
3219  */
3220 void
3221 g_object_set_data (GObject     *object,
3222                    const gchar *key,
3223                    gpointer     data)
3224 {
3225   g_return_if_fail (G_IS_OBJECT (object));
3226   g_return_if_fail (key != NULL);
3227
3228   g_datalist_id_set_data (&object->qdata, g_quark_from_string (key), data);
3229 }
3230
3231 /**
3232  * g_object_set_data_full: (skip)
3233  * @object: #GObject containing the associations
3234  * @key: name of the key
3235  * @data: data to associate with that key
3236  * @destroy: function to call when the association is destroyed
3237  *
3238  * Like g_object_set_data() except it adds notification
3239  * for when the association is destroyed, either by setting it
3240  * to a different value or when the object is destroyed.
3241  *
3242  * Note that the @destroy callback is not called if @data is %NULL.
3243  */
3244 void
3245 g_object_set_data_full (GObject       *object,
3246                         const gchar   *key,
3247                         gpointer       data,
3248                         GDestroyNotify destroy)
3249 {
3250   g_return_if_fail (G_IS_OBJECT (object));
3251   g_return_if_fail (key != NULL);
3252
3253   g_datalist_id_set_data_full (&object->qdata, g_quark_from_string (key), data,
3254                                data ? destroy : (GDestroyNotify) NULL);
3255 }
3256
3257 /**
3258  * g_object_steal_data:
3259  * @object: #GObject containing the associations
3260  * @key: name of the key
3261  *
3262  * Remove a specified datum from the object's data associations,
3263  * without invoking the association's destroy handler.
3264  *
3265  * Returns: (transfer full): the data if found, or %NULL if no such data exists.
3266  */
3267 gpointer
3268 g_object_steal_data (GObject     *object,
3269                      const gchar *key)
3270 {
3271   GQuark quark;
3272
3273   g_return_val_if_fail (G_IS_OBJECT (object), NULL);
3274   g_return_val_if_fail (key != NULL, NULL);
3275
3276   quark = g_quark_try_string (key);
3277
3278   return quark ? g_datalist_id_remove_no_notify (&object->qdata, quark) : NULL;
3279 }
3280
3281 static void
3282 g_value_object_init (GValue *value)
3283 {
3284   value->data[0].v_pointer = NULL;
3285 }
3286
3287 static void
3288 g_value_object_free_value (GValue *value)
3289 {
3290   if (value->data[0].v_pointer)
3291     g_object_unref (value->data[0].v_pointer);
3292 }
3293
3294 static void
3295 g_value_object_copy_value (const GValue *src_value,
3296                            GValue       *dest_value)
3297 {
3298   if (src_value->data[0].v_pointer)
3299     dest_value->data[0].v_pointer = g_object_ref (src_value->data[0].v_pointer);
3300   else
3301     dest_value->data[0].v_pointer = NULL;
3302 }
3303
3304 static void
3305 g_value_object_transform_value (const GValue *src_value,
3306                                 GValue       *dest_value)
3307 {
3308   if (src_value->data[0].v_pointer && g_type_is_a (G_OBJECT_TYPE (src_value->data[0].v_pointer), G_VALUE_TYPE (dest_value)))
3309     dest_value->data[0].v_pointer = g_object_ref (src_value->data[0].v_pointer);
3310   else
3311     dest_value->data[0].v_pointer = NULL;
3312 }
3313
3314 static gpointer
3315 g_value_object_peek_pointer (const GValue *value)
3316 {
3317   return value->data[0].v_pointer;
3318 }
3319
3320 static gchar*
3321 g_value_object_collect_value (GValue      *value,
3322                               guint        n_collect_values,
3323                               GTypeCValue *collect_values,
3324                               guint        collect_flags)
3325 {
3326   if (collect_values[0].v_pointer)
3327     {
3328       GObject *object = collect_values[0].v_pointer;
3329       
3330       if (object->g_type_instance.g_class == NULL)
3331         return g_strconcat ("invalid unclassed object pointer for value type `",
3332                             G_VALUE_TYPE_NAME (value),
3333                             "'",
3334                             NULL);
3335       else if (!g_value_type_compatible (G_OBJECT_TYPE (object), G_VALUE_TYPE (value)))
3336         return g_strconcat ("invalid object type `",
3337                             G_OBJECT_TYPE_NAME (object),
3338                             "' for value type `",
3339                             G_VALUE_TYPE_NAME (value),
3340                             "'",
3341                             NULL);
3342       /* never honour G_VALUE_NOCOPY_CONTENTS for ref-counted types */
3343       value->data[0].v_pointer = g_object_ref (object);
3344     }
3345   else
3346     value->data[0].v_pointer = NULL;
3347   
3348   return NULL;
3349 }
3350
3351 static gchar*
3352 g_value_object_lcopy_value (const GValue *value,
3353                             guint        n_collect_values,
3354                             GTypeCValue *collect_values,
3355                             guint        collect_flags)
3356 {
3357   GObject **object_p = collect_values[0].v_pointer;
3358   
3359   if (!object_p)
3360     return g_strdup_printf ("value location for `%s' passed as NULL", G_VALUE_TYPE_NAME (value));
3361
3362   if (!value->data[0].v_pointer)
3363     *object_p = NULL;
3364   else if (collect_flags & G_VALUE_NOCOPY_CONTENTS)
3365     *object_p = value->data[0].v_pointer;
3366   else
3367     *object_p = g_object_ref (value->data[0].v_pointer);
3368   
3369   return NULL;
3370 }
3371
3372 /**
3373  * g_value_set_object:
3374  * @value: a valid #GValue of %G_TYPE_OBJECT derived type
3375  * @v_object: (type GObject.Object) (allow-none): object value to be set
3376  *
3377  * Set the contents of a %G_TYPE_OBJECT derived #GValue to @v_object.
3378  *
3379  * g_value_set_object() increases the reference count of @v_object
3380  * (the #GValue holds a reference to @v_object).  If you do not wish
3381  * to increase the reference count of the object (i.e. you wish to
3382  * pass your current reference to the #GValue because you no longer
3383  * need it), use g_value_take_object() instead.
3384  *
3385  * It is important that your #GValue holds a reference to @v_object (either its
3386  * own, or one it has taken) to ensure that the object won't be destroyed while
3387  * the #GValue still exists).
3388  */
3389 void
3390 g_value_set_object (GValue   *value,
3391                     gpointer  v_object)
3392 {
3393   GObject *old;
3394         
3395   g_return_if_fail (G_VALUE_HOLDS_OBJECT (value));
3396
3397   old = value->data[0].v_pointer;
3398   
3399   if (v_object)
3400     {
3401       g_return_if_fail (G_IS_OBJECT (v_object));
3402       g_return_if_fail (g_value_type_compatible (G_OBJECT_TYPE (v_object), G_VALUE_TYPE (value)));
3403
3404       value->data[0].v_pointer = v_object;
3405       g_object_ref (value->data[0].v_pointer);
3406     }
3407   else
3408     value->data[0].v_pointer = NULL;
3409   
3410   if (old)
3411     g_object_unref (old);
3412 }
3413
3414 /**
3415  * g_value_set_object_take_ownership: (skip)
3416  * @value: a valid #GValue of %G_TYPE_OBJECT derived type
3417  * @v_object: (allow-none): object value to be set
3418  *
3419  * This is an internal function introduced mainly for C marshallers.
3420  *
3421  * Deprecated: 2.4: Use g_value_take_object() instead.
3422  */
3423 void
3424 g_value_set_object_take_ownership (GValue  *value,
3425                                    gpointer v_object)
3426 {
3427   g_value_take_object (value, v_object);
3428 }
3429
3430 /**
3431  * g_value_take_object: (skip)
3432  * @value: a valid #GValue of %G_TYPE_OBJECT derived type
3433  * @v_object: (allow-none): object value to be set
3434  *
3435  * Sets the contents of a %G_TYPE_OBJECT derived #GValue to @v_object
3436  * and takes over the ownership of the callers reference to @v_object;
3437  * the caller doesn't have to unref it any more (i.e. the reference
3438  * count of the object is not increased).
3439  *
3440  * If you want the #GValue to hold its own reference to @v_object, use
3441  * g_value_set_object() instead.
3442  *
3443  * Since: 2.4
3444  */
3445 void
3446 g_value_take_object (GValue  *value,
3447                      gpointer v_object)
3448 {
3449   g_return_if_fail (G_VALUE_HOLDS_OBJECT (value));
3450
3451   if (value->data[0].v_pointer)
3452     {
3453       g_object_unref (value->data[0].v_pointer);
3454       value->data[0].v_pointer = NULL;
3455     }
3456
3457   if (v_object)
3458     {
3459       g_return_if_fail (G_IS_OBJECT (v_object));
3460       g_return_if_fail (g_value_type_compatible (G_OBJECT_TYPE (v_object), G_VALUE_TYPE (value)));
3461
3462       value->data[0].v_pointer = v_object; /* we take over the reference count */
3463     }
3464 }
3465
3466 /**
3467  * g_value_get_object:
3468  * @value: a valid #GValue of %G_TYPE_OBJECT derived type
3469  * 
3470  * Get the contents of a %G_TYPE_OBJECT derived #GValue.
3471  * 
3472  * Returns: (type GObject.Object) (transfer none): object contents of @value
3473  */
3474 gpointer
3475 g_value_get_object (const GValue *value)
3476 {
3477   g_return_val_if_fail (G_VALUE_HOLDS_OBJECT (value), NULL);
3478   
3479   return value->data[0].v_pointer;
3480 }
3481
3482 /**
3483  * g_value_dup_object:
3484  * @value: a valid #GValue whose type is derived from %G_TYPE_OBJECT
3485  *
3486  * Get the contents of a %G_TYPE_OBJECT derived #GValue, increasing
3487  * its reference count. If the contents of the #GValue are %NULL, then
3488  * %NULL will be returned.
3489  *
3490  * Returns: (type GObject.Object) (transfer full): object content of @value,
3491  *          should be unreferenced when no longer needed.
3492  */
3493 gpointer
3494 g_value_dup_object (const GValue *value)
3495 {
3496   g_return_val_if_fail (G_VALUE_HOLDS_OBJECT (value), NULL);
3497   
3498   return value->data[0].v_pointer ? g_object_ref (value->data[0].v_pointer) : NULL;
3499 }
3500
3501 /**
3502  * g_signal_connect_object: (skip)
3503  * @instance: the instance to connect to.
3504  * @detailed_signal: a string of the form "signal-name::detail".
3505  * @c_handler: the #GCallback to connect.
3506  * @gobject: the object to pass as data to @c_handler.
3507  * @connect_flags: a combination of #GConnectFlags.
3508  *
3509  * This is similar to g_signal_connect_data(), but uses a closure which
3510  * ensures that the @gobject stays alive during the call to @c_handler
3511  * by temporarily adding a reference count to @gobject.
3512  *
3513  * Note that there is a bug in GObject that makes this function
3514  * much less useful than it might seem otherwise. Once @gobject is
3515  * disposed, the callback will no longer be called, but, the signal
3516  * handler is <emphasis>not</emphasis> currently disconnected. If the
3517  * @instance is itself being freed at the same time than this doesn't
3518  * matter, since the signal will automatically be removed, but
3519  * if @instance persists, then the signal handler will leak. You
3520  * should not remove the signal yourself because in a future versions of
3521  * GObject, the handler <emphasis>will</emphasis> automatically
3522  * be disconnected.
3523  *
3524  * It's possible to work around this problem in a way that will
3525  * continue to work with future versions of GObject by checking
3526  * that the signal handler is still connected before disconnected it:
3527  * <informalexample><programlisting>
3528  *  if (g_signal_handler_is_connected (instance, id))
3529  *    g_signal_handler_disconnect (instance, id);
3530  * </programlisting></informalexample>
3531  *
3532  * Returns: the handler id.
3533  */
3534 gulong
3535 g_signal_connect_object (gpointer      instance,
3536                          const gchar  *detailed_signal,
3537                          GCallback     c_handler,
3538                          gpointer      gobject,
3539                          GConnectFlags connect_flags)
3540 {
3541   g_return_val_if_fail (G_TYPE_CHECK_INSTANCE (instance), 0);
3542   g_return_val_if_fail (detailed_signal != NULL, 0);
3543   g_return_val_if_fail (c_handler != NULL, 0);
3544
3545   if (gobject)
3546     {
3547       GClosure *closure;
3548
3549       g_return_val_if_fail (G_IS_OBJECT (gobject), 0);
3550
3551       closure = ((connect_flags & G_CONNECT_SWAPPED) ? g_cclosure_new_object_swap : g_cclosure_new_object) (c_handler, gobject);
3552
3553       return g_signal_connect_closure (instance, detailed_signal, closure, connect_flags & G_CONNECT_AFTER);
3554     }
3555   else
3556     return g_signal_connect_data (instance, detailed_signal, c_handler, NULL, NULL, connect_flags);
3557 }
3558
3559 typedef struct {
3560   GObject  *object;
3561   guint     n_closures;
3562   GClosure *closures[1]; /* flexible array */
3563 } CArray;
3564 /* don't change this structure without supplying an accessor for
3565  * watched closures, e.g.:
3566  * GSList* g_object_list_watched_closures (GObject *object)
3567  * {
3568  *   CArray *carray;
3569  *   g_return_val_if_fail (G_IS_OBJECT (object), NULL);
3570  *   carray = g_object_get_data (object, "GObject-closure-array");
3571  *   if (carray)
3572  *     {
3573  *       GSList *slist = NULL;
3574  *       guint i;
3575  *       for (i = 0; i < carray->n_closures; i++)
3576  *         slist = g_slist_prepend (slist, carray->closures[i]);
3577  *       return slist;
3578  *     }
3579  *   return NULL;
3580  * }
3581  */
3582
3583 static void
3584 object_remove_closure (gpointer  data,
3585                        GClosure *closure)
3586 {
3587   GObject *object = data;
3588   CArray *carray;
3589   guint i;
3590   
3591   G_LOCK (closure_array_mutex);
3592   carray = g_object_get_qdata (object, quark_closure_array);
3593   for (i = 0; i < carray->n_closures; i++)
3594     if (carray->closures[i] == closure)
3595       {
3596         carray->n_closures--;
3597         if (i < carray->n_closures)
3598           carray->closures[i] = carray->closures[carray->n_closures];
3599         G_UNLOCK (closure_array_mutex);
3600         return;
3601       }
3602   G_UNLOCK (closure_array_mutex);
3603   g_assert_not_reached ();
3604 }
3605
3606 static void
3607 destroy_closure_array (gpointer data)
3608 {
3609   CArray *carray = data;
3610   GObject *object = carray->object;
3611   guint i, n = carray->n_closures;
3612   
3613   for (i = 0; i < n; i++)
3614     {
3615       GClosure *closure = carray->closures[i];
3616       
3617       /* removing object_remove_closure() upfront is probably faster than
3618        * letting it fiddle with quark_closure_array which is empty anyways
3619        */
3620       g_closure_remove_invalidate_notifier (closure, object, object_remove_closure);
3621       g_closure_invalidate (closure);
3622     }
3623   g_free (carray);
3624 }
3625
3626 /**
3627  * g_object_watch_closure:
3628  * @object: GObject restricting lifetime of @closure
3629  * @closure: GClosure to watch
3630  *
3631  * This function essentially limits the life time of the @closure to
3632  * the life time of the object. That is, when the object is finalized,
3633  * the @closure is invalidated by calling g_closure_invalidate() on
3634  * it, in order to prevent invocations of the closure with a finalized
3635  * (nonexisting) object. Also, g_object_ref() and g_object_unref() are
3636  * added as marshal guards to the @closure, to ensure that an extra
3637  * reference count is held on @object during invocation of the
3638  * @closure.  Usually, this function will be called on closures that
3639  * use this @object as closure data.
3640  */
3641 void
3642 g_object_watch_closure (GObject  *object,
3643                         GClosure *closure)
3644 {
3645   CArray *carray;
3646   guint i;
3647   
3648   g_return_if_fail (G_IS_OBJECT (object));
3649   g_return_if_fail (closure != NULL);
3650   g_return_if_fail (closure->is_invalid == FALSE);
3651   g_return_if_fail (closure->in_marshal == FALSE);
3652   g_return_if_fail (object->ref_count > 0);     /* this doesn't work on finalizing objects */
3653   
3654   g_closure_add_invalidate_notifier (closure, object, object_remove_closure);
3655   g_closure_add_marshal_guards (closure,
3656                                 object, (GClosureNotify) g_object_ref,
3657                                 object, (GClosureNotify) g_object_unref);
3658   G_LOCK (closure_array_mutex);
3659   carray = g_datalist_id_remove_no_notify (&object->qdata, quark_closure_array);
3660   if (!carray)
3661     {
3662       carray = g_renew (CArray, NULL, 1);
3663       carray->object = object;
3664       carray->n_closures = 1;
3665       i = 0;
3666     }
3667   else
3668     {
3669       i = carray->n_closures++;
3670       carray = g_realloc (carray, sizeof (*carray) + sizeof (carray->closures[0]) * i);
3671     }
3672   carray->closures[i] = closure;
3673   g_datalist_id_set_data_full (&object->qdata, quark_closure_array, carray, destroy_closure_array);
3674   G_UNLOCK (closure_array_mutex);
3675 }
3676
3677 /**
3678  * g_closure_new_object:
3679  * @sizeof_closure: the size of the structure to allocate, must be at least
3680  *  <literal>sizeof (GClosure)</literal>
3681  * @object: a #GObject pointer to store in the @data field of the newly
3682  *  allocated #GClosure
3683  *
3684  * A variant of g_closure_new_simple() which stores @object in the
3685  * @data field of the closure and calls g_object_watch_closure() on
3686  * @object and the created closure. This function is mainly useful
3687  * when implementing new types of closures.
3688  *
3689  * Returns: (transfer full): a newly allocated #GClosure
3690  */
3691 GClosure*
3692 g_closure_new_object (guint    sizeof_closure,
3693                       GObject *object)
3694 {
3695   GClosure *closure;
3696
3697   g_return_val_if_fail (G_IS_OBJECT (object), NULL);
3698   g_return_val_if_fail (object->ref_count > 0, NULL);     /* this doesn't work on finalizing objects */
3699
3700   closure = g_closure_new_simple (sizeof_closure, object);
3701   g_object_watch_closure (object, closure);
3702
3703   return closure;
3704 }
3705
3706 /**
3707  * g_cclosure_new_object: (skip)
3708  * @callback_func: the function to invoke
3709  * @object: a #GObject pointer to pass to @callback_func
3710  *
3711  * A variant of g_cclosure_new() which uses @object as @user_data and
3712  * calls g_object_watch_closure() on @object and the created
3713  * closure. This function is useful when you have a callback closely
3714  * associated with a #GObject, and want the callback to no longer run
3715  * after the object is is freed.
3716  *
3717  * Returns: a new #GCClosure
3718  */
3719 GClosure*
3720 g_cclosure_new_object (GCallback callback_func,
3721                        GObject  *object)
3722 {
3723   GClosure *closure;
3724
3725   g_return_val_if_fail (G_IS_OBJECT (object), NULL);
3726   g_return_val_if_fail (object->ref_count > 0, NULL);     /* this doesn't work on finalizing objects */
3727   g_return_val_if_fail (callback_func != NULL, NULL);
3728
3729   closure = g_cclosure_new (callback_func, object, NULL);
3730   g_object_watch_closure (object, closure);
3731
3732   return closure;
3733 }
3734
3735 /**
3736  * g_cclosure_new_object_swap: (skip)
3737  * @callback_func: the function to invoke
3738  * @object: a #GObject pointer to pass to @callback_func
3739  *
3740  * A variant of g_cclosure_new_swap() which uses @object as @user_data
3741  * and calls g_object_watch_closure() on @object and the created
3742  * closure. This function is useful when you have a callback closely
3743  * associated with a #GObject, and want the callback to no longer run
3744  * after the object is is freed.
3745  *
3746  * Returns: a new #GCClosure
3747  */
3748 GClosure*
3749 g_cclosure_new_object_swap (GCallback callback_func,
3750                             GObject  *object)
3751 {
3752   GClosure *closure;
3753
3754   g_return_val_if_fail (G_IS_OBJECT (object), NULL);
3755   g_return_val_if_fail (object->ref_count > 0, NULL);     /* this doesn't work on finalizing objects */
3756   g_return_val_if_fail (callback_func != NULL, NULL);
3757
3758   closure = g_cclosure_new_swap (callback_func, object, NULL);
3759   g_object_watch_closure (object, closure);
3760
3761   return closure;
3762 }
3763
3764 gsize
3765 g_object_compat_control (gsize           what,
3766                          gpointer        data)
3767 {
3768   switch (what)
3769     {
3770       gpointer *pp;
3771     case 1:     /* floating base type */
3772       return G_TYPE_INITIALLY_UNOWNED;
3773     case 2:     /* FIXME: remove this once GLib/Gtk+ break ABI again */
3774       floating_flag_handler = (guint(*)(GObject*,gint)) data;
3775       return 1;
3776     case 3:     /* FIXME: remove this once GLib/Gtk+ break ABI again */
3777       pp = data;
3778       *pp = floating_flag_handler;
3779       return 1;
3780     default:
3781       return 0;
3782     }
3783 }
3784
3785 G_DEFINE_TYPE (GInitiallyUnowned, g_initially_unowned, G_TYPE_OBJECT);
3786
3787 static void
3788 g_initially_unowned_init (GInitiallyUnowned *object)
3789 {
3790   g_object_force_floating (object);
3791 }
3792
3793 static void
3794 g_initially_unowned_class_init (GInitiallyUnownedClass *klass)
3795 {
3796 }
3797
3798 /**
3799  * GWeakRef:
3800  *
3801  * A structure containing a weak reference to a #GObject.  It can either
3802  * be empty (i.e. point to %NULL), or point to an object for as long as
3803  * at least one "strong" reference to that object exists. Before the
3804  * object's #GObjectClass.dispose method is called, every #GWeakRef
3805  * associated with becomes empty (i.e. points to %NULL).
3806  *
3807  * Like #GValue, #GWeakRef can be statically allocated, stack- or
3808  * heap-allocated, or embedded in larger structures.
3809  *
3810  * Unlike g_object_weak_ref() and g_object_add_weak_pointer(), this weak
3811  * reference is thread-safe: converting a weak pointer to a reference is
3812  * atomic with respect to invalidation of weak pointers to destroyed
3813  * objects.
3814  *
3815  * If the object's #GObjectClass.dispose method results in additional
3816  * references to the object being held, any #GWeakRef<!-- -->s taken
3817  * before it was disposed will continue to point to %NULL.  If
3818  * #GWeakRef<!-- -->s are taken after the object is disposed and
3819  * re-referenced, they will continue to point to it until its refcount
3820  * goes back to zero, at which point they too will be invalidated.
3821  */
3822
3823 /**
3824  * g_weak_ref_init: (skip)
3825  * @weak_ref_location: (inout): uninitialized or empty location for a weak
3826  *  reference
3827  * @object: (allow-none): a #GObject or %NULL
3828  *
3829  * Initialise a non-statically-allocated #GWeakRef.
3830  *
3831  * This function also calls g_weak_ref_set() with @object on the
3832  * freshly-initialised weak reference.
3833  *
3834  * This function should always be matched with a call to
3835  * g_weak_ref_clear().  It is not necessary to use this function for a
3836  * #GWeakRef in static storage because it will already be
3837  * properly initialised.  Just use g_weak_ref_set() directly.
3838  *
3839  * Since: 2.32
3840  */
3841 void
3842 g_weak_ref_init (GWeakRef *weak_ref_location,
3843                  gpointer  object)
3844 {
3845   weak_ref_location->priv.p = NULL;
3846
3847   g_weak_ref_set (weak_ref_location, object);
3848 }
3849
3850 /**
3851  * g_weak_ref_clear: (skip)
3852  * @weak_ref_location: (inout): location of a weak reference, which
3853  *  may be empty
3854  *
3855  * Frees resources associated with a non-statically-allocated #GWeakRef.
3856  * After this call, the #GWeakRef is left in an undefined state.
3857  *
3858  * You should only call this on a #GWeakRef that previously had
3859  * g_weak_ref_init() called on it.
3860  *
3861  * Since: 2.32
3862  */
3863 void
3864 g_weak_ref_clear (GWeakRef *weak_ref_location)
3865 {
3866   g_weak_ref_set (weak_ref_location, NULL);
3867
3868   /* be unkind */
3869   weak_ref_location->priv.p = (void *) 0xccccccccu;
3870 }
3871
3872 /**
3873  * g_weak_ref_get: (skip)
3874  * @weak_ref_location: (inout): location of a weak reference to a #GObject
3875  *
3876  * If @weak_ref_location is not empty, atomically acquire a strong
3877  * reference to the object it points to, and return that reference.
3878  *
3879  * This function is needed because of the potential race between taking
3880  * the pointer value and g_object_ref() on it, if the object was losing
3881  * its last reference at the same time in a different thread.
3882  *
3883  * The caller should release the resulting reference in the usual way,
3884  * by using g_object_unref().
3885  *
3886  * Returns: (transfer full) (type GObject.Object): the object pointed to
3887  *  by @weak_ref_location, or %NULL if it was empty
3888  *
3889  * Since: 2.32
3890  */
3891 gpointer
3892 g_weak_ref_get (GWeakRef *weak_ref_location)
3893 {
3894   gpointer object_or_null;
3895
3896   g_return_val_if_fail (weak_ref_location != NULL, NULL);
3897
3898   g_rw_lock_reader_lock (&weak_locations_lock);
3899
3900   object_or_null = weak_ref_location->priv.p;
3901
3902   if (object_or_null != NULL)
3903     g_object_ref (object_or_null);
3904
3905   g_rw_lock_reader_unlock (&weak_locations_lock);
3906
3907   return object_or_null;
3908 }
3909
3910 /**
3911  * g_weak_ref_set: (skip)
3912  * @weak_ref_location: location for a weak reference
3913  * @object: (allow-none): a #GObject or %NULL
3914  *
3915  * Change the object to which @weak_ref_location points, or set it to
3916  * %NULL.
3917  *
3918  * You must own a strong reference on @object while calling this
3919  * function.
3920  *
3921  * Since: 2.32
3922  */
3923 void
3924 g_weak_ref_set (GWeakRef *weak_ref_location,
3925                 gpointer  object)
3926 {
3927   GSList **weak_locations;
3928   GObject *new_object;
3929   GObject *old_object;
3930
3931   g_return_if_fail (weak_ref_location != NULL);
3932   g_return_if_fail (object == NULL || G_IS_OBJECT (object));
3933
3934   new_object = object;
3935
3936   g_rw_lock_writer_lock (&weak_locations_lock);
3937
3938   /* We use the extra level of indirection here so that if we have ever
3939    * had a weak pointer installed at any point in time on this object,
3940    * we can see that there is a non-NULL value associated with the
3941    * weak-pointer quark and know that this value will not change at any
3942    * point in the object's lifetime.
3943    *
3944    * Both properties are important for reducing the amount of times we
3945    * need to acquire locks and for decreasing the duration of time the
3946    * lock is held while avoiding some rather tricky races.
3947    *
3948    * Specifically: we can avoid having to do an extra unconditional lock
3949    * in g_object_unref() without worrying about some extremely tricky
3950    * races.
3951    */
3952
3953   old_object = weak_ref_location->priv.p;
3954   if (new_object != old_object)
3955     {
3956       weak_ref_location->priv.p = new_object;
3957
3958       /* Remove the weak ref from the old object */
3959       if (old_object != NULL)
3960         {
3961           weak_locations = g_datalist_id_get_data (&old_object->qdata, quark_weak_locations);
3962           /* for it to point to an object, the object must have had it added once */
3963           g_assert (weak_locations != NULL);
3964
3965           *weak_locations = g_slist_remove (*weak_locations, weak_ref_location);
3966         }
3967
3968       /* Add the weak ref to the new object */
3969       if (new_object != NULL)
3970         {
3971           weak_locations = g_datalist_id_get_data (&new_object->qdata, quark_weak_locations);
3972
3973           if (weak_locations == NULL)
3974             {
3975               weak_locations = g_new0 (GSList *, 1);
3976               g_datalist_id_set_data_full (&new_object->qdata, quark_weak_locations, weak_locations, g_free);
3977             }
3978
3979           *weak_locations = g_slist_prepend (*weak_locations, weak_ref_location);
3980         }
3981     }
3982
3983   g_rw_lock_writer_unlock (&weak_locations_lock);
3984 }