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 #ifndef GST_DISABLE_TRACE
  42 #include "gsttrace.h"
  43 static GstAllocTrace *_gst_mini_object_trace;
  44 #endif
  45
  46 #define GST_MINI_OBJECT_GET_CLASS_UNCHECKED(obj) \
  47     ((GstMiniObjectClass *) (((GTypeInstance*)(obj))->g_class))
  48
  49 /* Structure used for storing weak references */
  50 typedef struct
  51 {
  52   GstMiniObject *object;
  53   guint n_weak_refs;
  54   struct
  55   {
  56     GstMiniObjectWeakNotify notify;
  57     gpointer data;
  58   } weak_refs[1];               /* flexible array */
  59 } WeakRefStack;
  60
  61 /* Structure for storing a mini object's private data */
  62 struct _GstMiniObjectPrivate
  63 {
  64   WeakRefStack *wstack;
  65 };
  66
  67 #if 0
  68 static void gst_mini_object_base_init (gpointer g_class);
  69 static void gst_mini_object_base_finalize (gpointer g_class);
  70 #endif
  71 static void gst_mini_object_class_init (gpointer g_class, gpointer class_data);
  72 static void gst_mini_object_init (GTypeInstance * instance, gpointer klass);
  73
  74 static void gst_value_mini_object_init (GValue * value);
  75 static void gst_value_mini_object_free (GValue * value);
  76 static void weak_refs_notify (WeakRefStack * data);
  77 static void gst_value_mini_object_copy (const GValue * src_value,
  78     GValue * dest_value);
  79 static gpointer gst_value_mini_object_peek_pointer (const GValue * value);
  80 static gchar *gst_value_mini_object_collect (GValue * value,
  81     guint n_collect_values, GTypeCValue * collect_values, guint collect_flags);
  82 static gchar *gst_value_mini_object_lcopy (const GValue * value,
  83     guint n_collect_values, GTypeCValue * collect_values, guint collect_flags);
  84
  85 static GstMiniObject *gst_mini_object_copy_default (const GstMiniObject * obj);
  86 static void gst_mini_object_finalize (GstMiniObject * obj);
  87
  88 /* Mutex used for weak referencing */
  89 G_LOCK_DEFINE_STATIC (weak_refs_mutex);
  90
  91 GType
  92 gst_mini_object_get_type (void)
  93 {
  94   static volatile GType _gst_mini_object_type = 0;
  95
  96   if (g_once_init_enter (&_gst_mini_object_type)) {
  97     GType _type;
  98     static const GTypeValueTable value_table = {
  99       gst_value_mini_object_init,
 100       gst_value_mini_object_free,
 101       gst_value_mini_object_copy,
 102       gst_value_mini_object_peek_pointer,
 103       (char *) "p",
 104       gst_value_mini_object_collect,
 105       (char *) "p",
 106       gst_value_mini_object_lcopy
 107     };
 108     static const GTypeInfo mini_object_info = {
 109       sizeof (GstMiniObjectClass),
 110 #if 0
 111       gst_mini_object_base_init,
 112       gst_mini_object_base_finalize,
 113 #else
 114       NULL, NULL,
 115 #endif
 116       gst_mini_object_class_init,
 117       NULL,
 118       NULL,
 119       sizeof (GstMiniObject),
 120       0,
 121       (GInstanceInitFunc) gst_mini_object_init,
 122       &value_table
 123     };
 124     static const GTypeFundamentalInfo mini_object_fundamental_info = {
 125       (G_TYPE_FLAG_CLASSED | G_TYPE_FLAG_INSTANTIATABLE |
 126           G_TYPE_FLAG_DERIVABLE | G_TYPE_FLAG_DEEP_DERIVABLE)
 127     };
 128
 129     _type = g_type_fundamental_next ();
 130     g_type_register_fundamental (_type, "GstMiniObject",
 131         &mini_object_info, &mini_object_fundamental_info, G_TYPE_FLAG_ABSTRACT);
 132
 133 #ifndef GST_DISABLE_TRACE
 134     _gst_mini_object_trace = gst_alloc_trace_register (g_type_name (_type));
 135 #endif
 136     g_once_init_leave (&_gst_mini_object_type, _type);
 137   }
 138
 139   return _gst_mini_object_type;
 140 }
 141
 142 #if 0
 143 static void
 144 gst_mini_object_base_init (gpointer g_class)
 145 {
 146   /* do nothing */
 147 }
 148
 149 static void
 150 gst_mini_object_base_finalize (gpointer g_class)
 151 {
 152   /* do nothing */
 153 }
 154 #endif
 155
 156 static void
 157 gst_mini_object_class_init (gpointer g_class, gpointer class_data)
 158 {
 159   GstMiniObjectClass *mo_class = GST_MINI_OBJECT_CLASS (g_class);
 160
 161   mo_class->copy = gst_mini_object_copy_default;
 162   mo_class->finalize = gst_mini_object_finalize;
 163
 164   /* Set the instance data type */
 165   g_type_class_add_private (g_class, sizeof (GstMiniObjectPrivate));
 166 }
 167
 168 static void
 169 gst_mini_object_init (GTypeInstance * instance, gpointer klass)
 170 {
 171   GstMiniObject *mini_object = GST_MINI_OBJECT_CAST (instance);
 172
 173   mini_object->refcount = 1;
 174
 175   /* we delay initialising the mini object's private data until it's actually
 176    * needed for now (mini_object->priv automatically inited to NULL) */
 177 }
 178
 179 static GstMiniObject *
 180 gst_mini_object_copy_default (const GstMiniObject * obj)
 181 {
 182   g_warning ("GstMiniObject classes must implement GstMiniObject::copy");
 183   return NULL;
 184 }
 185
 186 static void
 187 gst_mini_object_finalize (GstMiniObject * obj)
 188 {
 189   /* do nothing */
 190
 191   /* WARNING: if anything is ever put in this method, make sure that the
 192    * following sub-classes' finalize method chains up to this one:
 193    * gstbuffer
 194    * gstevent
 195    * gstmessage
 196    * gstquery
 197    */
 198 }
 199
 200 /**
 201  * gst_mini_object_new:
 202  * @type: the #GType of the mini-object to create
 203  *
 204  * Creates a new mini-object of the desired type.
 205  *
 206  * MT safe
 207  *
 208  * Returns: (transfer full): the new mini-object.
 209  */
 210 GstMiniObject *
 211 gst_mini_object_new (GType type)
 212 {
 213   GstMiniObject *mini_object;
 214
 215   /* we don't support dynamic types because they really aren't useful,
 216    * and could cause refcount problems */
 217   mini_object = (GstMiniObject *) g_type_create_instance (type);
 218
 219 #ifndef GST_DISABLE_TRACE
 220   gst_alloc_trace_new (_gst_mini_object_trace, mini_object);
 221 #endif
 222
 223   return mini_object;
 224 }
 225
 226 /* FIXME 0.11: Current way of doing the copy makes it impossible
 227  * to currectly chain to the parent classes and do a copy in a
 228  * subclass without knowing all internals of the parent classes.
 229  *
 230  * For 0.11 we should do something like the following:
 231  *  - The GstMiniObjectClass::copy() implementation of GstMiniObject
 232  *    should call g_type_create_instance() with the type of the source
 233  *    object.
 234  *  - All GstMiniObjectClass::copy() implementations should as first
 235  *    thing chain up to the parent class and then do whatever they need
 236  *    to do to copy their type specific data. Note that this way the
 237  *    instance_init() functions are called!
 238  */
 239
 240 /**
 241  * gst_mini_object_copy:
 242  * @mini_object: the mini-object to copy
 243  *
 244  * Creates a copy of the mini-object.
 245  *
 246  * MT safe
 247  *
 248  * Returns: (transfer full): the new mini-object.
 249  */
 250 GstMiniObject *
 251 gst_mini_object_copy (const GstMiniObject * mini_object)
 252 {
 253   GstMiniObjectClass *mo_class;
 254
 255   g_return_val_if_fail (mini_object != NULL, NULL);
 256
 257   mo_class = GST_MINI_OBJECT_GET_CLASS (mini_object);
 258
 259   return mo_class->copy (mini_object);
 260 }
 261
 262 /**
 263  * gst_mini_object_is_writable:
 264  * @mini_object: the mini-object to check
 265  *
 266  * Checks if a mini-object is writable.  A mini-object is writable
 267  * if the reference count is one and the #GST_MINI_OBJECT_FLAG_READONLY
 268  * flag is not set.  Modification of a mini-object should only be
 269  * done after verifying that it is writable.
 270  *
 271  * MT safe
 272  *
 273  * Returns: TRUE if the object is writable.
 274  */
 275 gboolean
 276 gst_mini_object_is_writable (const GstMiniObject * mini_object)
 277 {
 278   g_return_val_if_fail (mini_object != NULL, FALSE);
 279
 280   return (GST_MINI_OBJECT_REFCOUNT_VALUE (mini_object) == 1) &&
 281       ((mini_object->flags & GST_MINI_OBJECT_FLAG_READONLY) == 0);
 282 }
 283
 284 /**
 285  * gst_mini_object_make_writable:
 286  * @mini_object: (transfer full): the mini-object to make writable
 287  *
 288  * Checks if a mini-object is writable.  If not, a writable copy is made and
 289  * returned.  This gives away the reference to the original mini object,
 290  * and returns a reference to the new object.
 291  *
 292  * MT safe
 293  *
 294  * Returns: (transfer full): a mini-object (possibly the same pointer) that
 295  *     is writable.
 296  */
 297 GstMiniObject *
 298 gst_mini_object_make_writable (GstMiniObject * mini_object)
 299 {
 300   GstMiniObject *ret;
 301
 302   g_return_val_if_fail (mini_object != NULL, NULL);
 303
 304   if (gst_mini_object_is_writable (mini_object)) {
 305     ret = mini_object;
 306   } else {
 307     GST_CAT_DEBUG (GST_CAT_PERFORMANCE, "copy %s miniobject",
 308         g_type_name (G_TYPE_FROM_INSTANCE (mini_object)));
 309     ret = gst_mini_object_copy (mini_object);
 310     gst_mini_object_unref (mini_object);
 311   }
 312
 313   return ret;
 314 }
 315
 316 /**
 317  * gst_mini_object_ref:
 318  * @mini_object: the mini-object
 319  *
 320  * Increase the reference count of the mini-object.
 321  *
 322  * Note that the refcount affects the writeability
 323  * of @mini-object, see gst_mini_object_is_writable(). It is
 324  * important to note that keeping additional references to
 325  * GstMiniObject instances can potentially increase the number
 326  * of memcpy operations in a pipeline, especially if the miniobject
 327  * is a #GstBuffer.
 328  *
 329  * Returns: (transfer full): the mini-object.
 330  */
 331 GstMiniObject *
 332 gst_mini_object_ref (GstMiniObject * mini_object)
 333 {
 334   g_return_val_if_fail (mini_object != NULL, NULL);
 335   /* we can't assert that the refcount > 0 since the _free functions
 336    * increments the refcount from 0 to 1 again to allow resurecting
 337    * the object
 338    g_return_val_if_fail (mini_object->refcount > 0, NULL);
 339    */
 340   g_return_val_if_fail (GST_IS_MINI_OBJECT (mini_object), NULL);
 341
 342   GST_CAT_TRACE (GST_CAT_REFCOUNTING, "%p ref %d->%d", mini_object,
 343       GST_MINI_OBJECT_REFCOUNT_VALUE (mini_object),
 344       GST_MINI_OBJECT_REFCOUNT_VALUE (mini_object) + 1);
 345
 346   g_atomic_int_inc (&mini_object->refcount);
 347
 348   return mini_object;
 349 }
 350
 351 static void
 352 weak_refs_notify (WeakRefStack * wstack)
 353 {
 354   guint i;
 355
 356   for (i = 0; i < wstack->n_weak_refs; i++)
 357     wstack->weak_refs[i].notify (wstack->weak_refs[i].data, wstack->object);
 358   g_free (wstack);
 359 }
 360
 361 static void
 362 gst_mini_object_free (GstMiniObject * mini_object)
 363 {
 364   GstMiniObjectClass *mo_class;
 365
 366   /* At this point, the refcount of the object is 0. We increase the refcount
 367    * here because if a subclass recycles the object and gives out a new
 368    * reference we don't want to free the instance anymore. */
 369   GST_CAT_TRACE (GST_CAT_REFCOUNTING, "%p ref %d->%d", mini_object,
 370       GST_MINI_OBJECT_REFCOUNT_VALUE (mini_object),
 371       GST_MINI_OBJECT_REFCOUNT_VALUE (mini_object) + 1);
 372
 373   g_atomic_int_inc (&mini_object->refcount);
 374
 375   mo_class = GST_MINI_OBJECT_GET_CLASS_UNCHECKED (mini_object);
 376   mo_class->finalize (mini_object);
 377
 378   /* decrement the refcount again, if the subclass recycled the object we don't
 379    * want to free the instance anymore */
 380   if (G_LIKELY (g_atomic_int_dec_and_test (&mini_object->refcount))) {
 381     /* The weak reference stack is freed in the notification function */
 382     if (mini_object->priv != NULL && mini_object->priv->wstack != NULL)
 383       weak_refs_notify (mini_object->priv->wstack);
 384
 385 #ifndef GST_DISABLE_TRACE
 386     gst_alloc_trace_free (_gst_mini_object_trace, mini_object);
 387 #endif
 388     g_type_free_instance ((GTypeInstance *) mini_object);
 389   }
 390 }
 391
 392 /**
 393  * gst_mini_object_unref:
 394  * @mini_object: the mini-object
 395  *
 396  * Decreases the reference count of the mini-object, possibly freeing
 397  * the mini-object.
 398  */
 399 void
 400 gst_mini_object_unref (GstMiniObject * mini_object)
 401 {
 402   g_return_if_fail (GST_IS_MINI_OBJECT (mini_object));
 403   g_return_if_fail (mini_object->refcount > 0);
 404
 405   GST_CAT_TRACE (GST_CAT_REFCOUNTING, "%p unref %d->%d",
 406       mini_object,
 407       GST_MINI_OBJECT_REFCOUNT_VALUE (mini_object),
 408       GST_MINI_OBJECT_REFCOUNT_VALUE (mini_object) - 1);
 409
 410   if (G_UNLIKELY (g_atomic_int_dec_and_test (&mini_object->refcount))) {
 411     gst_mini_object_free (mini_object);
 412   }
 413 }
 414
 415 /**
 416  * gst_mini_object_weak_ref: (skip)
 417  * @object: #GstMiniObject to reference weakly
 418  * @notify: callback to invoke before the mini object is freed
 419  * @data: extra data to pass to notify
 420  *
 421  * Adds a weak reference callback to a mini object. Weak references are
 422  * used for notification when a mini object is finalized. They are called
 423  * "weak references" because they allow you to safely hold a pointer
 424  * to the mini object without calling gst_mini_object_ref()
 425  * (gst_mini_object_ref() adds a strong reference, that is, forces the object
 426  * to stay alive).
 427  *
 428  * Since: 0.10.36
 429  */
 430 void
 431 gst_mini_object_weak_ref (GstMiniObject * object,
 432     GstMiniObjectWeakNotify notify, gpointer data)
 433 {
 434   guint i;
 435
 436   g_return_if_fail (GST_IS_MINI_OBJECT (object));
 437   g_return_if_fail (notify != NULL);
 438   g_return_if_fail (GST_MINI_OBJECT_REFCOUNT_VALUE (object) >= 1);
 439
 440   G_LOCK (weak_refs_mutex);
 441
 442   if (object->priv == NULL) {
 443     object->priv = G_TYPE_INSTANCE_GET_PRIVATE (object, GST_TYPE_MINI_OBJECT,
 444         GstMiniObjectPrivate);
 445
 446     /* object->priv->wstack will have been inited to NULL automatically */
 447   }
 448
 449   if (object->priv->wstack) {
 450     /* Don't add the weak reference if it already exists. */
 451     for (i = 0; i < object->priv->wstack->n_weak_refs; i++) {
 452       if (object->priv->wstack->weak_refs[i].notify == notify &&
 453           object->priv->wstack->weak_refs[i].data == data) {
 454         g_warning ("%s: Attempt to re-add existing weak ref %p(%p) failed.",
 455             G_STRFUNC, notify, data);
 456         goto found;
 457       }
 458     }
 459
 460     i = object->priv->wstack->n_weak_refs++;
 461     object->priv->wstack =
 462         g_realloc (object->priv->wstack, sizeof (*(object->priv->wstack)) +
 463         sizeof (object->priv->wstack->weak_refs[0]) * i);
 464   } else {
 465     object->priv->wstack = g_renew (WeakRefStack, NULL, 1);
 466     object->priv->wstack->object = object;
 467     object->priv->wstack->n_weak_refs = 1;
 468     i = 0;
 469   }
 470   object->priv->wstack->weak_refs[i].notify = notify;
 471   object->priv->wstack->weak_refs[i].data = data;
 472 found:
 473   G_UNLOCK (weak_refs_mutex);
 474 }
 475
 476 /**
 477  * gst_mini_object_weak_unref: (skip)
 478  * @object: #GstMiniObject to remove a weak reference from
 479  * @notify: callback to search for
 480  * @data: data to search for
 481  *
 482  * Removes a weak reference callback to a mini object.
 483  *
 484  * Since: 0.10.36
 485  */
 486 void
 487 gst_mini_object_weak_unref (GstMiniObject * object,
 488     GstMiniObjectWeakNotify notify, gpointer data)
 489 {
 490   gboolean found_one = FALSE;
 491
 492   g_return_if_fail (GST_IS_MINI_OBJECT (object));
 493   g_return_if_fail (notify != NULL);
 494
 495   G_LOCK (weak_refs_mutex);
 496
 497   if (object->priv != NULL && object->priv->wstack != NULL) {
 498     guint i;
 499
 500     for (i = 0; i < object->priv->wstack->n_weak_refs; i++)
 501       if (object->priv->wstack->weak_refs[i].notify == notify &&
 502           object->priv->wstack->weak_refs[i].data == data) {
 503         found_one = TRUE;
 504         object->priv->wstack->n_weak_refs -= 1;
 505         if (i != object->priv->wstack->n_weak_refs)
 506           object->priv->wstack->weak_refs[i] =
 507               object->priv->wstack->weak_refs[object->priv->wstack->
 508               n_weak_refs];
 509
 510         break;
 511       }
 512   }
 513   G_UNLOCK (weak_refs_mutex);
 514   if (!found_one)
 515     g_warning ("%s: couldn't find weak ref %p(%p)", G_STRFUNC, notify, data);
 516 }
 517
 518 /**
 519  * gst_mini_object_replace:
 520  * @olddata: (inout) (transfer full): pointer to a pointer to a mini-object to
 521  *     be replaced
 522  * @newdata: pointer to new mini-object
 523  *
 524  * Modifies a pointer to point to a new mini-object.  The modification
 525  * is done atomically, and the reference counts are updated correctly.
 526  * Either @newdata and the value pointed to by @olddata may be NULL.
 527  */
 528 void
 529 gst_mini_object_replace (GstMiniObject ** olddata, GstMiniObject * newdata)
 530 {
 531   GstMiniObject *olddata_val;
 532
 533   g_return_if_fail (olddata != NULL);
 534
 535   GST_CAT_TRACE (GST_CAT_REFCOUNTING, "replace %p (%d) with %p (%d)",
 536       *olddata, *olddata ? (*olddata)->refcount : 0,
 537       newdata, newdata ? newdata->refcount : 0);
 538
 539   olddata_val = g_atomic_pointer_get ((gpointer *) olddata);
 540
 541   if (olddata_val == newdata)
 542     return;
 543
 544   if (newdata)
 545     gst_mini_object_ref (newdata);
 546
 547   while (!g_atomic_pointer_compare_and_exchange ((gpointer *) olddata,
 548           olddata_val, newdata)) {
 549     olddata_val = g_atomic_pointer_get ((gpointer *) olddata);
 550   }
 551
 552   if (olddata_val)
 553     gst_mini_object_unref (olddata_val);
 554 }
 555
 556 static void
 557 gst_value_mini_object_init (GValue * value)
 558 {
 559   value->data[0].v_pointer = NULL;
 560 }
 561
 562 static void
 563 gst_value_mini_object_free (GValue * value)
 564 {
 565   if (value->data[0].v_pointer) {
 566     gst_mini_object_unref (GST_MINI_OBJECT_CAST (value->data[0].v_pointer));
 567   }
 568 }
 569
 570 static void
 571 gst_value_mini_object_copy (const GValue * src_value, GValue * dest_value)
 572 {
 573   if (src_value->data[0].v_pointer) {
 574     dest_value->data[0].v_pointer =
 575         gst_mini_object_ref (GST_MINI_OBJECT_CAST (src_value->data[0].
 576             v_pointer));
 577   } else {
 578     dest_value->data[0].v_pointer = NULL;
 579   }
 580 }
 581
 582 static gpointer
 583 gst_value_mini_object_peek_pointer (const GValue * value)
 584 {
 585   return value->data[0].v_pointer;
 586 }
 587
 588 static gchar *
 589 gst_value_mini_object_collect (GValue * value, guint n_collect_values,
 590     GTypeCValue * collect_values, guint collect_flags)
 591 {
 592   if (collect_values[0].v_pointer) {
 593     value->data[0].v_pointer =
 594         gst_mini_object_ref (collect_values[0].v_pointer);
 595   } else {
 596     value->data[0].v_pointer = NULL;
 597   }
 598
 599   return NULL;
 600 }
 601
 602 static gchar *
 603 gst_value_mini_object_lcopy (const GValue * value, guint n_collect_values,
 604     GTypeCValue * collect_values, guint collect_flags)
 605 {
 606   gpointer *mini_object_p = collect_values[0].v_pointer;
 607
 608   if (!mini_object_p) {
 609     return g_strdup_printf ("value location for '%s' passed as NULL",
 610         G_VALUE_TYPE_NAME (value));
 611   }
 612
 613   if (!value->data[0].v_pointer)
 614     *mini_object_p = NULL;
 615   else if (collect_flags & G_VALUE_NOCOPY_CONTENTS)
 616     *mini_object_p = value->data[0].v_pointer;
 617   else
 618     *mini_object_p = gst_mini_object_ref (value->data[0].v_pointer);
 619
 620   return NULL;
 621 }
 622
 623 /**
 624  * gst_value_set_mini_object:
 625  * @value: a valid #GValue of %GST_TYPE_MINI_OBJECT derived type
 626  * @mini_object: (transfer none): mini object value to set
 627  *
 628  * Set the contents of a %GST_TYPE_MINI_OBJECT derived #GValue to
 629  * @mini_object.
 630  * The caller retains ownership of the reference.
 631  */
 632 void
 633 gst_value_set_mini_object (GValue * value, GstMiniObject * mini_object)
 634 {
 635   gpointer *pointer_p;
 636
 637   g_return_if_fail (GST_VALUE_HOLDS_MINI_OBJECT (value));
 638   g_return_if_fail (mini_object == NULL || GST_IS_MINI_OBJECT (mini_object));
 639
 640   pointer_p = &value->data[0].v_pointer;
 641   gst_mini_object_replace ((GstMiniObject **) pointer_p, mini_object);
 642 }
 643
 644 /**
 645  * gst_value_take_mini_object:
 646  * @value: a valid #GValue of %GST_TYPE_MINI_OBJECT derived type
 647  * @mini_object: (transfer full): mini object value to take
 648  *
 649  * Set the contents of a %GST_TYPE_MINI_OBJECT derived #GValue to
 650  * @mini_object.
 651  * Takes over the ownership of the caller's reference to @mini_object;
 652  * the caller doesn't have to unref it any more.
 653  */
 654 void
 655 gst_value_take_mini_object (GValue * value, GstMiniObject * mini_object)
 656 {
 657   gpointer *pointer_p;
 658
 659   g_return_if_fail (GST_VALUE_HOLDS_MINI_OBJECT (value));
 660   g_return_if_fail (mini_object == NULL || GST_IS_MINI_OBJECT (mini_object));
 661
 662   pointer_p = &value->data[0].v_pointer;
 663   /* takes additional refcount */
 664   gst_mini_object_replace ((GstMiniObject **) pointer_p, mini_object);
 665   /* remove additional refcount */
 666   if (mini_object)
 667     gst_mini_object_unref (mini_object);
 668 }
 669
 670 /**
 671  * gst_value_get_mini_object:
 672  * @value:   a valid #GValue of %GST_TYPE_MINI_OBJECT derived type
 673  *
 674  * Get the contents of a %GST_TYPE_MINI_OBJECT derived #GValue.
 675  * Does not increase the refcount of the returned object.
 676  *
 677  * Returns: (transfer none): mini object contents of @value
 678  */
 679 GstMiniObject *
 680 gst_value_get_mini_object (const GValue * value)
 681 {
 682   g_return_val_if_fail (GST_VALUE_HOLDS_MINI_OBJECT (value), NULL);
 683
 684   return value->data[0].v_pointer;
 685 }
 686
 687 /**
 688  * gst_value_dup_mini_object:
 689  * @value:   a valid #GValue of %GST_TYPE_MINI_OBJECT derived type
 690  *
 691  * Get the contents of a %GST_TYPE_MINI_OBJECT derived #GValue,
 692  * increasing its reference count. If the contents of the #GValue
 693  * are %NULL, %NULL will be returned.
 694  *
 695  * Returns: (transfer full): mini object contents of @value
 696  *
 697  * Since: 0.10.20
 698  */
 699 GstMiniObject *
 700 gst_value_dup_mini_object (const GValue * value)
 701 {
 702   g_return_val_if_fail (GST_VALUE_HOLDS_MINI_OBJECT (value), NULL);
 703
 704   return value->data[0].v_pointer ? gst_mini_object_ref (value->
 705       data[0].v_pointer) : NULL;
 706 }
 707
 708
 709 /* param spec */
 710
 711 static void
 712 param_mini_object_init (GParamSpec * pspec)
 713 {
 714   /* GParamSpecMiniObject *ospec = G_PARAM_SPEC_MINI_OBJECT (pspec); */
 715 }
 716
 717 static void
 718 param_mini_object_set_default (GParamSpec * pspec, GValue * value)
 719 {
 720   value->data[0].v_pointer = NULL;
 721 }
 722
 723 static gboolean
 724 param_mini_object_validate (GParamSpec * pspec, GValue * value)
 725 {
 726   GstMiniObject *mini_object = value->data[0].v_pointer;
 727   gboolean changed = FALSE;
 728
 729   if (mini_object
 730       && !g_value_type_compatible (G_OBJECT_TYPE (mini_object),
 731           pspec->value_type)) {
 732     gst_mini_object_unref (mini_object);
 733     value->data[0].v_pointer = NULL;
 734     changed = TRUE;
 735   }
 736
 737   return changed;
 738 }
 739
 740 static gint
 741 param_mini_object_values_cmp (GParamSpec * pspec,
 742     const GValue * value1, const GValue * value2)
 743 {
 744   guint8 *p1 = value1->data[0].v_pointer;
 745   guint8 *p2 = value2->data[0].v_pointer;
 746
 747   /* not much to compare here, try to at least provide stable lesser/greater result */
 748
 749   return p1 < p2 ? -1 : p1 > p2;
 750 }
 751
 752 GType
 753 gst_param_spec_mini_object_get_type (void)
 754 {
 755   static GType type;
 756
 757   if (G_UNLIKELY (type) == 0) {
 758     static const GParamSpecTypeInfo pspec_info = {
 759       sizeof (GstParamSpecMiniObject),  /* instance_size */
 760       16,                       /* n_preallocs */
 761       param_mini_object_init,   /* instance_init */
 762       G_TYPE_OBJECT,            /* value_type */
 763       NULL,                     /* finalize */
 764       param_mini_object_set_default,    /* value_set_default */
 765       param_mini_object_validate,       /* value_validate */
 766       param_mini_object_values_cmp,     /* values_cmp */
 767     };
 768     /* FIXME 0.11: Should really be GstParamSpecMiniObject */
 769     type = g_param_type_register_static ("GParamSpecMiniObject", &pspec_info);
 770   }
 771
 772   return type;
 773 }
 774
 775 /**
 776  * gst_param_spec_mini_object:
 777  * @name: the canonical name of the property
 778  * @nick: the nickname of the property
 779  * @blurb: a short description of the property
 780  * @object_type: the #GstMiniObject #GType for the property
 781  * @flags: a combination of #GParamFlags
 782  *
 783  * Creates a new #GParamSpec instance that hold #GstMiniObject references.
 784  *
 785  * Returns: (transfer full): a newly allocated #GParamSpec instance
 786  */
 787 GParamSpec *
 788 gst_param_spec_mini_object (const char *name, const char *nick,
 789     const char *blurb, GType object_type, GParamFlags flags)
 790 {
 791   GstParamSpecMiniObject *ospec;
 792
 793   g_return_val_if_fail (g_type_is_a (object_type, GST_TYPE_MINI_OBJECT), NULL);
 794
 795   ospec = g_param_spec_internal (GST_TYPE_PARAM_MINI_OBJECT,
 796       name, nick, blurb, flags);
 797   G_PARAM_SPEC (ospec)->value_type = object_type;
 798
 799   return G_PARAM_SPEC (ospec);
 800 }