Merge branch 'master' into 0.11
[platform/upstream/gstreamer.git] / gst / gstminiobject.c
1 /* GStreamer
2  * Copyright (C) 2005 David Schleef <ds@schleef.org>
3  *
4  * gstminiobject.h: Header for GstMiniObject
5  *
6  * This library is free software; you can redistribute it and/or
7  * modify it under the terms of the GNU Library General Public
8  * License as published by the Free Software Foundation; either
9  * version 2 of the License, or (at your option) any later version.
10  *
11  * This library is distributed in the hope that it will be useful,
12  * but WITHOUT ANY WARRANTY; without even the implied warranty of
13  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
14  * Library General Public License for more details.
15  *
16  * You should have received a copy of the GNU Library General Public
17  * License along with this library; if not, write to the
18  * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
19  * Boston, MA 02111-1307, USA.
20  */
21 /**
22  * SECTION:gstminiobject
23  * @short_description: Lightweight base class for the GStreamer object hierarchy
24  *
25  * #GstMiniObject is a baseclass like #GObject, but has been stripped down of
26  * features to be fast and small.
27  * It offers sub-classing and ref-counting in the same way as #GObject does.
28  * It has no properties and no signal-support though.
29  *
30  * Last reviewed on 2005-11-23 (0.9.5)
31  */
32 #ifdef HAVE_CONFIG_H
33 #include "config.h"
34 #endif
35
36 #include "gst/gst_private.h"
37 #include "gst/gstminiobject.h"
38 #include "gst/gstinfo.h"
39 #include <gobject/gvaluecollector.h>
40
41 #define GST_DISABLE_TRACE
42
43 #ifndef GST_DISABLE_TRACE
44 #include "gsttrace.h"
45 static GstAllocTrace *_gst_mini_object_trace;
46 #endif
47
48 /* Mutex used for weak referencing */
49 G_LOCK_DEFINE_STATIC (weak_refs_mutex);
50
51 /**
52  * gst_mini_object_init:
53  * @mini_object: a #GstMiniObject 
54  * @type: the #GType of the mini-object to create
55  * @size: the size of the data
56  *
57  * Initializes a mini-object with the desired type and size.
58  *
59  * MT safe
60  *
61  * Returns: (transfer full): the new mini-object.
62  */
63 void
64 gst_mini_object_init (GstMiniObject * mini_object, GType type, gsize size)
65 {
66   mini_object->type = type;
67   mini_object->refcount = 1;
68   mini_object->flags = 0;
69   mini_object->size = size;
70   mini_object->n_weak_refs = 0;
71   mini_object->weak_refs = NULL;
72 }
73
74 /**
75  * gst_mini_object_copy:
76  * @mini_object: the mini-object to copy
77  *
78  * Creates a copy of the mini-object.
79  *
80  * MT safe
81  *
82  * Returns: (transfer full): the new mini-object.
83  */
84 GstMiniObject *
85 gst_mini_object_copy (const GstMiniObject * mini_object)
86 {
87   GstMiniObject *copy;
88
89   g_return_val_if_fail (mini_object != NULL, NULL);
90
91   if (mini_object->copy)
92     copy = mini_object->copy (mini_object);
93   else
94     copy = NULL;
95
96   return copy;
97 }
98
99 /**
100  * gst_mini_object_is_writable:
101  * @mini_object: the mini-object to check
102  *
103  * Checks if a mini-object is writable.  A mini-object is writable
104  * if the reference count is one and the #GST_MINI_OBJECT_FLAG_READONLY
105  * flag is not set.  Modification of a mini-object should only be
106  * done after verifying that it is writable.
107  *
108  * MT safe
109  *
110  * Returns: TRUE if the object is writable.
111  */
112 gboolean
113 gst_mini_object_is_writable (const GstMiniObject * mini_object)
114 {
115   g_return_val_if_fail (mini_object != NULL, FALSE);
116
117   return (GST_MINI_OBJECT_REFCOUNT_VALUE (mini_object) == 1);
118 }
119
120 /**
121  * gst_mini_object_make_writable:
122  * @mini_object: (transfer full): the mini-object to make writable
123  *
124  * Checks if a mini-object is writable.  If not, a writable copy is made and
125  * returned.  This gives away the reference to the original mini object,
126  * and returns a reference to the new object.
127  *
128  * MT safe
129  *
130  * Returns: (transfer full): a mini-object (possibly the same pointer) that
131  *     is writable.
132  */
133 GstMiniObject *
134 gst_mini_object_make_writable (GstMiniObject * mini_object)
135 {
136   GstMiniObject *ret;
137
138   g_return_val_if_fail (mini_object != NULL, NULL);
139
140   if (gst_mini_object_is_writable (mini_object)) {
141     ret = mini_object;
142   } else {
143     ret = gst_mini_object_copy (mini_object);
144     GST_CAT_DEBUG (GST_CAT_PERFORMANCE, "copy %s miniobject %p -> %p",
145         g_type_name (GST_MINI_OBJECT_TYPE (mini_object)), mini_object, ret);
146     gst_mini_object_unref (mini_object);
147   }
148
149   return ret;
150 }
151
152 /**
153  * gst_mini_object_ref:
154  * @mini_object: the mini-object
155  *
156  * Increase the reference count of the mini-object.
157  *
158  * Note that the refcount affects the writeability
159  * of @mini-object, see gst_mini_object_is_writable(). It is
160  * important to note that keeping additional references to
161  * GstMiniObject instances can potentially increase the number
162  * of memcpy operations in a pipeline, especially if the miniobject
163  * is a #GstBuffer.
164  *
165  * Returns: (transfer full): the mini-object.
166  */
167 GstMiniObject *
168 gst_mini_object_ref (GstMiniObject * mini_object)
169 {
170   g_return_val_if_fail (mini_object != NULL, NULL);
171   /* we can't assert that the refcount > 0 since the _free functions
172    * increments the refcount from 0 to 1 again to allow resurecting
173    * the object
174    g_return_val_if_fail (mini_object->refcount > 0, NULL);
175    */
176
177   GST_CAT_TRACE (GST_CAT_REFCOUNTING, "%p ref %d->%d", mini_object,
178       GST_MINI_OBJECT_REFCOUNT_VALUE (mini_object),
179       GST_MINI_OBJECT_REFCOUNT_VALUE (mini_object) + 1);
180
181   g_atomic_int_inc (&mini_object->refcount);
182
183   return mini_object;
184 }
185
186 static void
187 weak_refs_notify (GstMiniObject * obj)
188 {
189   guint i;
190
191   for (i = 0; i < obj->n_weak_refs; i++)
192     obj->weak_refs[i].notify (obj->weak_refs[i].data, obj);
193   g_free (obj->weak_refs);
194 }
195
196 /**
197  * gst_mini_object_unref:
198  * @mini_object: the mini-object
199  *
200  * Decreases the reference count of the mini-object, possibly freeing
201  * the mini-object.
202  */
203 void
204 gst_mini_object_unref (GstMiniObject * mini_object)
205 {
206   g_return_if_fail (mini_object != NULL);
207   g_return_if_fail (mini_object->refcount > 0);
208
209   GST_CAT_TRACE (GST_CAT_REFCOUNTING, "%p unref %d->%d",
210       mini_object,
211       GST_MINI_OBJECT_REFCOUNT_VALUE (mini_object),
212       GST_MINI_OBJECT_REFCOUNT_VALUE (mini_object) - 1);
213
214   if (G_UNLIKELY (g_atomic_int_dec_and_test (&mini_object->refcount))) {
215     gboolean do_free;
216
217     if (mini_object->dispose)
218       do_free = mini_object->dispose (mini_object);
219     else
220       do_free = TRUE;
221
222     /* if the subclass recycled the object (and returned FALSE) we don't
223      * want to free the instance anymore */
224     if (G_LIKELY (do_free)) {
225       /* The weak reference stack is freed in the notification function */
226       if (mini_object->n_weak_refs)
227         weak_refs_notify (mini_object);
228
229 #ifndef GST_DISABLE_TRACE
230       gst_alloc_trace_free (_gst_mini_object_trace, mini_object);
231 #endif
232       if (mini_object->free)
233         mini_object->free (mini_object);
234     }
235   }
236 }
237
238 /**
239  * gst_mini_object_replace:
240  * @olddata: (inout) (transfer full): pointer to a pointer to a mini-object to
241  *     be replaced
242  * @newdata: pointer to new mini-object
243  *
244  * Atomically modifies a pointer to point to a new mini-object.
245  * The reference count of @olddata is decreased and the reference count of
246  * @newdata is increased.
247  *
248  * Either @newdata and the value pointed to by @olddata may be NULL.
249  *
250  * Returns: TRUE if @newdata was different from @olddata
251  */
252 gboolean
253 gst_mini_object_replace (GstMiniObject ** olddata, GstMiniObject * newdata)
254 {
255   GstMiniObject *olddata_val;
256
257   g_return_val_if_fail (olddata != NULL, FALSE);
258
259   GST_CAT_TRACE (GST_CAT_REFCOUNTING, "replace %p (%d) with %p (%d)",
260       *olddata, *olddata ? (*olddata)->refcount : 0,
261       newdata, newdata ? newdata->refcount : 0);
262
263   olddata_val = g_atomic_pointer_get ((gpointer *) olddata);
264
265   if (G_UNLIKELY (olddata_val == newdata))
266     return FALSE;
267
268   if (newdata)
269     gst_mini_object_ref (newdata);
270
271   while (G_UNLIKELY (!g_atomic_pointer_compare_and_exchange ((gpointer *)
272               olddata, olddata_val, newdata))) {
273     olddata_val = g_atomic_pointer_get ((gpointer *) olddata);
274     if (G_UNLIKELY (olddata_val == newdata))
275       break;
276   }
277
278   if (olddata_val)
279     gst_mini_object_unref (olddata_val);
280
281   return olddata_val != newdata;
282 }
283
284 /**
285  * gst_mini_object_steal:
286  * @olddata: (inout) (transfer full): pointer to a pointer to a mini-object to
287  *     be stolen
288  *
289  * Replace the current #GstMiniObject pointer to by @olddata with NULL and
290  * return the old value.
291  *
292  * Returns: the #GstMiniObject at @oldata
293  */
294 GstMiniObject *
295 gst_mini_object_steal (GstMiniObject ** olddata)
296 {
297   GstMiniObject *olddata_val;
298
299   g_return_val_if_fail (olddata != NULL, NULL);
300
301   GST_CAT_TRACE (GST_CAT_REFCOUNTING, "steal %p (%d)",
302       *olddata, *olddata ? (*olddata)->refcount : 0);
303
304   do {
305     olddata_val = g_atomic_pointer_get ((gpointer *) olddata);
306     if (olddata_val == NULL)
307       break;
308   } while (G_UNLIKELY (!g_atomic_pointer_compare_and_exchange ((gpointer *)
309               olddata, olddata_val, NULL)));
310
311   return olddata_val;
312 }
313
314 /**
315  * gst_mini_object_take:
316  * @olddata: (inout) (transfer full): pointer to a pointer to a mini-object to
317  *     be replaced
318  * @newdata: pointer to new mini-object
319  *
320  * Modifies a pointer to point to a new mini-object. The modification
321  * is done atomically. This version is similar to gst_mini_object_replace()
322  * except that it does not increase the refcount of @newdata and thus
323  * takes ownership of @newdata.
324  *
325  * Either @newdata and the value pointed to by @olddata may be NULL.
326  *
327  * Returns: TRUE if @newdata was different from @olddata
328  */
329 gboolean
330 gst_mini_object_take (GstMiniObject ** olddata, GstMiniObject * newdata)
331 {
332   GstMiniObject *olddata_val;
333
334   g_return_val_if_fail (olddata != NULL, FALSE);
335
336   GST_CAT_TRACE (GST_CAT_REFCOUNTING, "take %p (%d) with %p (%d)",
337       *olddata, *olddata ? (*olddata)->refcount : 0,
338       newdata, newdata ? newdata->refcount : 0);
339
340   do {
341     olddata_val = g_atomic_pointer_get ((gpointer *) olddata);
342     if (G_UNLIKELY (olddata_val == newdata))
343       break;
344   } while (G_UNLIKELY (!g_atomic_pointer_compare_and_exchange ((gpointer *)
345               olddata, olddata_val, newdata)));
346
347   if (olddata_val)
348     gst_mini_object_unref (olddata_val);
349
350   return olddata_val != newdata;
351 }
352
353 /**
354  * gst_mini_object_weak_ref: (skip)
355  * @object: #GstMiniObject to reference weakly
356  * @notify: callback to invoke before the mini object is freed
357  * @data: extra data to pass to notify
358  *
359  * Adds a weak reference callback to a mini object. Weak references are
360  * used for notification when a mini object is finalized. They are called
361  * "weak references" because they allow you to safely hold a pointer
362  * to the mini object without calling gst_mini_object_ref()
363  * (gst_mini_object_ref() adds a strong reference, that is, forces the object
364  * to stay alive).
365  *
366  * Since: 0.10.35
367  */
368 void
369 gst_mini_object_weak_ref (GstMiniObject * object,
370     GstMiniObjectWeakNotify notify, gpointer data)
371 {
372   guint i;
373
374   g_return_if_fail (object != NULL);
375   g_return_if_fail (notify != NULL);
376   g_return_if_fail (GST_MINI_OBJECT_REFCOUNT_VALUE (object) >= 1);
377
378   G_LOCK (weak_refs_mutex);
379
380   if (object->n_weak_refs) {
381     /* Don't add the weak reference if it already exists. */
382     for (i = 0; i < object->n_weak_refs; i++) {
383       if (object->weak_refs[i].notify == notify &&
384           object->weak_refs[i].data == data) {
385         g_warning ("%s: Attempt to re-add existing weak ref %p(%p) failed.",
386             G_STRFUNC, notify, data);
387         goto found;
388       }
389     }
390
391     i = object->n_weak_refs++;
392     object->weak_refs =
393         g_realloc (object->weak_refs, sizeof (object->weak_refs[0]) * i);
394   } else {
395     object->weak_refs = g_malloc0 (sizeof (object->weak_refs[0]));
396     object->n_weak_refs = 1;
397     i = 0;
398   }
399   object->weak_refs[i].notify = notify;
400   object->weak_refs[i].data = data;
401 found:
402   G_UNLOCK (weak_refs_mutex);
403 }
404
405 /**
406  * gst_mini_object_weak_unref: (skip)
407  * @object: #GstMiniObject to remove a weak reference from
408  * @notify: callback to search for
409  * @data: data to search for
410  *
411  * Removes a weak reference callback to a mini object.
412  *
413  * Since: 0.10.35
414  */
415 void
416 gst_mini_object_weak_unref (GstMiniObject * object,
417     GstMiniObjectWeakNotify notify, gpointer data)
418 {
419   gboolean found_one = FALSE;
420
421   g_return_if_fail (object != NULL);
422   g_return_if_fail (notify != NULL);
423
424   G_LOCK (weak_refs_mutex);
425
426   if (object->n_weak_refs) {
427     guint i;
428
429     for (i = 0; i < object->n_weak_refs; i++)
430       if (object->weak_refs[i].notify == notify &&
431           object->weak_refs[i].data == data) {
432         found_one = TRUE;
433         object->n_weak_refs -= 1;
434         if (i != object->n_weak_refs)
435           object->weak_refs[i] = object->weak_refs[object->n_weak_refs];
436
437         break;
438       }
439   }
440   G_UNLOCK (weak_refs_mutex);
441   if (!found_one)
442     g_warning ("%s: couldn't find weak ref %p(%p)", G_STRFUNC, notify, data);
443 }