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