/* GStreamer

 * Copyright (C) 1999,2000 Erik Walthinsen <omega@cse.ogi.edu>

 *                    2000 Wim Taymans <wtay@chello.be>

 *                    2005 Wim Taymans <wim@fluendo.com>

 *

 * gstobject.c: Fundamental class used for all of GStreamer

 *

 * This library is free software; you can redistribute it and/or

 * modify it under the terms of the GNU Library General Public

 * License as published by the Free Software Foundation; either

 * version 2 of the License, or (at your option) any later version.

 *

 * This library is distributed in the hope that it will be useful,

 * but WITHOUT ANY WARRANTY; without even the implied warranty of

 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU

 * Library General Public License for more details.

 *

 * You should have received a copy of the GNU Library General Public

 * License along with this library; if not, write to the

 * Free Software Foundation, Inc., 59 Temple Place - Suite 330,

 * Boston, MA 02111-1307, USA.

 */

/**

 * SECTION:gstobject

 * @short_description: Base class for the GStreamer object hierarchy

 *

 * #GstObject provides a root for the object hierarchy tree filed in by the

 * GStreamer library.  It is currently a thin wrapper on top of

 * #GObject. It is an abstract class that is not very usable on its own.

 *

 * #GstObject gives us basic refcounting, parenting functionality and locking.

 * Most of the function are just extended for special GStreamer needs and can be

 * found under the same name in the base class of #GstObject which is #GObject

 * (e.g. g_object_ref() becomes gst_object_ref()).

 *

 * The most interesting difference between #GstObject and #GObject is the

 * "floating" reference count. A #GObject is created with a reference count of

 * 1, owned by the creator of the #GObject. (The owner of a reference is the

 * code section that has the right to call gst_object_unref() in order to

 * remove that reference.) A #GstObject is created with a reference count of 1

 * also, but it isn't owned by anyone; Instead, the initial reference count

 * of a #GstObject is "floating". The floating reference can be removed by

 * anyone at any time, by calling gst_object_sink().  gst_object_sink() does

 * nothing if an object is already sunk (has no floating reference).

 *

 * When you add a #GstElement to its parent container, the parent container will

 * do this:

 * <informalexample>

 * <programlisting>

 *   gst_object_ref (GST_OBJECT (child_element));

 *   gst_object_sink (GST_OBJECT (child_element));

 * </programlisting>

 * </informalexample>

 * This means that the container now owns a reference to the child element

 * (since it called gst_object_ref()), and the child element has no floating

 * reference.

 *

 * The purpose of the floating reference is to keep the child element alive

 * until you add it to a parent container, which then manages the lifetime of

 * the object itself:

 * <informalexample>

 * <programlisting>

 *    element = gst_element_factory_make (factoryname, name);

 *    // element has one floating reference to keep it alive

 *    gst_bin_add (GST_BIN (bin), element);

 *    // element has one non-floating reference owned by the container

 * </programlisting>

 * </informalexample>

 *

 * Another effect of this is, that calling gst_object_unref() on a bin object,

 * will also destoy all the #GstElement objects in it. The same is true for

 * calling gst_bin_remove().

 *

 * Special care has to be taken for all methods that gst_object_sink() an object

 * since if the caller of those functions had a floating reference to the object,

 * the object reference is now invalid.

 *

 * In contrast to #GObject instances, #GstObject adds a name property. The functions

 * gst_object_set_name() and gst_object_get_name() are used to set/get the name

 * of the object.

 *

 * Last reviewed on 2005-11-09 (0.9.4)

 */

#include "gst_private.h"

#include "gstobject.h"

#include "gstmarshal.h"

#include "gstinfo.h"

#include "gstutils.h"

#ifdef __SYMBIAN32__

#include <glib_global.h>

#include <gobject_global.h>

#endif

#ifndef GST_DISABLE_TRACE

#include "gsttrace.h"

static GstAllocTrace *_gst_object_trace;

#endif

#define DEBUG_REFCOUNT

/* Object signals and args */

/* FIXME-0.11: have a read-only parent property instead of the two signals

 * then we get notify::parent for free */

enum

{

  PARENT_SET,

  PARENT_UNSET,

#ifndef GST_DISABLE_LOADSAVE

  OBJECT_SAVED,

#endif

  DEEP_NOTIFY,

  LAST_SIGNAL

};

enum

{

  ARG_0,

  ARG_NAME

      /* FILL ME */

};

enum

{

  SO_OBJECT_LOADED,

  SO_LAST_SIGNAL

};

/* maps type name quark => count */

static GData *object_name_counts = NULL;

G_LOCK_DEFINE_STATIC (object_name_mutex);

typedef struct _GstSignalObject GstSignalObject;

typedef struct _GstSignalObjectClass GstSignalObjectClass;

static GType gst_signal_object_get_type (void);

static void gst_signal_object_class_init (GstSignalObjectClass * klass);

static void gst_signal_object_init (GstSignalObject * object);

#ifndef GST_DISABLE_LOADSAVE

static guint gst_signal_object_signals[SO_LAST_SIGNAL] = { 0 };

#endif

static void gst_object_set_property (GObject * object, guint prop_id,

    const GValue * value, GParamSpec * pspec);

static void gst_object_get_property (GObject * object, guint prop_id,

    GValue * value, GParamSpec * pspec);

static void gst_object_dispatch_properties_changed (GObject * object,

    guint n_pspecs, GParamSpec ** pspecs);

static void gst_object_dispose (GObject * object);

static void gst_object_finalize (GObject * object);

static gboolean gst_object_set_name_default (GstObject * object);

#ifndef GST_DISABLE_LOADSAVE

static void gst_object_real_restore_thyself (GstObject * object,

    xmlNodePtr self);

#endif

static GObjectClass *parent_class = NULL;

static guint gst_object_signals[LAST_SIGNAL] = { 0 };

G_DEFINE_ABSTRACT_TYPE (GstObject, gst_object, G_TYPE_OBJECT);

static void

gst_object_class_init (GstObjectClass * klass)

{

  GObjectClass *gobject_class = G_OBJECT_CLASS (klass);

  parent_class = g_type_class_peek_parent (klass);

#ifndef GST_DISABLE_TRACE

  _gst_object_trace = gst_alloc_trace_register (g_type_name (GST_TYPE_OBJECT));

#endif

  gobject_class->set_property = GST_DEBUG_FUNCPTR (gst_object_set_property);

  gobject_class->get_property = GST_DEBUG_FUNCPTR (gst_object_get_property);

  g_object_class_install_property (gobject_class, ARG_NAME,

      g_param_spec_string ("name", "Name", "The name of the object",

          NULL,

          G_PARAM_READWRITE | G_PARAM_CONSTRUCT | G_PARAM_STATIC_STRINGS));

  /**

   * GstObject::parent-set:

   * @gstobject: a #GstObject

   * @parent: the new parent

   *

   * Emitted when the parent of an object is set.

   */

  gst_object_signals[PARENT_SET] =

      g_signal_new ("parent-set", G_TYPE_FROM_CLASS (klass), G_SIGNAL_RUN_LAST,

      G_STRUCT_OFFSET (GstObjectClass, parent_set), NULL, NULL,

      g_cclosure_marshal_VOID__OBJECT, G_TYPE_NONE, 1, GST_TYPE_OBJECT);

  /**

   * GstObject::parent-unset:

   * @gstobject: a #GstObject

   * @parent: the old parent

   *

   * Emitted when the parent of an object is unset.

   */

  gst_object_signals[PARENT_UNSET] =

      g_signal_new ("parent-unset", G_TYPE_FROM_CLASS (klass),

      G_SIGNAL_RUN_LAST, G_STRUCT_OFFSET (GstObjectClass, parent_unset), NULL,

      NULL, g_cclosure_marshal_VOID__OBJECT, G_TYPE_NONE, 1, GST_TYPE_OBJECT);

#ifndef GST_DISABLE_LOADSAVE

  /**

   * GstObject::object-saved:

   * @gstobject: a #GstObject

   * @xml_node: the xmlNodePtr of the parent node

   *

   * Trigered whenever a new object is saved to XML. You can connect to this

   * signal to insert custom XML tags into the core XML.

   */

  /* FIXME This should be the GType of xmlNodePtr instead of G_TYPE_POINTER

   *       (if libxml would use GObject)

   */

  gst_object_signals[OBJECT_SAVED] =

      g_signal_new ("object-saved", G_TYPE_FROM_CLASS (klass),

      G_SIGNAL_RUN_LAST, G_STRUCT_OFFSET (GstObjectClass, object_saved), NULL,

      NULL, g_cclosure_marshal_VOID__POINTER, G_TYPE_NONE, 1, G_TYPE_POINTER);

  klass->restore_thyself = gst_object_real_restore_thyself;

#endif

  /**

   * GstObject::deep-notify:

   * @gstobject: a #GstObject

   * @prop_object: the object that originated the signal

   * @prop: the property that changed

   *

   * The deep notify signal is used to be notified of property changes. It is

   * typically attached to the toplevel bin to receive notifications from all

   * the elements contained in that bin.

   */

  gst_object_signals[DEEP_NOTIFY] =

      g_signal_new ("deep-notify", G_TYPE_FROM_CLASS (klass),

      G_SIGNAL_RUN_FIRST | G_SIGNAL_NO_RECURSE | G_SIGNAL_DETAILED |

      G_SIGNAL_NO_HOOKS, G_STRUCT_OFFSET (GstObjectClass, deep_notify), NULL,

      NULL, gst_marshal_VOID__OBJECT_PARAM, G_TYPE_NONE, 2, GST_TYPE_OBJECT,

      G_TYPE_PARAM);

  klass->path_string_separator = "/";

  klass->lock = g_new0 (GStaticRecMutex, 1);

  g_static_rec_mutex_init (klass->lock);

  klass->signal_object = g_object_new (gst_signal_object_get_type (), NULL);

  /* see the comments at gst_object_dispatch_properties_changed */

  gobject_class->dispatch_properties_changed

      = GST_DEBUG_FUNCPTR (gst_object_dispatch_properties_changed);

  gobject_class->dispose = gst_object_dispose;

  gobject_class->finalize = gst_object_finalize;

}

static void

gst_object_init (GstObject * object)

{

  object->lock = g_mutex_new ();

  object->parent = NULL;

  object->name = NULL;

  GST_CAT_LOG_OBJECT (GST_CAT_REFCOUNTING, object, "%p new", object);

#ifndef GST_DISABLE_TRACE

  gst_alloc_trace_new (_gst_object_trace, object);

#endif

  object->flags = 0;

  GST_OBJECT_FLAG_SET (object, GST_OBJECT_FLOATING);

}

/**

 * gst_object_ref:

 * @object: a #GstObject to reference

 *

 * Increments the reference count on @object. This function

 * does not take the lock on @object because it relies on

 * atomic refcounting.

 *

 * This object returns the input parameter to ease writing

 * constructs like :

 *  result = gst_object_ref (object->parent);

 *

 * Returns: A pointer to @object

 */

#ifdef __SYMBIAN32__

EXPORT_C

#endif

gpointer

gst_object_ref (gpointer object)

{

  g_return_val_if_fail (object != NULL, NULL);

#ifdef DEBUG_REFCOUNT

  GST_CAT_LOG_OBJECT (GST_CAT_REFCOUNTING, object, "%p ref %d->%d",

      object,

      ((GObject *) object)->ref_count, ((GObject *) object)->ref_count + 1);

#endif

  g_object_ref (object);

  return object;

}

/**

 * gst_object_unref:

 * @object: a #GstObject to unreference

 *

 * Decrements the reference count on @object.  If reference count hits

 * zero, destroy @object. This function does not take the lock

 * on @object as it relies on atomic refcounting.

 *

 * The unref method should never be called with the LOCK held since

 * this might deadlock the dispose function.

 */

#ifdef __SYMBIAN32__

EXPORT_C

#endif

void

gst_object_unref (gpointer object)

{

  g_return_if_fail (object != NULL);

  g_return_if_fail (((GObject *) object)->ref_count > 0);

#ifdef DEBUG_REFCOUNT

  GST_CAT_LOG_OBJECT (GST_CAT_REFCOUNTING, object, "%p unref %d->%d",

      object,

      ((GObject *) object)->ref_count, ((GObject *) object)->ref_count - 1);

#endif

  g_object_unref (object);

}

/**

 * gst_object_ref_sink:

 * @object: a #GstObject to sink

 *

 * Increase the reference count of @object, and possibly remove the floating

 * reference, if @object has a floating reference.

 *

 * In other words, if the object is floating, then this call "assumes ownership"

 * of the floating reference, converting it to a normal reference by clearing

 * the floating flag while leaving the reference count unchanged. If the object

 * is not floating, then this call adds a new normal reference increasing the

 * reference count by one.

 *

 * MT safe. This function grabs and releases @object lock.

 *

 * Since: 0.10.24

 */

#ifdef __SYMBIAN32__

EXPORT_C

#endif

void

gst_object_ref_sink (gpointer object)

{

  g_return_if_fail (GST_IS_OBJECT (object));

  GST_OBJECT_LOCK (object);

  if (G_LIKELY (GST_OBJECT_IS_FLOATING (object))) {

    GST_CAT_LOG_OBJECT (GST_CAT_REFCOUNTING, object, "unsetting floating flag");

    GST_OBJECT_FLAG_UNSET (object, GST_OBJECT_FLOATING);

    GST_OBJECT_UNLOCK (object);

  } else {

    GST_OBJECT_UNLOCK (object);

    gst_object_ref (object);

  }

}

/**

 * gst_object_sink:

 * @object: a #GstObject to sink

 *

 * If @object was floating, the #GST_OBJECT_FLOATING flag is removed

 * and @object is unreffed. When @object was not floating,

 * this function does nothing.

 *

 * Any newly created object has a refcount of 1 and is floating.

 * This function should be used when creating a new object to

 * symbolically 'take ownership' of @object. This done by first doing a

 * gst_object_ref() to keep a reference to @object and then gst_object_sink()

 * to remove and unref any floating references to @object.

 * Use gst_object_set_parent() to have this done for you.

 *

 * MT safe. This function grabs and releases @object lock.

 */

#ifdef __SYMBIAN32__

EXPORT_C

#endif

void

gst_object_sink (gpointer object)

{

  g_return_if_fail (GST_IS_OBJECT (object));

  GST_CAT_LOG_OBJECT (GST_CAT_REFCOUNTING, object, "sink");

  GST_OBJECT_LOCK (object);

  if (G_LIKELY (GST_OBJECT_IS_FLOATING (object))) {

    GST_CAT_LOG_OBJECT (GST_CAT_REFCOUNTING, object, "clear floating flag");

    GST_OBJECT_FLAG_UNSET (object, GST_OBJECT_FLOATING);

    GST_OBJECT_UNLOCK (object);

    gst_object_unref (object);

  } else {

    GST_OBJECT_UNLOCK (object);

  }

}

/**

 * gst_object_replace:

 * @oldobj: pointer to a place of a #GstObject to replace

 * @newobj: a new #GstObject

 *

 * Unrefs the #GstObject pointed to by @oldobj, refs @newobj and

 * puts @newobj in *@oldobj. Be carefull when calling this

 * function, it does not take any locks. You might want to lock

 * the object owning @oldobj pointer before calling this

 * function.

 *

 * Make sure not to LOCK @oldobj because it might be unreffed

 * which could cause a deadlock when it is disposed.

 */

#ifdef __SYMBIAN32__

EXPORT_C

#endif

void

gst_object_replace (GstObject ** oldobj, GstObject * newobj)

{

  g_return_if_fail (oldobj != NULL);

  g_return_if_fail (*oldobj == NULL || GST_IS_OBJECT (*oldobj));

  g_return_if_fail (newobj == NULL || GST_IS_OBJECT (newobj));

#ifdef DEBUG_REFCOUNT

  GST_CAT_LOG (GST_CAT_REFCOUNTING, "replace %p %s (%d) with %p %s (%d)",

      *oldobj, *oldobj ? GST_STR_NULL (GST_OBJECT_NAME (*oldobj)) : "(NONE)",

      *oldobj ? G_OBJECT (*oldobj)->ref_count : 0,

      newobj, newobj ? GST_STR_NULL (GST_OBJECT_NAME (newobj)) : "(NONE)",

      newobj ? G_OBJECT (newobj)->ref_count : 0);

#endif

  if (G_LIKELY (*oldobj != newobj)) {

    if (newobj)

      gst_object_ref (newobj);

    if (*oldobj)

      gst_object_unref (*oldobj);

    *oldobj = newobj;

  }

}

/* dispose is called when the object has to release all links

 * to other objects */

static void

gst_object_dispose (GObject * object)

{

  GstObject *parent;

  GST_CAT_LOG_OBJECT (GST_CAT_REFCOUNTING, object, "dispose");

  GST_OBJECT_LOCK (object);

  if ((parent = GST_OBJECT_PARENT (object)))

    goto have_parent;

  GST_OBJECT_PARENT (object) = NULL;

  GST_OBJECT_UNLOCK (object);

  parent_class->dispose (object);

  return;

  /* ERRORS */

have_parent:

  {

    g_critical ("\nTrying to dispose object \"%s\", but it still has a "

        "parent \"%s\".\nYou need to let the parent manage the "

        "object instead of unreffing the object directly.\n",

        GST_OBJECT_NAME (object), GST_OBJECT_NAME (parent));

    GST_OBJECT_UNLOCK (object);

    /* ref the object again to revive it in this error case */

    object = gst_object_ref (object);

    return;

  }

}

/* finalize is called when the object has to free its resources */

static void

gst_object_finalize (GObject * object)

{

  GstObject *gstobject = GST_OBJECT (object);

  GST_CAT_LOG_OBJECT (GST_CAT_REFCOUNTING, object, "finalize");

  g_signal_handlers_destroy (object);

  g_free (gstobject->name);

  g_mutex_free (gstobject->lock);

#ifndef GST_DISABLE_TRACE

  gst_alloc_trace_free (_gst_object_trace, object);

#endif

  parent_class->finalize (object);

}

/* Changing a GObject property of a GstObject will result in "deep_notify"

 * signals being emitted by the object itself, as well as in each parent

 * object. This is so that an application can connect a listener to the

 * top-level bin to catch property-change notifications for all contained

 * elements.

 *

 * This function is not MT safe in glib < 2.8 so we need to lock it with a

 * classwide mutex in that case.

 *

 * MT safe.

 */