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 simple structure that can be used to implement refcounted
  26  * types.
  27  *
  28  * Subclasses will include #GstMiniObject as the first member in their structure
  29  * and then call gst_mini_object_init() to initialize the #GstMiniObject fields.
  30  *
  31  * gst_mini_object_ref() and gst_mini_object_unref() increment and decrement the
  32  * refcount respectively. When the refcount of a mini-object reaches 0, the
  33  * dispose function is called first and when this returns %TRUE, the free
  34  * function of the miniobject is called.
  35  *
  36  * A copy can be made with gst_mini_object_copy().
  37  *
  38  * gst_mini_object_is_writable() will return %TRUE when the refcount of the
  39  * object is exactly 1, meaning the current caller has the only reference to the
  40  * object. gst_mini_object_make_writable() will return a writable version of the
  41  * object, which might be a new copy when the refcount was not 1.
  42  *
  43  * Opaque data can be associated with a #GstMiniObject with
  44  * gst_mini_object_set_qdata() and gst_mini_object_get_qdata(). The data is
  45  * meant to be specific to the particular object and is not automatically copied
  46  * with gst_mini_object_copy() or similar methods.
  47  *
  48  * A weak reference can be added and remove with gst_mini_object_weak_ref()
  49  * and gst_mini_object_weak_unref() respectively.
  50  *
  51  * Last reviewed on 2012-06-15 (0.11.93)
  52  */
  53 #ifdef HAVE_CONFIG_H
  54 #include "config.h"
  55 #endif
  56
  57 #include "gst/gst_private.h"
  58 #include "gst/gstminiobject.h"
  59 #include "gst/gstinfo.h"
  60 #include <gobject/gvaluecollector.h>
  61
  62 #ifndef GST_DISABLE_TRACE
  63 #include "gsttrace.h"
  64 static GstAllocTrace *_gst_mini_object_trace;
  65 #endif
  66
  67 /* Mutex used for weak referencing */
  68 G_LOCK_DEFINE_STATIC (qdata_mutex);
  69 static GQuark weak_ref_quark;
  70
  71 #define SHARE_ONE (1 << 16)
  72 #define SHARE_MASK (~(SHARE_ONE - 1))
  73 #define LOCK_ONE (GST_LOCK_FLAG_LAST)
  74 #define FLAG_MASK (GST_LOCK_FLAG_LAST - 1)
  75 #define LOCK_MASK ((SHARE_ONE - 1) - FLAG_MASK)
  76 #define LOCK_FLAG_MASK (SHARE_ONE - 1)
  77
  78 typedef struct
  79 {
  80   GQuark quark;
  81   GstMiniObjectNotify notify;
  82   gpointer data;
  83   GDestroyNotify destroy;
  84 } GstQData;
  85
  86 #define QDATA(o,i)          ((GstQData *)(o)->qdata)[(i)]
  87 #define QDATA_QUARK(o,i)    (QDATA(o,i).quark)
  88 #define QDATA_NOTIFY(o,i)   (QDATA(o,i).notify)
  89 #define QDATA_DATA(o,i)     (QDATA(o,i).data)
  90 #define QDATA_DESTROY(o,i)  (QDATA(o,i).destroy)
  91
  92 void
  93 _priv_gst_mini_object_initialize (void)
  94 {
  95   weak_ref_quark = g_quark_from_static_string ("GstMiniObjectWeakRefQuark");
  96
  97 #ifndef GST_DISABLE_TRACE
  98   _gst_mini_object_trace = _gst_alloc_trace_register ("GstMiniObject", 0);
  99 #endif
 100 }
 101
 102 /**
 103  * gst_mini_object_init: (skip)
 104  * @mini_object: a #GstMiniObject
 105  * @type: the #GType of the mini-object to create
 106  * @copy_func: the copy function, or NULL
 107  * @dispose_func: the dispose function, or NULL
 108  * @free_func: the free function or NULL
 109  *
 110  * Initializes a mini-object with the desired type and copy/dispose/free
 111  * functions.
 112  */
 113 void
 114 gst_mini_object_init (GstMiniObject * mini_object, guint flags, GType type,
 115     GstMiniObjectCopyFunction copy_func,
 116     GstMiniObjectDisposeFunction dispose_func,
 117     GstMiniObjectFreeFunction free_func)
 118 {
 119   mini_object->type = type;
 120   mini_object->refcount = 1;
 121   mini_object->lockstate =
 122       (flags & GST_MINI_OBJECT_FLAG_LOCK_READONLY ? GST_LOCK_FLAG_READ : 0);
 123   mini_object->flags = flags;
 124
 125   mini_object->copy = copy_func;
 126   mini_object->dispose = dispose_func;
 127   mini_object->free = free_func;
 128
 129   mini_object->n_qdata = 0;
 130   mini_object->qdata = NULL;
 131
 132 #ifndef GST_DISABLE_TRACE
 133   _gst_alloc_trace_new (_gst_mini_object_trace, mini_object);
 134 #endif
 135 }
 136
 137 /**
 138  * gst_mini_object_copy:
 139  * @mini_object: the mini-object to copy
 140  *
 141  * Creates a copy of the mini-object.
 142  *
 143  * MT safe
 144  *
 145  * Returns: (transfer full): the new mini-object.
 146  */
 147 GstMiniObject *
 148 gst_mini_object_copy (const GstMiniObject * mini_object)
 149 {
 150   GstMiniObject *copy;
 151
 152   g_return_val_if_fail (mini_object != NULL, NULL);
 153
 154   if (mini_object->copy)
 155     copy = mini_object->copy (mini_object);
 156   else
 157     copy = NULL;
 158
 159   return copy;
 160 }
 161
 162 /**
 163  * gst_mini_object_lock:
 164  * @object: the mini-object to lock
 165  * @flags: #GstLockFlags
 166  *
 167  * Lock the mini-object with the specified access mode in @flags.
 168  *
 169  * Returns: %TRUE if @object could be locked.
 170  */
 171 gboolean
 172 gst_mini_object_lock (GstMiniObject * object, GstLockFlags flags)
 173 {
 174   gint access_mode, state, newstate;
 175
 176   g_return_val_if_fail (object != NULL, FALSE);
 177   g_return_val_if_fail (GST_MINI_OBJECT_IS_LOCKABLE (object), FALSE);
 178
 179   do {
 180     access_mode = flags & FLAG_MASK;
 181     newstate = state = g_atomic_int_get (&object->lockstate);
 182
 183     GST_CAT_TRACE (GST_CAT_LOCKING, "lock %p: state %08x, access_mode %d",
 184         object, state, access_mode);
 185
 186     if (access_mode & GST_LOCK_FLAG_EXCLUSIVE) {
 187       /* shared ref */
 188       newstate += SHARE_ONE;
 189       access_mode &= ~GST_LOCK_FLAG_EXCLUSIVE;
 190     }
 191
 192     if (access_mode) {
 193       /* shared counter > 1 and write access is not allowed */
 194       if (state > SHARE_ONE && access_mode & GST_LOCK_FLAG_WRITE)
 195         goto lock_failed;
 196
 197       if ((state & LOCK_FLAG_MASK) == 0) {
 198         /* nothing mapped, set access_mode */
 199         newstate |= access_mode;
 200       } else {
 201         /* access_mode must match */
 202         if ((state & access_mode) != access_mode)
 203           goto lock_failed;
 204       }
 205       /* increase refcount */
 206       newstate += LOCK_ONE;
 207     }
 208   } while (!g_atomic_int_compare_and_exchange (&object->lockstate, state,
 209           newstate));
 210
 211   return TRUE;
 212
 213 lock_failed:
 214   {
 215     GST_CAT_DEBUG (GST_CAT_LOCKING,
 216         "lock failed %p: state %08x, access_mode %d", object, state,
 217         access_mode);
 218     return FALSE;
 219   }
 220 }
 221
 222 /**
 223  * gst_mini_object_unlock:
 224  * @object: the mini-object to unlock
 225  * @flags: #GstLockFlags
 226  *
 227  * Unlock the mini-object with the specified access mode in @flags.
 228  */
 229 void
 230 gst_mini_object_unlock (GstMiniObject * object, GstLockFlags flags)
 231 {
 232   gint access_mode, state, newstate;
 233
 234   g_return_if_fail (object != NULL);
 235   g_return_if_fail (GST_MINI_OBJECT_IS_LOCKABLE (object));
 236
 237   do {
 238     access_mode = flags & FLAG_MASK;
 239     newstate = state = g_atomic_int_get (&object->lockstate);
 240
 241     GST_CAT_TRACE (GST_CAT_LOCKING, "unlock %p: state %08x, access_mode %d",
 242         object, state, access_mode);
 243
 244     if (access_mode & GST_LOCK_FLAG_EXCLUSIVE) {
 245       /* shared counter */
 246       g_return_if_fail (state >= SHARE_ONE);
 247       newstate -= SHARE_ONE;
 248       access_mode &= ~GST_LOCK_FLAG_EXCLUSIVE;
 249     }
 250
 251     if (access_mode) {
 252       g_return_if_fail ((state & access_mode) == access_mode);
 253       /* decrease the refcount */
 254       newstate -= LOCK_ONE;
 255       /* last refcount, unset access_mode */
 256       if ((newstate & LOCK_FLAG_MASK) == access_mode)
 257         newstate &= ~LOCK_FLAG_MASK;
 258     }
 259   } while (!g_atomic_int_compare_and_exchange (&object->lockstate, state,
 260           newstate));
 261 }
 262
 263 /**
 264  * gst_mini_object_is_writable:
 265  * @mini_object: the mini-object to check
 266  *
 267  * If @mini_object has the LOCKABLE flag set, check if the current EXCLUSIVE
 268  * lock on @object is the only one, this means that changes to the object will
 269  * not be visible to any other object.
 270  *
 271  * If the LOCKABLE flag is not set, check if the refcount of @mini_object is
 272  * exactly 1, meaning that no other reference exists to the object and that the
 273  * object is therefore writable.
 274  *
 275  * Modification of a mini-object should only be done after verifying that it
 276  * is writable.
 277  *
 278  * Returns: TRUE if the object is writable.
 279  */
 280 gboolean
 281 gst_mini_object_is_writable (const GstMiniObject * mini_object)
 282 {
 283   gboolean result;
 284
 285   g_return_val_if_fail (mini_object != NULL, FALSE);
 286
 287   if (GST_MINI_OBJECT_IS_LOCKABLE (mini_object)) {
 288     result = (g_atomic_int_get (&mini_object->lockstate) & SHARE_MASK) < 2;
 289   } else {
 290     result = (GST_MINI_OBJECT_REFCOUNT_VALUE (mini_object) == 1);
 291   }
 292   return result;
 293 }
 294
 295 /**
 296  * gst_mini_object_make_writable:
 297  * @mini_object: (transfer full): the mini-object to make writable
 298  *
 299  * Checks if a mini-object is writable.  If not, a writable copy is made and
 300  * returned.  This gives away the reference to the original mini object,
 301  * and returns a reference to the new object.
 302  *
 303  * MT safe
 304  *
 305  * Returns: (transfer full): a mini-object (possibly the same pointer) that
 306  *     is writable.
 307  */
 308 GstMiniObject *
 309 gst_mini_object_make_writable (GstMiniObject * mini_object)
 310 {
 311   GstMiniObject *ret;
 312
 313   g_return_val_if_fail (mini_object != NULL, NULL);
 314
 315   if (gst_mini_object_is_writable (mini_object)) {
 316     ret = mini_object;
 317   } else {
 318     ret = gst_mini_object_copy (mini_object);
 319     GST_CAT_DEBUG (GST_CAT_PERFORMANCE, "copy %s miniobject %p -> %p",
 320         g_type_name (GST_MINI_OBJECT_TYPE (mini_object)), mini_object, ret);
 321     gst_mini_object_unref (mini_object);
 322   }
 323
 324   return ret;
 325 }
 326
 327 /**
 328  * gst_mini_object_ref:
 329  * @mini_object: the mini-object
 330  *
 331  * Increase the reference count of the mini-object.
 332  *
 333  * Note that the refcount affects the writeability
 334  * of @mini-object, see gst_mini_object_is_writable(). It is
 335  * important to note that keeping additional references to
 336  * GstMiniObject instances can potentially increase the number
 337  * of memcpy operations in a pipeline, especially if the miniobject
 338  * is a #GstBuffer.
 339  *
 340  * Returns: (transfer full): the mini-object.
 341  */
 342 GstMiniObject *
 343 gst_mini_object_ref (GstMiniObject * mini_object)
 344 {
 345   g_return_val_if_fail (mini_object != NULL, NULL);
 346   /* we can't assert that the refcount > 0 since the _free functions
 347    * increments the refcount from 0 to 1 again to allow resurecting
 348    * the object
 349    g_return_val_if_fail (mini_object->refcount > 0, NULL);
 350    */
 351
 352   GST_CAT_TRACE (GST_CAT_REFCOUNTING, "%p ref %d->%d", mini_object,
 353       GST_MINI_OBJECT_REFCOUNT_VALUE (mini_object),
 354       GST_MINI_OBJECT_REFCOUNT_VALUE (mini_object) + 1);
 355
 356   g_atomic_int_inc (&mini_object->refcount);
 357
 358   return mini_object;
 359 }
 360
 361 static gint
 362 find_notify (GstMiniObject * object, GQuark quark, gboolean match_notify,
 363     GstMiniObjectNotify notify, gpointer data)
 364 {
 365   guint i;
 366
 367   for (i = 0; i < object->n_qdata; i++) {
 368     if (QDATA_QUARK (object, i) == quark) {
 369       /* check if we need to match the callback too */
 370       if (!match_notify || (QDATA_NOTIFY (object, i) == notify &&
 371               QDATA_DATA (object, i) == data))
 372         return i;
 373     }
 374   }
 375   return -1;
 376 }
 377
 378 static void
 379 remove_notify (GstMiniObject * object, gint index)
 380 {
 381   /* remove item */
 382   if (--object->n_qdata == 0) {
 383     /* we don't shrink but free when everything is gone */
 384     g_free (object->qdata);
 385     object->qdata = NULL;
 386   } else if (index != object->n_qdata)
 387     QDATA (object, index) = QDATA (object, object->n_qdata);
 388 }
 389
 390 static void
 391 set_notify (GstMiniObject * object, gint index, GQuark quark,
 392     GstMiniObjectNotify notify, gpointer data, GDestroyNotify destroy)
 393 {
 394   if (index == -1) {
 395     /* add item */
 396     index = object->n_qdata++;
 397     object->qdata =
 398         g_realloc (object->qdata, sizeof (GstQData) * object->n_qdata);
 399   }
 400   QDATA_QUARK (object, index) = quark;
 401   QDATA_NOTIFY (object, index) = notify;
 402   QDATA_DATA (object, index) = data;
 403   QDATA_DESTROY (object, index) = destroy;
 404 }
 405
 406 static void
 407 call_finalize_notify (GstMiniObject * obj)
 408 {
 409   guint i;
 410
 411   for (i = 0; i < obj->n_qdata; i++) {
 412     if (QDATA_QUARK (obj, i) == weak_ref_quark)
 413       QDATA_NOTIFY (obj, i) (QDATA_DATA (obj, i), obj);
 414     if (QDATA_DESTROY (obj, i))
 415       QDATA_DESTROY (obj, i) (QDATA_DATA (obj, i));
 416   }
 417 }
 418
 419 /**
 420  * gst_mini_object_unref:
 421  * @mini_object: the mini-object
 422  *
 423  * Decreases the reference count of the mini-object, possibly freeing
 424  * the mini-object.
 425  */
 426 void
 427 gst_mini_object_unref (GstMiniObject * mini_object)
 428 {
 429   g_return_if_fail (mini_object != NULL);
 430
 431   GST_CAT_TRACE (GST_CAT_REFCOUNTING, "%p unref %d->%d",
 432       mini_object,
 433       GST_MINI_OBJECT_REFCOUNT_VALUE (mini_object),
 434       GST_MINI_OBJECT_REFCOUNT_VALUE (mini_object) - 1);
 435
 436   g_return_if_fail (mini_object->refcount > 0);
 437
 438   if (G_UNLIKELY (g_atomic_int_dec_and_test (&mini_object->refcount))) {
 439     gboolean do_free;
 440
 441     if (mini_object->dispose)
 442       do_free = mini_object->dispose (mini_object);
 443     else
 444       do_free = TRUE;
 445
 446     /* if the subclass recycled the object (and returned FALSE) we don't
 447      * want to free the instance anymore */
 448     if (G_LIKELY (do_free)) {
 449       /* there should be no outstanding locks */
 450       g_return_if_fail ((g_atomic_int_get (&mini_object->lockstate) & LOCK_MASK)
 451           < 4);
 452
 453       if (mini_object->n_qdata) {
 454         call_finalize_notify (mini_object);
 455         g_free (mini_object->qdata);
 456       }
 457 #ifndef GST_DISABLE_TRACE
 458       _gst_alloc_trace_free (_gst_mini_object_trace, mini_object);
 459 #endif
 460       if (mini_object->free)
 461         mini_object->free (mini_object);
 462     }
 463   }
 464 }
 465
 466 /**
 467  * gst_mini_object_replace:
 468  * @olddata: (inout) (transfer full): pointer to a pointer to a mini-object to
 469  *     be replaced
 470  * @newdata: pointer to new mini-object
 471  *
 472  * Atomically modifies a pointer to point to a new mini-object.
 473  * The reference count of @olddata is decreased and the reference count of
 474  * @newdata is increased.
 475  *
 476  * Either @newdata and the value pointed to by @olddata may be NULL.
 477  *
 478  * Returns: TRUE if @newdata was different from @olddata
 479  */
 480 gboolean
 481 gst_mini_object_replace (GstMiniObject ** olddata, GstMiniObject * newdata)
 482 {
 483   GstMiniObject *olddata_val;
 484
 485   g_return_val_if_fail (olddata != NULL, FALSE);
 486
 487   GST_CAT_TRACE (GST_CAT_REFCOUNTING, "replace %p (%d) with %p (%d)",
 488       *olddata, *olddata ? (*olddata)->refcount : 0,
 489       newdata, newdata ? newdata->refcount : 0);
 490
 491   olddata_val = g_atomic_pointer_get ((gpointer *) olddata);
 492
 493   if (G_UNLIKELY (olddata_val == newdata))
 494     return FALSE;
 495
 496   if (newdata)
 497     gst_mini_object_ref (newdata);
 498
 499   while (G_UNLIKELY (!g_atomic_pointer_compare_and_exchange ((gpointer *)
 500               olddata, olddata_val, newdata))) {
 501     olddata_val = g_atomic_pointer_get ((gpointer *) olddata);
 502     if (G_UNLIKELY (olddata_val == newdata))
 503       break;
 504   }
 505
 506   if (olddata_val)
 507     gst_mini_object_unref (olddata_val);
 508
 509   return olddata_val != newdata;
 510 }
 511
 512 /**
 513  * gst_mini_object_steal:
 514  * @olddata: (inout) (transfer full): pointer to a pointer to a mini-object to
 515  *     be stolen
 516  *
 517  * Replace the current #GstMiniObject pointer to by @olddata with NULL and
 518  * return the old value.
 519  *
 520  * Returns: the #GstMiniObject at @oldata
 521  */
 522 GstMiniObject *
 523 gst_mini_object_steal (GstMiniObject ** olddata)
 524 {
 525   GstMiniObject *olddata_val;
 526
 527   g_return_val_if_fail (olddata != NULL, NULL);
 528
 529   GST_CAT_TRACE (GST_CAT_REFCOUNTING, "steal %p (%d)",
 530       *olddata, *olddata ? (*olddata)->refcount : 0);
 531
 532   do {
 533     olddata_val = g_atomic_pointer_get ((gpointer *) olddata);
 534     if (olddata_val == NULL)
 535       break;
 536   } while (G_UNLIKELY (!g_atomic_pointer_compare_and_exchange ((gpointer *)
 537               olddata, olddata_val, NULL)));
 538
 539   return olddata_val;
 540 }
 541
 542 /**
 543  * gst_mini_object_take:
 544  * @olddata: (inout) (transfer full): pointer to a pointer to a mini-object to
 545  *     be replaced
 546  * @newdata: pointer to new mini-object
 547  *
 548  * Modifies a pointer to point to a new mini-object. The modification
 549  * is done atomically. This version is similar to gst_mini_object_replace()
 550  * except that it does not increase the refcount of @newdata and thus
 551  * takes ownership of @newdata.
 552  *
 553  * Either @newdata and the value pointed to by @olddata may be NULL.
 554  *
 555  * Returns: TRUE if @newdata was different from @olddata
 556  */
 557 gboolean
 558 gst_mini_object_take (GstMiniObject ** olddata, GstMiniObject * newdata)
 559 {
 560   GstMiniObject *olddata_val;
 561
 562   g_return_val_if_fail (olddata != NULL, FALSE);
 563
 564   GST_CAT_TRACE (GST_CAT_REFCOUNTING, "take %p (%d) with %p (%d)",
 565       *olddata, *olddata ? (*olddata)->refcount : 0,
 566       newdata, newdata ? newdata->refcount : 0);
 567
 568   do {
 569     olddata_val = g_atomic_pointer_get ((gpointer *) olddata);
 570     if (G_UNLIKELY (olddata_val == newdata))
 571       break;
 572   } while (G_UNLIKELY (!g_atomic_pointer_compare_and_exchange ((gpointer *)
 573               olddata, olddata_val, newdata)));
 574
 575   if (olddata_val)
 576     gst_mini_object_unref (olddata_val);
 577
 578   return olddata_val != newdata;
 579 }
 580
 581 /**
 582  * gst_mini_object_weak_ref: (skip)
 583  * @object: #GstMiniObject to reference weakly
 584  * @notify: callback to invoke before the mini object is freed
 585  * @data: extra data to pass to notify
 586  *
 587  * Adds a weak reference callback to a mini object. Weak references are
 588  * used for notification when a mini object is finalized. They are called
 589  * "weak references" because they allow you to safely hold a pointer
 590  * to the mini object without calling gst_mini_object_ref()
 591  * (gst_mini_object_ref() adds a strong reference, that is, forces the object
 592  * to stay alive).
 593  */
 594 void
 595 gst_mini_object_weak_ref (GstMiniObject * object,
 596     GstMiniObjectNotify notify, gpointer data)
 597 {
 598   g_return_if_fail (object != NULL);
 599   g_return_if_fail (notify != NULL);
 600   g_return_if_fail (GST_MINI_OBJECT_REFCOUNT_VALUE (object) >= 1);
 601
 602   G_LOCK (qdata_mutex);
 603   set_notify (object, -1, weak_ref_quark, notify, data, NULL);
 604   G_UNLOCK (qdata_mutex);
 605 }
 606
 607 /**
 608  * gst_mini_object_weak_unref: (skip)
 609  * @object: #GstMiniObject to remove a weak reference from
 610  * @notify: callback to search for
 611  * @data: data to search for
 612  *
 613  * Removes a weak reference callback from a mini object.
 614  */
 615 void
 616 gst_mini_object_weak_unref (GstMiniObject * object,
 617     GstMiniObjectNotify notify, gpointer data)
 618 {
 619   gint i;
 620
 621   g_return_if_fail (object != NULL);
 622   g_return_if_fail (notify != NULL);
 623
 624   G_LOCK (qdata_mutex);
 625   if ((i = find_notify (object, weak_ref_quark, TRUE, notify, data)) != -1) {
 626     remove_notify (object, i);
 627   } else {
 628     g_warning ("%s: couldn't find weak ref %p(%p)", G_STRFUNC, notify, data);
 629   }
 630   G_UNLOCK (qdata_mutex);
 631 }
 632
 633 /**
 634  * gst_mini_object_set_qdata:
 635  * @object: a #GstMiniObject
 636  * @quark: A #GQuark, naming the user data pointer
 637  * @data: An opaque user data pointer
 638  * @destroy: Function to invoke with @data as argument, when @data
 639  *           needs to be freed
 640  *
 641  * This sets an opaque, named pointer on a miniobject.
 642  * The name is specified through a #GQuark (retrived e.g. via
 643  * g_quark_from_static_string()), and the pointer
 644  * can be gotten back from the @object with gst_mini_object_get_qdata()
 645  * until the @object is disposed.
 646  * Setting a previously set user data pointer, overrides (frees)
 647  * the old pointer set, using #NULL as pointer essentially
 648  * removes the data stored.
 649  *
 650  * @destroy may be specified which is called with @data as argument
 651  * when the @object is disposed, or the data is being overwritten by
 652  * a call to gst_mini_object_set_qdata() with the same @quark.
 653  */
 654 void
 655 gst_mini_object_set_qdata (GstMiniObject * object, GQuark quark,
 656     gpointer data, GDestroyNotify destroy)
 657 {
 658   gint i;
 659   gpointer old_data = NULL;
 660   GDestroyNotify old_notify = NULL;
 661
 662   g_return_if_fail (object != NULL);
 663   g_return_if_fail (quark > 0);
 664
 665   G_LOCK (qdata_mutex);
 666   if ((i = find_notify (object, quark, FALSE, NULL, NULL)) != -1) {
 667
 668     old_data = QDATA_DATA (object, i);
 669     old_notify = QDATA_DESTROY (object, i);
 670
 671     if (data == NULL)
 672       remove_notify (object, i);
 673   }
 674   if (data != NULL)
 675     set_notify (object, i, quark, NULL, data, destroy);
 676   G_UNLOCK (qdata_mutex);
 677
 678   if (old_notify)
 679     old_notify (old_data);
 680 }
 681
 682 /**
 683  * gst_mini_object_get_qdata:
 684  * @object: The GstMiniObject to get a stored user data pointer from
 685  * @quark: A #GQuark, naming the user data pointer
 686  *
 687  * This function gets back user data pointers stored via
 688  * gst_mini_object_set_qdata().
 689  *
 690  * Returns: (transfer none): The user data pointer set, or %NULL
 691  */
 692 gpointer
 693 gst_mini_object_get_qdata (GstMiniObject * object, GQuark quark)
 694 {
 695   guint i;
 696   gpointer result;
 697
 698   g_return_val_if_fail (object != NULL, NULL);
 699   g_return_val_if_fail (quark > 0, NULL);
 700
 701   G_LOCK (qdata_mutex);
 702   if ((i = find_notify (object, quark, FALSE, NULL, NULL)) != -1)
 703     result = QDATA_DATA (object, i);
 704   else
 705     result = NULL;
 706   G_UNLOCK (qdata_mutex);
 707
 708   return result;
 709 }
 710
 711 /**
 712  * gst_mini_object_steal_qdata:
 713  * @object: The GstMiniObject to get a stored user data pointer from
 714  * @quark: A #GQuark, naming the user data pointer
 715  *
 716  * This function gets back user data pointers stored via gst_mini_object_set_qdata()
 717  * and removes the data from @object without invoking its destroy() function (if
 718  * any was set).
 719  *
 720  * Returns: (transfer full): The user data pointer set, or %NULL
 721  */
 722 gpointer
 723 gst_mini_object_steal_qdata (GstMiniObject * object, GQuark quark)
 724 {
 725   guint i;
 726   gpointer result;
 727
 728   g_return_val_if_fail (object != NULL, NULL);
 729   g_return_val_if_fail (quark > 0, NULL);
 730
 731   G_LOCK (qdata_mutex);
 732   if ((i = find_notify (object, quark, FALSE, NULL, NULL)) != -1) {
 733     result = QDATA_DATA (object, i);
 734     remove_notify (object, i);
 735   } else {
 736     result = NULL;
 737   }
 738   G_UNLOCK (qdata_mutex);
 739
 740   return result;
 741 }