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       if ((state & LOCK_FLAG_MASK) == 0) {
 194         /* shared counter > 1 and write access */
 195         if (state > SHARE_ONE && access_mode & GST_LOCK_FLAG_WRITE)
 196           goto lock_failed;
 197         /* nothing mapped, set access_mode */
 198         newstate |= access_mode;
 199       } else {
 200         /* access_mode must match */
 201         if ((state & access_mode) != access_mode)
 202           goto lock_failed;
 203       }
 204       /* increase refcount */
 205       newstate += LOCK_ONE;
 206     }
 207   } while (!g_atomic_int_compare_and_exchange (&object->lockstate, state,
 208           newstate));
 209
 210   return TRUE;
 211
 212 lock_failed:
 213   {
 214     GST_CAT_DEBUG (GST_CAT_LOCKING,
 215         "lock failed %p: state %08x, access_mode %d", object, state,
 216         access_mode);
 217     return FALSE;
 218   }
 219 }
 220
 221 /**
 222  * gst_mini_object_unlock:
 223  * @object: the mini-object to unlock
 224  * @flags: #GstLockFlags
 225  *
 226  * Unlock the mini-object with the specified access mode in @flags.
 227  */
 228 void
 229 gst_mini_object_unlock (GstMiniObject * object, GstLockFlags flags)
 230 {
 231   gint access_mode, state, newstate;
 232
 233   g_return_if_fail (object != NULL);
 234   g_return_if_fail (GST_MINI_OBJECT_IS_LOCKABLE (object));
 235
 236   do {
 237     access_mode = flags & FLAG_MASK;
 238     newstate = state = g_atomic_int_get (&object->lockstate);
 239
 240     GST_CAT_TRACE (GST_CAT_LOCKING, "unlock %p: state %08x, access_mode %d",
 241         object, state, access_mode);
 242
 243     if (access_mode & GST_LOCK_FLAG_EXCLUSIVE) {
 244       /* shared counter */
 245       g_return_if_fail (state >= SHARE_ONE);
 246       newstate -= SHARE_ONE;
 247       access_mode &= ~GST_LOCK_FLAG_EXCLUSIVE;
 248     }
 249
 250     if (access_mode) {
 251       g_return_if_fail ((state & access_mode) == access_mode);
 252       /* decrease the refcount */
 253       newstate -= LOCK_ONE;
 254       /* last refcount, unset access_mode */
 255       if ((newstate & LOCK_FLAG_MASK) == access_mode)
 256         newstate &= ~LOCK_FLAG_MASK;
 257     }
 258   } while (!g_atomic_int_compare_and_exchange (&object->lockstate, state,
 259           newstate));
 260 }
 261
 262 /**
 263  * gst_mini_object_is_writable:
 264  * @mini_object: the mini-object to check
 265  *
 266  * If @mini_object has the LOCKABLE flag set, check if the current EXCLUSIVE
 267  * lock on @object is the only one, this means that changes to the object will
 268  * not be visible to any other object.
 269  *
 270  * If the LOCKABLE flag is not set, check if the refcount of @mini_object is
 271  * exactly 1, meaning that no other reference exists to the object and that the
 272  * object is therefore writable.
 273  *
 274  * Modification of a mini-object should only be done after verifying that it
 275  * is writable.
 276  *
 277  * Returns: TRUE if the object is writable.
 278  */
 279 gboolean
 280 gst_mini_object_is_writable (const GstMiniObject * mini_object)
 281 {
 282   gboolean result;
 283
 284   g_return_val_if_fail (mini_object != NULL, FALSE);
 285
 286   if (GST_MINI_OBJECT_IS_LOCKABLE (mini_object)) {
 287     result = (g_atomic_int_get (&mini_object->lockstate) & SHARE_MASK) < 2;
 288   } else {
 289     result = (GST_MINI_OBJECT_REFCOUNT_VALUE (mini_object) == 1);
 290   }
 291   return result;
 292 }
 293
 294 /**
 295  * gst_mini_object_make_writable:
 296  * @mini_object: (transfer full): the mini-object to make writable
 297  *
 298  * Checks if a mini-object is writable.  If not, a writable copy is made and
 299  * returned.  This gives away the reference to the original mini object,
 300  * and returns a reference to the new object.
 301  *
 302  * MT safe
 303  *
 304  * Returns: (transfer full): a mini-object (possibly the same pointer) that
 305  *     is writable.
 306  */
 307 GstMiniObject *
 308 gst_mini_object_make_writable (GstMiniObject * mini_object)
 309 {
 310   GstMiniObject *ret;
 311
 312   g_return_val_if_fail (mini_object != NULL, NULL);
 313
 314   if (gst_mini_object_is_writable (mini_object)) {
 315     ret = mini_object;
 316   } else {
 317     ret = gst_mini_object_copy (mini_object);
 318     GST_CAT_DEBUG (GST_CAT_PERFORMANCE, "copy %s miniobject %p -> %p",
 319         g_type_name (GST_MINI_OBJECT_TYPE (mini_object)), mini_object, ret);
 320     gst_mini_object_unref (mini_object);
 321   }
 322
 323   return ret;
 324 }
 325
 326 /**
 327  * gst_mini_object_ref:
 328  * @mini_object: the mini-object
 329  *
 330  * Increase the reference count of the mini-object.
 331  *
 332  * Note that the refcount affects the writeability
 333  * of @mini-object, see gst_mini_object_is_writable(). It is
 334  * important to note that keeping additional references to
 335  * GstMiniObject instances can potentially increase the number
 336  * of memcpy operations in a pipeline, especially if the miniobject
 337  * is a #GstBuffer.
 338  *
 339  * Returns: (transfer full): the mini-object.
 340  */
 341 GstMiniObject *
 342 gst_mini_object_ref (GstMiniObject * mini_object)
 343 {
 344   g_return_val_if_fail (mini_object != NULL, NULL);
 345   /* we can't assert that the refcount > 0 since the _free functions
 346    * increments the refcount from 0 to 1 again to allow resurecting
 347    * the object
 348    g_return_val_if_fail (mini_object->refcount > 0, NULL);
 349    */
 350
 351   GST_CAT_TRACE (GST_CAT_REFCOUNTING, "%p ref %d->%d", mini_object,
 352       GST_MINI_OBJECT_REFCOUNT_VALUE (mini_object),
 353       GST_MINI_OBJECT_REFCOUNT_VALUE (mini_object) + 1);
 354
 355   g_atomic_int_inc (&mini_object->refcount);
 356
 357   return mini_object;
 358 }
 359
 360 static gint
 361 find_notify (GstMiniObject * object, GQuark quark, gboolean match_notify,
 362     GstMiniObjectNotify notify, gpointer data)
 363 {
 364   guint i;
 365
 366   for (i = 0; i < object->n_qdata; i++) {
 367     if (QDATA_QUARK (object, i) == quark) {
 368       /* check if we need to match the callback too */
 369       if (!match_notify || (QDATA_NOTIFY (object, i) == notify &&
 370               QDATA_DATA (object, i) == data))
 371         return i;
 372     }
 373   }
 374   return -1;
 375 }
 376
 377 static void
 378 remove_notify (GstMiniObject * object, gint index)
 379 {
 380   /* remove item */
 381   if (--object->n_qdata == 0) {
 382     /* we don't shrink but free when everything is gone */
 383     g_free (object->qdata);
 384     object->qdata = NULL;
 385   } else if (index != object->n_qdata)
 386     QDATA (object, index) = QDATA (object, object->n_qdata);
 387 }
 388
 389 static void
 390 set_notify (GstMiniObject * object, gint index, GQuark quark,
 391     GstMiniObjectNotify notify, gpointer data, GDestroyNotify destroy)
 392 {
 393   if (index == -1) {
 394     /* add item */
 395     index = object->n_qdata++;
 396     object->qdata =
 397         g_realloc (object->qdata, sizeof (GstQData) * object->n_qdata);
 398   }
 399   QDATA_QUARK (object, index) = quark;
 400   QDATA_NOTIFY (object, index) = notify;
 401   QDATA_DATA (object, index) = data;
 402   QDATA_DESTROY (object, index) = destroy;
 403 }
 404
 405 static void
 406 call_finalize_notify (GstMiniObject * obj)
 407 {
 408   guint i;
 409
 410   for (i = 0; i < obj->n_qdata; i++) {
 411     if (QDATA_QUARK (obj, i) == weak_ref_quark)
 412       QDATA_NOTIFY (obj, i) (QDATA_DATA (obj, i), obj);
 413     if (QDATA_DESTROY (obj, i))
 414       QDATA_DESTROY (obj, i) (QDATA_DATA (obj, i));
 415   }
 416 }
 417
 418 /**
 419  * gst_mini_object_unref:
 420  * @mini_object: the mini-object
 421  *
 422  * Decreases the reference count of the mini-object, possibly freeing
 423  * the mini-object.
 424  */
 425 void
 426 gst_mini_object_unref (GstMiniObject * mini_object)
 427 {
 428   g_return_if_fail (mini_object != NULL);
 429
 430   GST_CAT_TRACE (GST_CAT_REFCOUNTING, "%p unref %d->%d",
 431       mini_object,
 432       GST_MINI_OBJECT_REFCOUNT_VALUE (mini_object),
 433       GST_MINI_OBJECT_REFCOUNT_VALUE (mini_object) - 1);
 434
 435   g_return_if_fail (mini_object->refcount > 0);
 436
 437   if (G_UNLIKELY (g_atomic_int_dec_and_test (&mini_object->refcount))) {
 438     gboolean do_free;
 439
 440     if (mini_object->dispose)
 441       do_free = mini_object->dispose (mini_object);
 442     else
 443       do_free = TRUE;
 444
 445     /* if the subclass recycled the object (and returned FALSE) we don't
 446      * want to free the instance anymore */
 447     if (G_LIKELY (do_free)) {
 448       /* there should be no outstanding locks */
 449       g_return_if_fail ((g_atomic_int_get (&mini_object->lockstate) & LOCK_MASK)
 450           < 4);
 451
 452       if (mini_object->n_qdata) {
 453         call_finalize_notify (mini_object);
 454         g_free (mini_object->qdata);
 455       }
 456 #ifndef GST_DISABLE_TRACE
 457       _gst_alloc_trace_free (_gst_mini_object_trace, mini_object);
 458 #endif
 459       if (mini_object->free)
 460         mini_object->free (mini_object);
 461     }
 462   }
 463 }
 464
 465 /**
 466  * gst_mini_object_replace:
 467  * @olddata: (inout) (transfer full): pointer to a pointer to a mini-object to
 468  *     be replaced
 469  * @newdata: pointer to new mini-object
 470  *
 471  * Atomically modifies a pointer to point to a new mini-object.
 472  * The reference count of @olddata is decreased and the reference count of
 473  * @newdata is increased.
 474  *
 475  * Either @newdata and the value pointed to by @olddata may be NULL.
 476  *
 477  * Returns: TRUE if @newdata was different from @olddata
 478  */
 479 gboolean
 480 gst_mini_object_replace (GstMiniObject ** olddata, GstMiniObject * newdata)
 481 {
 482   GstMiniObject *olddata_val;
 483
 484   g_return_val_if_fail (olddata != NULL, FALSE);
 485
 486   GST_CAT_TRACE (GST_CAT_REFCOUNTING, "replace %p (%d) with %p (%d)",
 487       *olddata, *olddata ? (*olddata)->refcount : 0,
 488       newdata, newdata ? newdata->refcount : 0);
 489
 490   olddata_val = g_atomic_pointer_get ((gpointer *) olddata);
 491
 492   if (G_UNLIKELY (olddata_val == newdata))
 493     return FALSE;
 494
 495   if (newdata)
 496     gst_mini_object_ref (newdata);
 497
 498   while (G_UNLIKELY (!g_atomic_pointer_compare_and_exchange ((gpointer *)
 499               olddata, olddata_val, newdata))) {
 500     olddata_val = g_atomic_pointer_get ((gpointer *) olddata);
 501     if (G_UNLIKELY (olddata_val == newdata))
 502       break;
 503   }
 504
 505   if (olddata_val)
 506     gst_mini_object_unref (olddata_val);
 507
 508   return olddata_val != newdata;
 509 }
 510
 511 /**
 512  * gst_mini_object_steal:
 513  * @olddata: (inout) (transfer full): pointer to a pointer to a mini-object to
 514  *     be stolen
 515  *
 516  * Replace the current #GstMiniObject pointer to by @olddata with NULL and
 517  * return the old value.
 518  *
 519  * Returns: the #GstMiniObject at @oldata
 520  */
 521 GstMiniObject *
 522 gst_mini_object_steal (GstMiniObject ** olddata)
 523 {
 524   GstMiniObject *olddata_val;
 525
 526   g_return_val_if_fail (olddata != NULL, NULL);
 527
 528   GST_CAT_TRACE (GST_CAT_REFCOUNTING, "steal %p (%d)",
 529       *olddata, *olddata ? (*olddata)->refcount : 0);
 530
 531   do {
 532     olddata_val = g_atomic_pointer_get ((gpointer *) olddata);
 533     if (olddata_val == NULL)
 534       break;
 535   } while (G_UNLIKELY (!g_atomic_pointer_compare_and_exchange ((gpointer *)
 536               olddata, olddata_val, NULL)));
 537
 538   return olddata_val;
 539 }
 540
 541 /**
 542  * gst_mini_object_take:
 543  * @olddata: (inout) (transfer full): pointer to a pointer to a mini-object to
 544  *     be replaced
 545  * @newdata: pointer to new mini-object
 546  *
 547  * Modifies a pointer to point to a new mini-object. The modification
 548  * is done atomically. This version is similar to gst_mini_object_replace()
 549  * except that it does not increase the refcount of @newdata and thus
 550  * takes ownership of @newdata.
 551  *
 552  * Either @newdata and the value pointed to by @olddata may be NULL.
 553  *
 554  * Returns: TRUE if @newdata was different from @olddata
 555  */
 556 gboolean
 557 gst_mini_object_take (GstMiniObject ** olddata, GstMiniObject * newdata)
 558 {
 559   GstMiniObject *olddata_val;
 560
 561   g_return_val_if_fail (olddata != NULL, FALSE);
 562
 563   GST_CAT_TRACE (GST_CAT_REFCOUNTING, "take %p (%d) with %p (%d)",
 564       *olddata, *olddata ? (*olddata)->refcount : 0,
 565       newdata, newdata ? newdata->refcount : 0);
 566
 567   do {
 568     olddata_val = g_atomic_pointer_get ((gpointer *) olddata);
 569     if (G_UNLIKELY (olddata_val == newdata))
 570       break;
 571   } while (G_UNLIKELY (!g_atomic_pointer_compare_and_exchange ((gpointer *)
 572               olddata, olddata_val, newdata)));
 573
 574   if (olddata_val)
 575     gst_mini_object_unref (olddata_val);
 576
 577   return olddata_val != newdata;
 578 }
 579
 580 /**
 581  * gst_mini_object_weak_ref: (skip)
 582  * @object: #GstMiniObject to reference weakly
 583  * @notify: callback to invoke before the mini object is freed
 584  * @data: extra data to pass to notify
 585  *
 586  * Adds a weak reference callback to a mini object. Weak references are
 587  * used for notification when a mini object is finalized. They are called
 588  * "weak references" because they allow you to safely hold a pointer
 589  * to the mini object without calling gst_mini_object_ref()
 590  * (gst_mini_object_ref() adds a strong reference, that is, forces the object
 591  * to stay alive).
 592  */
 593 void
 594 gst_mini_object_weak_ref (GstMiniObject * object,
 595     GstMiniObjectNotify notify, gpointer data)
 596 {
 597   g_return_if_fail (object != NULL);
 598   g_return_if_fail (notify != NULL);
 599   g_return_if_fail (GST_MINI_OBJECT_REFCOUNT_VALUE (object) >= 1);
 600
 601   G_LOCK (qdata_mutex);
 602   set_notify (object, -1, weak_ref_quark, notify, data, NULL);
 603   G_UNLOCK (qdata_mutex);
 604 }
 605
 606 /**
 607  * gst_mini_object_weak_unref: (skip)
 608  * @object: #GstMiniObject to remove a weak reference from
 609  * @notify: callback to search for
 610  * @data: data to search for
 611  *
 612  * Removes a weak reference callback from a mini object.
 613  */
 614 void
 615 gst_mini_object_weak_unref (GstMiniObject * object,
 616     GstMiniObjectNotify notify, gpointer data)
 617 {
 618   gint i;
 619
 620   g_return_if_fail (object != NULL);
 621   g_return_if_fail (notify != NULL);
 622
 623   G_LOCK (qdata_mutex);
 624   if ((i = find_notify (object, weak_ref_quark, TRUE, notify, data)) != -1) {
 625     remove_notify (object, i);
 626   } else {
 627     g_warning ("%s: couldn't find weak ref %p(%p)", G_STRFUNC, notify, data);
 628   }
 629   G_UNLOCK (qdata_mutex);
 630 }
 631
 632 /**
 633  * gst_mini_object_set_qdata:
 634  * @object: a #GstMiniObject
 635  * @quark: A #GQuark, naming the user data pointer
 636  * @data: An opaque user data pointer
 637  * @destroy: Function to invoke with @data as argument, when @data
 638  *           needs to be freed
 639  *
 640  * This sets an opaque, named pointer on a miniobject.
 641  * The name is specified through a #GQuark (retrived e.g. via
 642  * g_quark_from_static_string()), and the pointer
 643  * can be gotten back from the @object with gst_mini_object_get_qdata()
 644  * until the @object is disposed.
 645  * Setting a previously set user data pointer, overrides (frees)
 646  * the old pointer set, using #NULL as pointer essentially
 647  * removes the data stored.
 648  *
 649  * @destroy may be specified which is called with @data as argument
 650  * when the @object is disposed, or the data is being overwritten by
 651  * a call to gst_mini_object_set_qdata() with the same @quark.
 652  */
 653 void
 654 gst_mini_object_set_qdata (GstMiniObject * object, GQuark quark,
 655     gpointer data, GDestroyNotify destroy)
 656 {
 657   gint i;
 658   gpointer old_data = NULL;
 659   GDestroyNotify old_notify = NULL;
 660
 661   g_return_if_fail (object != NULL);
 662   g_return_if_fail (quark > 0);
 663
 664   G_LOCK (qdata_mutex);
 665   if ((i = find_notify (object, quark, FALSE, NULL, NULL)) != -1) {
 666
 667     old_data = QDATA_DATA (object, i);
 668     old_notify = QDATA_DESTROY (object, i);
 669
 670     if (data == NULL)
 671       remove_notify (object, i);
 672   }
 673   if (data != NULL)
 674     set_notify (object, i, quark, NULL, data, destroy);
 675   G_UNLOCK (qdata_mutex);
 676
 677   if (old_notify)
 678     old_notify (old_data);
 679 }
 680
 681 /**
 682  * gst_mini_object_get_qdata:
 683  * @object: The GstMiniObject to get a stored user data pointer from
 684  * @quark: A #GQuark, naming the user data pointer
 685  *
 686  * This function gets back user data pointers stored via
 687  * gst_mini_object_set_qdata().
 688  *
 689  * Returns: (transfer none): The user data pointer set, or %NULL
 690  */
 691 gpointer
 692 gst_mini_object_get_qdata (GstMiniObject * object, GQuark quark)
 693 {
 694   guint i;
 695   gpointer result;
 696
 697   g_return_val_if_fail (object != NULL, NULL);
 698   g_return_val_if_fail (quark > 0, NULL);
 699
 700   G_LOCK (qdata_mutex);
 701   if ((i = find_notify (object, quark, FALSE, NULL, NULL)) != -1)
 702     result = QDATA_DATA (object, i);
 703   else
 704     result = NULL;
 705   G_UNLOCK (qdata_mutex);
 706
 707   return result;
 708 }
 709
 710 /**
 711  * gst_mini_object_steal_qdata:
 712  * @object: The GstMiniObject to get a stored user data pointer from
 713  * @quark: A #GQuark, naming the user data pointer
 714  *
 715  * This function gets back user data pointers stored via gst_mini_object_set_qdata()
 716  * and removes the data from @object without invoking its destroy() function (if
 717  * any was set).
 718  *
 719  * Returns: (transfer full): The user data pointer set, or %NULL
 720  */
 721 gpointer
 722 gst_mini_object_steal_qdata (GstMiniObject * object, GQuark quark)
 723 {
 724   guint i;
 725   gpointer result;
 726
 727   g_return_val_if_fail (object != NULL, NULL);
 728   g_return_val_if_fail (quark > 0, NULL);
 729
 730   G_LOCK (qdata_mutex);
 731   if ((i = find_notify (object, quark, FALSE, NULL, NULL)) != -1) {
 732     result = QDATA_DATA (object, i);
 733     remove_notify (object, i);
 734   } else {
 735     result = NULL;
 736   }
 737   G_UNLOCK (qdata_mutex);
 738
 739   return result;
 740 }