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 typedef struct
  72 {
  73   GQuark quark;
  74   GstMiniObjectNotify notify;
  75   gpointer data;
  76   GDestroyNotify destroy;
  77 } GstQData;
  78
  79 #define QDATA(o,i)          ((GstQData *)(o)->qdata)[(i)]
  80 #define QDATA_QUARK(o,i)    (QDATA(o,i).quark)
  81 #define QDATA_NOTIFY(o,i)   (QDATA(o,i).notify)
  82 #define QDATA_DATA(o,i)     (QDATA(o,i).data)
  83 #define QDATA_DESTROY(o,i)  (QDATA(o,i).destroy)
  84
  85 void
  86 _priv_gst_mini_object_initialize (void)
  87 {
  88   weak_ref_quark = g_quark_from_static_string ("GstMiniObjectWeakRefQuark");
  89
  90 #ifndef GST_DISABLE_TRACE
  91   _gst_mini_object_trace = _gst_alloc_trace_register ("GstMiniObject", 0);
  92 #endif
  93 }
  94
  95 /**
  96  * gst_mini_object_init: (skip)
  97  * @mini_object: a #GstMiniObject
  98  * @type: the #GType of the mini-object to create
  99  * @copy_func: the copy function, or NULL
 100  * @dispose_func: the dispose function, or NULL
 101  * @free_func: the free function or NULL
 102  *
 103  * Initializes a mini-object with the desired type and copy/dispose/free
 104  * functions.
 105  *
 106  * MT safe
 107  *
 108  * Returns: (transfer full): the new mini-object.
 109  */
 110 void
 111 gst_mini_object_init (GstMiniObject * mini_object, GType type,
 112     GstMiniObjectCopyFunction copy_func,
 113     GstMiniObjectDisposeFunction dispose_func,
 114     GstMiniObjectFreeFunction free_func)
 115 {
 116   mini_object->type = type;
 117   mini_object->refcount = 1;
 118   mini_object->flags = 0;
 119
 120   mini_object->copy = copy_func;
 121   mini_object->dispose = dispose_func;
 122   mini_object->free = free_func;
 123
 124   mini_object->n_qdata = 0;
 125   mini_object->qdata = NULL;
 126
 127 #ifndef GST_DISABLE_TRACE
 128   _gst_alloc_trace_new (_gst_mini_object_trace, mini_object);
 129 #endif
 130 }
 131
 132 /**
 133  * gst_mini_object_copy:
 134  * @mini_object: the mini-object to copy
 135  *
 136  * Creates a copy of the mini-object.
 137  *
 138  * MT safe
 139  *
 140  * Returns: (transfer full): the new mini-object.
 141  */
 142 GstMiniObject *
 143 gst_mini_object_copy (const GstMiniObject * mini_object)
 144 {
 145   GstMiniObject *copy;
 146
 147   g_return_val_if_fail (mini_object != NULL, NULL);
 148
 149   if (mini_object->copy)
 150     copy = mini_object->copy (mini_object);
 151   else
 152     copy = NULL;
 153
 154   return copy;
 155 }
 156
 157 /**
 158  * gst_mini_object_is_writable:
 159  * @mini_object: the mini-object to check
 160  *
 161  * Checks if a mini-object is writable.  A mini-object is writable
 162  * if the reference count is one. Modification of a mini-object should
 163  * only be done after verifying that it is writable.
 164  *
 165  * MT safe
 166  *
 167  * Returns: TRUE if the object is writable.
 168  */
 169 gboolean
 170 gst_mini_object_is_writable (const GstMiniObject * mini_object)
 171 {
 172   g_return_val_if_fail (mini_object != NULL, FALSE);
 173
 174   return (GST_MINI_OBJECT_REFCOUNT_VALUE (mini_object) == 1);
 175 }
 176
 177 /**
 178  * gst_mini_object_make_writable:
 179  * @mini_object: (transfer full): the mini-object to make writable
 180  *
 181  * Checks if a mini-object is writable.  If not, a writable copy is made and
 182  * returned.  This gives away the reference to the original mini object,
 183  * and returns a reference to the new object.
 184  *
 185  * MT safe
 186  *
 187  * Returns: (transfer full): a mini-object (possibly the same pointer) that
 188  *     is writable.
 189  */
 190 GstMiniObject *
 191 gst_mini_object_make_writable (GstMiniObject * mini_object)
 192 {
 193   GstMiniObject *ret;
 194
 195   g_return_val_if_fail (mini_object != NULL, NULL);
 196
 197   if (gst_mini_object_is_writable (mini_object)) {
 198     ret = mini_object;
 199   } else {
 200     ret = gst_mini_object_copy (mini_object);
 201     GST_CAT_DEBUG (GST_CAT_PERFORMANCE, "copy %s miniobject %p -> %p",
 202         g_type_name (GST_MINI_OBJECT_TYPE (mini_object)), mini_object, ret);
 203     gst_mini_object_unref (mini_object);
 204   }
 205
 206   return ret;
 207 }
 208
 209 /**
 210  * gst_mini_object_ref:
 211  * @mini_object: the mini-object
 212  *
 213  * Increase the reference count of the mini-object.
 214  *
 215  * Note that the refcount affects the writeability
 216  * of @mini-object, see gst_mini_object_is_writable(). It is
 217  * important to note that keeping additional references to
 218  * GstMiniObject instances can potentially increase the number
 219  * of memcpy operations in a pipeline, especially if the miniobject
 220  * is a #GstBuffer.
 221  *
 222  * Returns: (transfer full): the mini-object.
 223  */
 224 GstMiniObject *
 225 gst_mini_object_ref (GstMiniObject * mini_object)
 226 {
 227   g_return_val_if_fail (mini_object != NULL, NULL);
 228   /* we can't assert that the refcount > 0 since the _free functions
 229    * increments the refcount from 0 to 1 again to allow resurecting
 230    * the object
 231    g_return_val_if_fail (mini_object->refcount > 0, NULL);
 232    */
 233
 234   GST_CAT_TRACE (GST_CAT_REFCOUNTING, "%p ref %d->%d", mini_object,
 235       GST_MINI_OBJECT_REFCOUNT_VALUE (mini_object),
 236       GST_MINI_OBJECT_REFCOUNT_VALUE (mini_object) + 1);
 237
 238   g_atomic_int_inc (&mini_object->refcount);
 239
 240   return mini_object;
 241 }
 242
 243 static gint
 244 find_notify (GstMiniObject * object, GQuark quark, gboolean match_notify,
 245     GstMiniObjectNotify notify, gpointer data)
 246 {
 247   guint i;
 248
 249   for (i = 0; i < object->n_qdata; i++) {
 250     if (QDATA_QUARK (object, i) == quark) {
 251       /* check if we need to match the callback too */
 252       if (!match_notify || (QDATA_NOTIFY (object, i) == notify &&
 253               QDATA_DATA (object, i) == data))
 254         return i;
 255     }
 256   }
 257   return -1;
 258 }
 259
 260 static void
 261 remove_notify (GstMiniObject * object, gint index)
 262 {
 263   /* remove item */
 264   if (--object->n_qdata == 0) {
 265     /* we don't shrink but free when everything is gone */
 266     g_free (object->qdata);
 267     object->qdata = NULL;
 268   } else if (index != object->n_qdata)
 269     QDATA (object, index) = QDATA (object, object->n_qdata);
 270 }
 271
 272 static void
 273 set_notify (GstMiniObject * object, gint index, GQuark quark,
 274     GstMiniObjectNotify notify, gpointer data, GDestroyNotify destroy)
 275 {
 276   if (index == -1) {
 277     /* add item */
 278     index = object->n_qdata++;
 279     object->qdata =
 280         g_realloc (object->qdata, sizeof (GstQData) * object->n_qdata);
 281   }
 282   QDATA_QUARK (object, index) = quark;
 283   QDATA_NOTIFY (object, index) = notify;
 284   QDATA_DATA (object, index) = data;
 285   QDATA_DESTROY (object, index) = destroy;
 286 }
 287
 288 static void
 289 call_finalize_notify (GstMiniObject * obj)
 290 {
 291   guint i;
 292
 293   for (i = 0; i < obj->n_qdata; i++) {
 294     if (QDATA_QUARK (obj, i) == weak_ref_quark)
 295       QDATA_NOTIFY (obj, i) (QDATA_DATA (obj, i), obj);
 296     if (QDATA_DESTROY (obj, i))
 297       QDATA_DESTROY (obj, i) (QDATA_DATA (obj, i));
 298   }
 299 }
 300
 301 /**
 302  * gst_mini_object_unref:
 303  * @mini_object: the mini-object
 304  *
 305  * Decreases the reference count of the mini-object, possibly freeing
 306  * the mini-object.
 307  */
 308 void
 309 gst_mini_object_unref (GstMiniObject * mini_object)
 310 {
 311   g_return_if_fail (mini_object != NULL);
 312
 313   GST_CAT_TRACE (GST_CAT_REFCOUNTING, "%p unref %d->%d",
 314       mini_object,
 315       GST_MINI_OBJECT_REFCOUNT_VALUE (mini_object),
 316       GST_MINI_OBJECT_REFCOUNT_VALUE (mini_object) - 1);
 317
 318   g_return_if_fail (mini_object->refcount > 0);
 319
 320   if (G_UNLIKELY (g_atomic_int_dec_and_test (&mini_object->refcount))) {
 321     gboolean do_free;
 322
 323     if (mini_object->dispose)
 324       do_free = mini_object->dispose (mini_object);
 325     else
 326       do_free = TRUE;
 327
 328     /* if the subclass recycled the object (and returned FALSE) we don't
 329      * want to free the instance anymore */
 330     if (G_LIKELY (do_free)) {
 331       if (mini_object->n_qdata) {
 332         call_finalize_notify (mini_object);
 333         g_free (mini_object->qdata);
 334       }
 335 #ifndef GST_DISABLE_TRACE
 336       _gst_alloc_trace_free (_gst_mini_object_trace, mini_object);
 337 #endif
 338       if (mini_object->free)
 339         mini_object->free (mini_object);
 340     }
 341   }
 342 }
 343
 344 /**
 345  * gst_mini_object_replace:
 346  * @olddata: (inout) (transfer full): pointer to a pointer to a mini-object to
 347  *     be replaced
 348  * @newdata: pointer to new mini-object
 349  *
 350  * Atomically modifies a pointer to point to a new mini-object.
 351  * The reference count of @olddata is decreased and the reference count of
 352  * @newdata is increased.
 353  *
 354  * Either @newdata and the value pointed to by @olddata may be NULL.
 355  *
 356  * Returns: TRUE if @newdata was different from @olddata
 357  */
 358 gboolean
 359 gst_mini_object_replace (GstMiniObject ** olddata, GstMiniObject * newdata)
 360 {
 361   GstMiniObject *olddata_val;
 362
 363   g_return_val_if_fail (olddata != NULL, FALSE);
 364
 365   GST_CAT_TRACE (GST_CAT_REFCOUNTING, "replace %p (%d) with %p (%d)",
 366       *olddata, *olddata ? (*olddata)->refcount : 0,
 367       newdata, newdata ? newdata->refcount : 0);
 368
 369   olddata_val = g_atomic_pointer_get ((gpointer *) olddata);
 370
 371   if (G_UNLIKELY (olddata_val == newdata))
 372     return FALSE;
 373
 374   if (newdata)
 375     gst_mini_object_ref (newdata);
 376
 377   while (G_UNLIKELY (!g_atomic_pointer_compare_and_exchange ((gpointer *)
 378               olddata, olddata_val, newdata))) {
 379     olddata_val = g_atomic_pointer_get ((gpointer *) olddata);
 380     if (G_UNLIKELY (olddata_val == newdata))
 381       break;
 382   }
 383
 384   if (olddata_val)
 385     gst_mini_object_unref (olddata_val);
 386
 387   return olddata_val != newdata;
 388 }
 389
 390 /**
 391  * gst_mini_object_steal:
 392  * @olddata: (inout) (transfer full): pointer to a pointer to a mini-object to
 393  *     be stolen
 394  *
 395  * Replace the current #GstMiniObject pointer to by @olddata with NULL and
 396  * return the old value.
 397  *
 398  * Returns: the #GstMiniObject at @oldata
 399  */
 400 GstMiniObject *
 401 gst_mini_object_steal (GstMiniObject ** olddata)
 402 {
 403   GstMiniObject *olddata_val;
 404
 405   g_return_val_if_fail (olddata != NULL, NULL);
 406
 407   GST_CAT_TRACE (GST_CAT_REFCOUNTING, "steal %p (%d)",
 408       *olddata, *olddata ? (*olddata)->refcount : 0);
 409
 410   do {
 411     olddata_val = g_atomic_pointer_get ((gpointer *) olddata);
 412     if (olddata_val == NULL)
 413       break;
 414   } while (G_UNLIKELY (!g_atomic_pointer_compare_and_exchange ((gpointer *)
 415               olddata, olddata_val, NULL)));
 416
 417   return olddata_val;
 418 }
 419
 420 /**
 421  * gst_mini_object_take:
 422  * @olddata: (inout) (transfer full): pointer to a pointer to a mini-object to
 423  *     be replaced
 424  * @newdata: pointer to new mini-object
 425  *
 426  * Modifies a pointer to point to a new mini-object. The modification
 427  * is done atomically. This version is similar to gst_mini_object_replace()
 428  * except that it does not increase the refcount of @newdata and thus
 429  * takes ownership of @newdata.
 430  *
 431  * Either @newdata and the value pointed to by @olddata may be NULL.
 432  *
 433  * Returns: TRUE if @newdata was different from @olddata
 434  */
 435 gboolean
 436 gst_mini_object_take (GstMiniObject ** olddata, GstMiniObject * newdata)
 437 {
 438   GstMiniObject *olddata_val;
 439
 440   g_return_val_if_fail (olddata != NULL, FALSE);
 441
 442   GST_CAT_TRACE (GST_CAT_REFCOUNTING, "take %p (%d) with %p (%d)",
 443       *olddata, *olddata ? (*olddata)->refcount : 0,
 444       newdata, newdata ? newdata->refcount : 0);
 445
 446   do {
 447     olddata_val = g_atomic_pointer_get ((gpointer *) olddata);
 448     if (G_UNLIKELY (olddata_val == newdata))
 449       break;
 450   } while (G_UNLIKELY (!g_atomic_pointer_compare_and_exchange ((gpointer *)
 451               olddata, olddata_val, newdata)));
 452
 453   if (olddata_val)
 454     gst_mini_object_unref (olddata_val);
 455
 456   return olddata_val != newdata;
 457 }
 458
 459 /**
 460  * gst_mini_object_weak_ref: (skip)
 461  * @object: #GstMiniObject to reference weakly
 462  * @notify: callback to invoke before the mini object is freed
 463  * @data: extra data to pass to notify
 464  *
 465  * Adds a weak reference callback to a mini object. Weak references are
 466  * used for notification when a mini object is finalized. They are called
 467  * "weak references" because they allow you to safely hold a pointer
 468  * to the mini object without calling gst_mini_object_ref()
 469  * (gst_mini_object_ref() adds a strong reference, that is, forces the object
 470  * to stay alive).
 471  *
 472  * Since: 0.10.35
 473  */
 474 void
 475 gst_mini_object_weak_ref (GstMiniObject * object,
 476     GstMiniObjectNotify notify, gpointer data)
 477 {
 478   g_return_if_fail (object != NULL);
 479   g_return_if_fail (notify != NULL);
 480   g_return_if_fail (GST_MINI_OBJECT_REFCOUNT_VALUE (object) >= 1);
 481
 482   G_LOCK (qdata_mutex);
 483   set_notify (object, -1, weak_ref_quark, notify, data, NULL);
 484   G_UNLOCK (qdata_mutex);
 485 }
 486
 487 /**
 488  * gst_mini_object_weak_unref: (skip)
 489  * @object: #GstMiniObject to remove a weak reference from
 490  * @notify: callback to search for
 491  * @data: data to search for
 492  *
 493  * Removes a weak reference callback from a mini object.
 494  *
 495  * Since: 0.10.35
 496  */
 497 void
 498 gst_mini_object_weak_unref (GstMiniObject * object,
 499     GstMiniObjectNotify notify, gpointer data)
 500 {
 501   gint i;
 502
 503   g_return_if_fail (object != NULL);
 504   g_return_if_fail (notify != NULL);
 505
 506   G_LOCK (qdata_mutex);
 507   if ((i = find_notify (object, weak_ref_quark, TRUE, notify, data)) != -1) {
 508     remove_notify (object, i);
 509   } else {
 510     g_warning ("%s: couldn't find weak ref %p(%p)", G_STRFUNC, notify, data);
 511   }
 512   G_UNLOCK (qdata_mutex);
 513 }
 514
 515 /**
 516  * gst_mini_object_set_qdata:
 517  * @object: a #GstMiniObject
 518  * @quark: A #GQuark, naming the user data pointer
 519  * @data: An opaque user data pointer
 520  * @destroy: Function to invoke with @data as argument, when @data
 521  *           needs to be freed
 522  *
 523  * This sets an opaque, named pointer on a miniobject.
 524  * The name is specified through a #GQuark (retrived e.g. via
 525  * g_quark_from_static_string()), and the pointer
 526  * can be gotten back from the @object with gst_mini_object_get_qdata()
 527  * until the @object is disposed.
 528  * Setting a previously set user data pointer, overrides (frees)
 529  * the old pointer set, using #NULL as pointer essentially
 530  * removes the data stored.
 531  *
 532  * @destroy may be specified which is called with @data as argument
 533  * when the @object is disposed, or the data is being overwritten by
 534  * a call to gst_mini_object_set_qdata() with the same @quark.
 535  */
 536 void
 537 gst_mini_object_set_qdata (GstMiniObject * object, GQuark quark,
 538     gpointer data, GDestroyNotify destroy)
 539 {
 540   gint i;
 541   gpointer old_data = NULL;
 542   GDestroyNotify old_notify = NULL;
 543
 544   g_return_if_fail (object != NULL);
 545   g_return_if_fail (quark > 0);
 546
 547   G_LOCK (qdata_mutex);
 548   if ((i = find_notify (object, quark, FALSE, NULL, NULL)) != -1) {
 549
 550     old_data = QDATA_DATA (object, i);
 551     old_notify = QDATA_DESTROY (object, i);
 552
 553     if (data == NULL)
 554       remove_notify (object, i);
 555   }
 556   if (data != NULL)
 557     set_notify (object, i, quark, NULL, data, destroy);
 558   G_UNLOCK (qdata_mutex);
 559
 560   if (old_notify)
 561     old_notify (old_data);
 562 }
 563
 564 /**
 565  * gst_mini_object_get_qdata:
 566  * @object: The GstMiniObject to get a stored user data pointer from
 567  * @quark: A #GQuark, naming the user data pointer
 568  *
 569  * This function gets back user data pointers stored via
 570  * gst_mini_object_set_qdata().
 571  *
 572  * Returns: (transfer none): The user data pointer set, or %NULL
 573  */
 574 gpointer
 575 gst_mini_object_get_qdata (GstMiniObject * object, GQuark quark)
 576 {
 577   guint i;
 578   gpointer result;
 579
 580   g_return_val_if_fail (object != NULL, NULL);
 581   g_return_val_if_fail (quark > 0, NULL);
 582
 583   G_LOCK (qdata_mutex);
 584   if ((i = find_notify (object, quark, FALSE, NULL, NULL)) != -1)
 585     result = QDATA_DATA (object, i);
 586   else
 587     result = NULL;
 588   G_UNLOCK (qdata_mutex);
 589
 590   return result;
 591 }
 592
 593 /**
 594  * gst_mini_object_steal_qdata:
 595  * @object: The GstMiniObject to get a stored user data pointer from
 596  * @quark: A #GQuark, naming the user data pointer
 597  *
 598  * This function gets back user data pointers stored via gst_mini_object_set_qdata()
 599  * and removes the data from @object without invoking its destroy() function (if
 600  * any was set).
 601  *
 602  * Returns: (transfer full): The user data pointer set, or %NULL
 603  */
 604 gpointer
 605 gst_mini_object_steal_qdata (GstMiniObject * object, GQuark quark)
 606 {
 607   guint i;
 608   gpointer result;
 609
 610   g_return_val_if_fail (object != NULL, NULL);
 611   g_return_val_if_fail (quark > 0, NULL);
 612
 613   G_LOCK (qdata_mutex);
 614   if ((i = find_notify (object, quark, FALSE, NULL, NULL)) != -1) {
 615     result = QDATA_DATA (object, i);
 616     remove_notify (object, i);
 617   } else {
 618     result = NULL;
 619   }
 620   G_UNLOCK (qdata_mutex);
 621
 622   return result;
 623 }