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 #define GST_MINI_OBJECT_GET_CLASS_UNCHECKED(obj) \
49     ((GstMiniObjectClass *) (((GTypeInstance*)(obj))->g_class))
50
51 /* boxed copy and free functions. Don't real copy or free but simply
52  * change the refcount */
53 static GstMiniObject *
54 _gst_mini_object_boxed_copy (GstMiniObject * mini_object)
55 {
56   if (mini_object)
57     return gst_mini_object_ref (mini_object);
58   else
59     return NULL;
60 }
61
62 static void
63 _gst_mini_object_boxed_free (GstMiniObject * mini_object)
64 {
65   if (mini_object)
66     gst_mini_object_unref (mini_object);
67 }
68
69 /**
70  * gst_mini_object_register:
71  * @name: name of the new boxed type
72  *
73  * This function creates a new G_TYPE_BOXED derived type id for a new boxed type
74  * with name @name. The default miniobject refcounting copy and free function
75  * are used for the boxed type.
76  *
77  * Returns: a new G_TYPE_BOXED derived type id for @name.
78  */
79 GType
80 gst_mini_object_register (const gchar * name)
81 {
82   GType type;
83
84   g_return_val_if_fail (name != NULL, 0);
85
86   type = g_boxed_type_register_static (name,
87       (GBoxedCopyFunc) _gst_mini_object_boxed_copy,
88       (GBoxedFreeFunc) _gst_mini_object_boxed_free);
89
90   return type;
91 }
92
93 /**
94  * gst_mini_object_init:
95  * @mini_object: a #GstMiniObject 
96  * @type: the #GType of the mini-object to create
97  * @size: the size of the data
98  *
99  * Initializes a mini-object with the desired type and size.
100  *
101  * MT safe
102  *
103  * Returns: (transfer full): the new mini-object.
104  */
105 void
106 gst_mini_object_init (GstMiniObject * mini_object, GType type, gsize size)
107 {
108   mini_object->type = type;
109   mini_object->refcount = 1;
110   mini_object->flags = 0;
111   mini_object->size = size;
112 }
113
114 /**
115  * gst_mini_object_copy:
116  * @mini_object: the mini-object to copy
117  *
118  * Creates a copy of the mini-object.
119  *
120  * MT safe
121  *
122  * Returns: (transfer full): the new mini-object.
123  */
124 GstMiniObject *
125 gst_mini_object_copy (const GstMiniObject * mini_object)
126 {
127   GstMiniObject *copy;
128
129   g_return_val_if_fail (mini_object != NULL, NULL);
130
131   if (mini_object->copy)
132     copy = mini_object->copy (mini_object);
133   else
134     copy = NULL;
135
136   return copy;
137 }
138
139 /**
140  * gst_mini_object_is_writable:
141  * @mini_object: the mini-object to check
142  *
143  * Checks if a mini-object is writable.  A mini-object is writable
144  * if the reference count is one and the #GST_MINI_OBJECT_FLAG_READONLY
145  * flag is not set.  Modification of a mini-object should only be
146  * done after verifying that it is writable.
147  *
148  * MT safe
149  *
150  * Returns: TRUE if the object is writable.
151  */
152 gboolean
153 gst_mini_object_is_writable (const GstMiniObject * mini_object)
154 {
155   g_return_val_if_fail (mini_object != NULL, FALSE);
156
157   return (GST_MINI_OBJECT_REFCOUNT_VALUE (mini_object) == 1);
158 }
159
160 /**
161  * gst_mini_object_make_writable:
162  * @mini_object: (transfer full): the mini-object to make writable
163  *
164  * Checks if a mini-object is writable.  If not, a writable copy is made and
165  * returned.  This gives away the reference to the original mini object,
166  * and returns a reference to the new object.
167  *
168  * MT safe
169  *
170  * Returns: (transfer full): a mini-object (possibly the same pointer) that
171  *     is writable.
172  */
173 GstMiniObject *
174 gst_mini_object_make_writable (GstMiniObject * mini_object)
175 {
176   GstMiniObject *ret;
177
178   g_return_val_if_fail (mini_object != NULL, NULL);
179
180   if (gst_mini_object_is_writable (mini_object)) {
181     ret = mini_object;
182   } else {
183     ret = gst_mini_object_copy (mini_object);
184     GST_CAT_DEBUG (GST_CAT_PERFORMANCE, "copy %s miniobject %p -> %p",
185         g_type_name (GST_MINI_OBJECT_TYPE (mini_object)), mini_object, ret);
186     gst_mini_object_unref (mini_object);
187   }
188
189   return ret;
190 }
191
192 /**
193  * gst_mini_object_ref:
194  * @mini_object: the mini-object
195  *
196  * Increase the reference count of the mini-object.
197  *
198  * Note that the refcount affects the writeability
199  * of @mini-object, see gst_mini_object_is_writable(). It is
200  * important to note that keeping additional references to
201  * GstMiniObject instances can potentially increase the number
202  * of memcpy operations in a pipeline, especially if the miniobject
203  * is a #GstBuffer.
204  *
205  * Returns: the mini-object.
206  */
207 GstMiniObject *
208 gst_mini_object_ref (GstMiniObject * mini_object)
209 {
210   g_return_val_if_fail (mini_object != NULL, NULL);
211   /* we can't assert that the refcount > 0 since the _free functions
212    * increments the refcount from 0 to 1 again to allow resurecting
213    * the object
214    g_return_val_if_fail (mini_object->refcount > 0, NULL);
215    */
216
217   GST_CAT_TRACE (GST_CAT_REFCOUNTING, "%p ref %d->%d", mini_object,
218       GST_MINI_OBJECT_REFCOUNT_VALUE (mini_object),
219       GST_MINI_OBJECT_REFCOUNT_VALUE (mini_object) + 1);
220
221   g_atomic_int_inc (&mini_object->refcount);
222
223   return mini_object;
224 }
225
226 /**
227  * gst_mini_object_unref:
228  * @mini_object: the mini-object
229  *
230  * Decreases the reference count of the mini-object, possibly freeing
231  * the mini-object.
232  */
233 void
234 gst_mini_object_unref (GstMiniObject * mini_object)
235 {
236   g_return_if_fail (mini_object != NULL);
237   g_return_if_fail (mini_object->refcount > 0);
238
239   GST_CAT_TRACE (GST_CAT_REFCOUNTING, "%p unref %d->%d",
240       mini_object,
241       GST_MINI_OBJECT_REFCOUNT_VALUE (mini_object),
242       GST_MINI_OBJECT_REFCOUNT_VALUE (mini_object) - 1);
243
244   if (G_UNLIKELY (g_atomic_int_dec_and_test (&mini_object->refcount))) {
245     /* At this point, the refcount of the object is 0. We increase the refcount
246      * here because if a subclass recycles the object and gives out a new
247      * reference we don't want to free the instance anymore. */
248     gst_mini_object_ref (mini_object);
249
250     if (mini_object->dispose)
251       mini_object->dispose (mini_object);
252
253     /* decrement the refcount again, if the subclass recycled the object we don't
254      * want to free the instance anymore */
255     if (G_LIKELY (g_atomic_int_dec_and_test (&mini_object->refcount))) {
256 #ifndef GST_DISABLE_TRACE
257       gst_alloc_trace_free (_gst_mini_object_trace, mini_object);
258 #endif
259       if (mini_object->free)
260         mini_object->free (mini_object);
261     }
262   }
263 }
264
265 /**
266  * gst_mini_object_replace:
267  * @olddata: (inout) (transfer full): pointer to a pointer to a mini-object to
268  *     be replaced
269  * @newdata: pointer to new mini-object
270  *
271  * Modifies a pointer to point to a new mini-object.  The modification
272  * is done atomically, and the reference counts are updated correctly.
273  * Either @newdata and the value pointed to by @olddata may be NULL.
274  */
275 void
276 gst_mini_object_replace (GstMiniObject ** olddata, GstMiniObject * newdata)
277 {
278   GstMiniObject *olddata_val;
279
280   g_return_if_fail (olddata != NULL);
281
282   GST_CAT_TRACE (GST_CAT_REFCOUNTING, "replace %p (%d) with %p (%d)",
283       *olddata, *olddata ? (*olddata)->refcount : 0,
284       newdata, newdata ? newdata->refcount : 0);
285
286   olddata_val = g_atomic_pointer_get ((gpointer *) olddata);
287
288   if (olddata_val == newdata)
289     return;
290
291   if (newdata)
292     gst_mini_object_ref (newdata);
293
294   while (!g_atomic_pointer_compare_and_exchange ((gpointer *) olddata,
295           olddata_val, newdata)) {
296     olddata_val = g_atomic_pointer_get ((gpointer *) olddata);
297   }
298
299   if (olddata_val)
300     gst_mini_object_unref (olddata_val);
301 }