2 * Copyright (C) 2005 David Schleef <ds@schleef.org>
4 * gstminiobject.h: Header for GstMiniObject
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.
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.
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.
22 * SECTION:gstminiobject
23 * @short_description: Lightweight base class for the GStreamer object hierarchy
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.
30 * Last reviewed on 2005-11-23 (0.9.5)
36 #include "gst/gst_private.h"
37 #include "gst/gstminiobject.h"
38 #include "gst/gstinfo.h"
39 #include <gobject/gvaluecollector.h>
41 #ifndef GST_DISABLE_TRACE
43 static GstAllocTrace *_gst_mini_object_trace;
46 #define DEBUG_REFCOUNT
49 static void gst_mini_object_base_init (gpointer g_class);
50 static void gst_mini_object_base_finalize (gpointer g_class);
52 static void gst_mini_object_class_init (gpointer g_class, gpointer class_data);
53 static void gst_mini_object_init (GTypeInstance * instance, gpointer klass);
55 static void gst_value_mini_object_init (GValue * value);
56 static void gst_value_mini_object_free (GValue * value);
57 static void gst_value_mini_object_copy (const GValue * src_value,
59 static gpointer gst_value_mini_object_peek_pointer (const GValue * value);
60 static gchar *gst_value_mini_object_collect (GValue * value,
61 guint n_collect_values, GTypeCValue * collect_values, guint collect_flags);
62 static gchar *gst_value_mini_object_lcopy (const GValue * value,
63 guint n_collect_values, GTypeCValue * collect_values, guint collect_flags);
65 static GstMiniObject *gst_mini_object_copy_default (const GstMiniObject * obj);
66 static void gst_mini_object_finalize (GstMiniObject * obj);
69 gst_mini_object_get_type (void)
71 static GType _gst_mini_object_type = 0;
73 if (G_UNLIKELY (_gst_mini_object_type == 0)) {
74 GTypeValueTable value_table = {
75 gst_value_mini_object_init,
76 gst_value_mini_object_free,
77 gst_value_mini_object_copy,
78 gst_value_mini_object_peek_pointer,
80 gst_value_mini_object_collect,
82 gst_value_mini_object_lcopy
84 GTypeInfo mini_object_info = {
85 sizeof (GstMiniObjectClass),
87 gst_mini_object_base_init,
88 gst_mini_object_base_finalize,
92 gst_mini_object_class_init,
95 sizeof (GstMiniObject),
97 (GInstanceInitFunc) gst_mini_object_init,
100 static const GTypeFundamentalInfo mini_object_fundamental_info = {
101 (G_TYPE_FLAG_CLASSED | G_TYPE_FLAG_INSTANTIATABLE |
102 G_TYPE_FLAG_DERIVABLE | G_TYPE_FLAG_DEEP_DERIVABLE)
105 mini_object_info.value_table = &value_table;
107 _gst_mini_object_type = g_type_fundamental_next ();
108 g_type_register_fundamental (_gst_mini_object_type, "GstMiniObject",
109 &mini_object_info, &mini_object_fundamental_info, G_TYPE_FLAG_ABSTRACT);
111 #ifndef GST_DISABLE_TRACE
112 _gst_mini_object_trace =
113 gst_alloc_trace_register (g_type_name (_gst_mini_object_type));
117 return _gst_mini_object_type;
122 gst_mini_object_base_init (gpointer g_class)
128 gst_mini_object_base_finalize (gpointer g_class)
135 gst_mini_object_class_init (gpointer g_class, gpointer class_data)
137 GstMiniObjectClass *mo_class = GST_MINI_OBJECT_CLASS (g_class);
139 mo_class->copy = gst_mini_object_copy_default;
140 mo_class->finalize = gst_mini_object_finalize;
144 gst_mini_object_init (GTypeInstance * instance, gpointer klass)
146 GstMiniObject *mini_object = GST_MINI_OBJECT_CAST (instance);
148 mini_object->refcount = 1;
151 static GstMiniObject *
152 gst_mini_object_copy_default (const GstMiniObject * obj)
154 g_warning ("GstMiniObject classes must implement GstMiniObject::copy");
159 gst_mini_object_finalize (GstMiniObject * obj)
165 * gst_mini_object_new:
166 * @type: the #GType of the mini-object to create
168 * Creates a new mini-object of the desired type.
172 * Returns: the new mini-object.
175 gst_mini_object_new (GType type)
177 GstMiniObject *mini_object;
179 /* we don't support dynamic types because they really aren't useful,
180 * and could cause refcount problems */
181 mini_object = (GstMiniObject *) g_type_create_instance (type);
183 #ifndef GST_DISABLE_TRACE
184 gst_alloc_trace_new (_gst_mini_object_trace, mini_object);
190 /* FIXME 0.11: Current way of doing the copy makes it impossible
191 * to currectly chain to the parent classes and do a copy in a
192 * subclass without knowing all internals of the parent classes.
194 * For 0.11 we should do something like the following:
195 * - The GstMiniObjectClass::copy() implementation of GstMiniObject
196 * should call g_type_create_instance() with the type of the source
198 * - All GstMiniObjectClass::copy() implementations should as first
199 * thing chain up to the parent class and then do whatever they need
200 * to do to copy their type specific data. Note that this way the
201 * instance_init() functions are called!
205 * gst_mini_object_copy:
206 * @mini_object: the mini-object to copy
208 * Creates a copy of the mini-object.
212 * Returns: the new mini-object.
215 gst_mini_object_copy (const GstMiniObject * mini_object)
217 GstMiniObjectClass *mo_class;
219 g_return_val_if_fail (mini_object != NULL, NULL);
221 mo_class = GST_MINI_OBJECT_GET_CLASS (mini_object);
223 return mo_class->copy (mini_object);
227 * gst_mini_object_is_writable:
228 * @mini_object: the mini-object to check
230 * Checks if a mini-object is writable. A mini-object is writable
231 * if the reference count is one and the #GST_MINI_OBJECT_FLAG_READONLY
232 * flag is not set. Modification of a mini-object should only be
233 * done after verifying that it is writable.
237 * Returns: TRUE if the object is writable.
240 gst_mini_object_is_writable (const GstMiniObject * mini_object)
242 g_return_val_if_fail (mini_object != NULL, FALSE);
244 return (GST_MINI_OBJECT_REFCOUNT_VALUE (mini_object) == 1) &&
245 ((mini_object->flags & GST_MINI_OBJECT_FLAG_READONLY) == 0);
249 * gst_mini_object_make_writable:
250 * @mini_object: the mini-object to make writable
252 * Checks if a mini-object is writable. If not, a writable copy is made and
253 * returned. This gives away the reference to the original mini object,
254 * and returns a reference to the new object.
258 * Returns: a mini-object (possibly the same pointer) that is writable.
261 gst_mini_object_make_writable (GstMiniObject * mini_object)
265 g_return_val_if_fail (mini_object != NULL, NULL);
267 if (gst_mini_object_is_writable (mini_object)) {
268 ret = (GstMiniObject *) mini_object;
270 ret = gst_mini_object_copy (mini_object);
271 gst_mini_object_unref ((GstMiniObject *) mini_object);
278 * gst_mini_object_ref:
279 * @mini_object: the mini-object
281 * Increase the reference count of the mini-object.
283 * Note that the refcount affects the writeability
284 * of @mini-object, see gst_mini_object_is_writable(). It is
285 * important to note that keeping additional references to
286 * GstMiniObject instances can potentially increase the number
287 * of memcpy operations in a pipeline, especially if the miniobject
290 * Returns: the mini-object.
293 gst_mini_object_ref (GstMiniObject * mini_object)
295 g_return_val_if_fail (mini_object != NULL, NULL);
296 /* we cannot assert that the refcount > 0 since a bufferalloc
297 * function might resurrect an object
298 g_return_val_if_fail (mini_object->refcount > 0, NULL);
300 #ifdef DEBUG_REFCOUNT
301 g_return_val_if_fail (GST_IS_MINI_OBJECT (mini_object), NULL);
303 GST_CAT_LOG (GST_CAT_REFCOUNTING, "%p ref %d->%d",
305 GST_MINI_OBJECT_REFCOUNT_VALUE (mini_object),
306 GST_MINI_OBJECT_REFCOUNT_VALUE (mini_object) + 1);
309 g_atomic_int_inc (&mini_object->refcount);
315 gst_mini_object_free (GstMiniObject * mini_object)
317 GstMiniObjectClass *mo_class;
319 mo_class = GST_MINI_OBJECT_GET_CLASS (mini_object);
320 mo_class->finalize (mini_object);
322 /* if the refcount is still 0 we can really free the
323 * object, else the finalize method recycled the object */
324 if (g_atomic_int_get (&mini_object->refcount) == 0) {
325 #ifndef GST_DISABLE_TRACE
326 gst_alloc_trace_free (_gst_mini_object_trace, mini_object);
328 g_type_free_instance ((GTypeInstance *) mini_object);
333 * gst_mini_object_unref:
334 * @mini_object: the mini-object
336 * Decreases the reference count of the mini-object, possibly freeing
340 gst_mini_object_unref (GstMiniObject * mini_object)
342 g_return_if_fail (mini_object != NULL);
343 g_return_if_fail (mini_object->refcount > 0);
345 #ifdef DEBUG_REFCOUNT
346 g_return_if_fail (GST_IS_MINI_OBJECT (mini_object));
348 GST_CAT_LOG (GST_CAT_REFCOUNTING, "%p unref %d->%d",
350 GST_MINI_OBJECT_REFCOUNT_VALUE (mini_object),
351 GST_MINI_OBJECT_REFCOUNT_VALUE (mini_object) - 1);
354 if (G_UNLIKELY (g_atomic_int_dec_and_test (&mini_object->refcount))) {
355 gst_mini_object_free (mini_object);
360 * gst_mini_object_replace:
361 * @olddata: pointer to a pointer to a mini-object to be replaced
362 * @newdata: pointer to new mini-object
364 * Modifies a pointer to point to a new mini-object. The modification
365 * is done atomically, and the reference counts are updated correctly.
366 * Either @newdata and the value pointed to by @olddata may be NULL.
369 gst_mini_object_replace (GstMiniObject ** olddata, GstMiniObject * newdata)
371 GstMiniObject *olddata_val;
373 g_return_if_fail (olddata != NULL);
375 #ifdef DEBUG_REFCOUNT
376 GST_CAT_LOG (GST_CAT_REFCOUNTING, "replace %p (%d) with %p (%d)",
377 *olddata, *olddata ? (*olddata)->refcount : 0,
378 newdata, newdata ? newdata->refcount : 0);
381 olddata_val = g_atomic_pointer_get ((gpointer *) olddata);
383 if (olddata_val == newdata)
387 gst_mini_object_ref (newdata);
389 while (!g_atomic_pointer_compare_and_exchange ((gpointer *) olddata,
390 olddata_val, newdata)) {
391 olddata_val = g_atomic_pointer_get ((gpointer *) olddata);
395 gst_mini_object_unref (olddata_val);
399 gst_value_mini_object_init (GValue * value)
401 value->data[0].v_pointer = NULL;
405 gst_value_mini_object_free (GValue * value)
407 if (value->data[0].v_pointer) {
408 gst_mini_object_unref (GST_MINI_OBJECT_CAST (value->data[0].v_pointer));
413 gst_value_mini_object_copy (const GValue * src_value, GValue * dest_value)
415 if (src_value->data[0].v_pointer) {
416 dest_value->data[0].v_pointer =
417 gst_mini_object_ref (GST_MINI_OBJECT_CAST (src_value->data[0].
420 dest_value->data[0].v_pointer = NULL;
425 gst_value_mini_object_peek_pointer (const GValue * value)
427 return value->data[0].v_pointer;
431 gst_value_mini_object_collect (GValue * value, guint n_collect_values,
432 GTypeCValue * collect_values, guint collect_flags)
434 gst_value_set_mini_object (value, collect_values[0].v_pointer);
440 gst_value_mini_object_lcopy (const GValue * value, guint n_collect_values,
441 GTypeCValue * collect_values, guint collect_flags)
443 gpointer *mini_object_p = collect_values[0].v_pointer;
445 if (!mini_object_p) {
446 return g_strdup_printf ("value location for '%s' passed as NULL",
447 G_VALUE_TYPE_NAME (value));
450 if (!value->data[0].v_pointer)
451 *mini_object_p = NULL;
452 else if (collect_flags & G_VALUE_NOCOPY_CONTENTS)
453 *mini_object_p = value->data[0].v_pointer;
455 *mini_object_p = gst_mini_object_ref (value->data[0].v_pointer);
461 * gst_value_set_mini_object:
462 * @value: a valid #GValue of %GST_TYPE_MINI_OBJECT derived type
463 * @mini_object: mini object value to set
465 * Set the contents of a %GST_TYPE_MINI_OBJECT derived #GValue to
467 * The caller retains ownership of the reference.
470 gst_value_set_mini_object (GValue * value, GstMiniObject * mini_object)
474 g_return_if_fail (GST_VALUE_HOLDS_MINI_OBJECT (value));
475 g_return_if_fail (mini_object == NULL || GST_IS_MINI_OBJECT (mini_object));
477 pointer_p = &value->data[0].v_pointer;
478 gst_mini_object_replace ((GstMiniObject **) pointer_p, mini_object);
482 * gst_value_take_mini_object:
483 * @value: a valid #GValue of %GST_TYPE_MINI_OBJECT derived type
484 * @mini_object: mini object value to take
486 * Set the contents of a %GST_TYPE_MINI_OBJECT derived #GValue to
488 * Takes over the ownership of the caller's reference to @mini_object;
489 * the caller doesn't have to unref it any more.
492 gst_value_take_mini_object (GValue * value, GstMiniObject * mini_object)
496 g_return_if_fail (GST_VALUE_HOLDS_MINI_OBJECT (value));
497 g_return_if_fail (mini_object == NULL || GST_IS_MINI_OBJECT (mini_object));
499 pointer_p = &value->data[0].v_pointer;
500 /* takes additional refcount */
501 gst_mini_object_replace ((GstMiniObject **) pointer_p, mini_object);
502 /* remove additional refcount */
504 gst_mini_object_unref (mini_object);
508 * gst_value_get_mini_object:
509 * @value: a valid #GValue of %GST_TYPE_MINI_OBJECT derived type
511 * Get the contents of a %GST_TYPE_MINI_OBJECT derived #GValue.
512 * Does not increase the refcount of the returned object.
514 * Returns: mini object contents of @value
517 gst_value_get_mini_object (const GValue * value)
519 g_return_val_if_fail (GST_VALUE_HOLDS_MINI_OBJECT (value), NULL);
521 return value->data[0].v_pointer;
526 static GType gst_param_spec_mini_object_get_type (void);
528 #define GST_TYPE_PARAM_SPEC_MINI_OBJECT (gst_param_spec_mini_object_get_type())
529 #define GST_PARAM_SPEC_MINI_OBJECT(obj) (G_TYPE_CHECK_INSTANCE_CAST((obj), GST_TYPE_PARAM_SPEC_MINI_OBJECT, GstParamSpecMiniObject))
531 typedef struct _GstParamSpecMiniObject GstParamSpecMiniObject;
532 struct _GstParamSpecMiniObject
534 GParamSpec parent_instance;
538 param_mini_object_init (GParamSpec * pspec)
540 /* GParamSpecMiniObject *ospec = G_PARAM_SPEC_MINI_OBJECT (pspec); */
544 param_mini_object_set_default (GParamSpec * pspec, GValue * value)
546 value->data[0].v_pointer = NULL;
550 param_mini_object_validate (GParamSpec * pspec, GValue * value)
552 GstParamSpecMiniObject *ospec = GST_PARAM_SPEC_MINI_OBJECT (pspec);
553 GstMiniObject *mini_object = value->data[0].v_pointer;
554 gboolean changed = FALSE;
557 && !g_value_type_compatible (G_OBJECT_TYPE (mini_object),
558 G_PARAM_SPEC_VALUE_TYPE (ospec))) {
559 gst_mini_object_unref (mini_object);
560 value->data[0].v_pointer = NULL;
568 param_mini_object_values_cmp (GParamSpec * pspec,
569 const GValue * value1, const GValue * value2)
571 guint8 *p1 = value1->data[0].v_pointer;
572 guint8 *p2 = value2->data[0].v_pointer;
574 /* not much to compare here, try to at least provide stable lesser/greater result */
576 return p1 < p2 ? -1 : p1 > p2;
580 gst_param_spec_mini_object_get_type (void)
584 if (G_UNLIKELY (type) == 0) {
585 static const GParamSpecTypeInfo pspec_info = {
586 sizeof (GstParamSpecMiniObject), /* instance_size */
587 16, /* n_preallocs */
588 param_mini_object_init, /* instance_init */
589 G_TYPE_OBJECT, /* value_type */
591 param_mini_object_set_default, /* value_set_default */
592 param_mini_object_validate, /* value_validate */
593 param_mini_object_values_cmp, /* values_cmp */
595 /* FIXME 0.11: Should really be GstParamSpecMiniObject */
596 type = g_param_type_register_static ("GParamSpecMiniObject", &pspec_info);
603 * gst_param_spec_mini_object:
604 * @name: the canonical name of the property
605 * @nick: the nickname of the property
606 * @blurb: a short description of the property
607 * @object_type: the #GstMiniObjectType for the property
608 * @flags: a combination of #GParamFlags
610 * Creates a new #GParamSpec instance that hold #GstMiniObject references.
612 * Returns: a newly allocated #GParamSpec instance
615 gst_param_spec_mini_object (const char *name, const char *nick,
616 const char *blurb, GType object_type, GParamFlags flags)
618 GstParamSpecMiniObject *ospec;
620 g_return_val_if_fail (g_type_is_a (object_type, GST_TYPE_MINI_OBJECT), NULL);
622 ospec = g_param_spec_internal (GST_TYPE_PARAM_SPEC_MINI_OBJECT,
623 name, nick, blurb, flags);
624 G_PARAM_SPEC (ospec)->value_type = object_type;
626 return G_PARAM_SPEC (ospec);