/* GStreamer

 *

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

 *                    2004 Wim Taymans <wim.taymans@gmail.com>

 *

 * gstbin.c: GstBin container object and support code

 *

 * 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.

 *

 * MT safe.

 */

/**

 * SECTION:gstbin

 * @short_description: Base class and element that can contain other elements

 *

 * #GstBin is an element that can contain other #GstElement, allowing them to be

 * managed as a group.

 * Pads from the child elements can be ghosted to the bin, see #GstGhostPad.

 * This makes the bin look like any other elements and enables creation of

 * higher-level abstraction elements.

 *

 * A new #GstBin is created with gst_bin_new(). Use a #GstPipeline instead if you

 * want to create a toplevel bin because a normal bin doesn't have a bus or

 * handle clock distribution of its own.

 *

 * After the bin has been created you will typically add elements to it with

 * gst_bin_add(). You can remove elements with gst_bin_remove().

 *

 * An element can be retrieved from a bin with gst_bin_get_by_name(), using the

 * elements name. gst_bin_get_by_name_recurse_up() is mainly used for internal

 * purposes and will query the parent bins when the element is not found in the

 * current bin.

 *

 * An iterator of elements in a bin can be retrieved with

 * gst_bin_iterate_elements(). Various other iterators exist to retrieve the

 * elements in a bin.

 *

 * gst_object_unref() is used to drop your reference to the bin.

 *

 *

 * <refsect2><title>Notes</title>

 * <para>

 * A #GstBin internally intercepts every #GstMessage posted by its children and

 * implements the following default behaviour for each of them:

 * <variablelist>

 *   <varlistentry>

 *     <term>GST_MESSAGE_EOS</term>

 *     <listitem><para>This message is only posted by sinks in the PLAYING

 *     state. If all sinks posted the EOS message, this bin will post and EOS

 *     message upwards.</para></listitem>

 *   </varlistentry>

 *   <varlistentry>

 *     <term>GST_MESSAGE_SEGMENT_START</term>

 *     <listitem><para>just collected and never forwarded upwards.

 *     The messages are used to decide when all elements have completed playback

 *     of their segment.</para></listitem>

 *   </varlistentry>

 *   <varlistentry>

 *     <term>GST_MESSAGE_SEGMENT_DONE</term>

 *     <listitem><para> Is posted by #GstBin when all elements that posted

 *     a SEGMENT_START have posted a SEGMENT_DONE.</para></listitem>

 *   </varlistentry>

 *   <varlistentry>

 *     <term>GST_MESSAGE_DURATION</term>

 *     <listitem><para> Is posted by an element that detected a change

 *     in the stream duration. The default bin behaviour is to clear any

 *     cached duration values so that the next duration query will perform

 *     a full duration recalculation. The duration change is posted to the

 *     application so that it can refetch the new duration with a duration

 *     query.

 *     </para></listitem>

 *   </varlistentry>

 *   <varlistentry>

 *     <term>GST_MESSAGE_CLOCK_LOST</term>

 *     <listitem><para> This message is posted by an element when it

 *     can no longer provide a clock. The default bin behaviour is to

 *     check if the lost clock was the one provided by the bin. If so and

 *     the bin is currently in the PLAYING state, the message is forwarded to

 *     the bin parent.

 *     This message is also generated when a clock provider is removed from

 *     the bin. If this message is received by the application, it should

 *     PAUSE the pipeline and set it back to PLAYING to force a new clock

 *     distribution.

 *     </para></listitem>

 *   </varlistentry>

 *   <varlistentry>

 *     <term>GST_MESSAGE_CLOCK_PROVIDE</term>

 *     <listitem><para> This message is generated when an element

 *     can provide a clock. This mostly happens when a new clock

 *     provider is added to the bin. The default behaviour of the bin is to

 *     mark the currently selected clock as dirty, which will perform a clock

 *     recalculation the next time the bin is asked to provide a clock.

 *     This message is never sent tot the application but is forwarded to

 *     the parent of the bin.

 *     </para></listitem>

 *   </varlistentry>

 *   <varlistentry>

 *     <term>OTHERS</term>

 *     <listitem><para> posted upwards.</para></listitem>

 *   </varlistentry>

 * </variablelist>

 *

 *

 * A #GstBin implements the following default behaviour for answering to a

 * #GstQuery:

 * <variablelist>

 *   <varlistentry>

 *     <term>GST_QUERY_DURATION</term>

 *     <listitem><para>If the query has been asked before with the same format

 *     and the bin is a toplevel bin (ie. has no parent),

 *     use the cached previous value. If no previous value was cached, the

 *     query is sent to all sink elements in the bin and the MAXIMUM of all

 *     values is returned. If the bin is a toplevel bin the value is cached.

 *     If no sinks are available in the bin, the query fails.

 *     </para></listitem>

 *   </varlistentry>

 *   <varlistentry>

 *     <term>GST_QUERY_POSITION</term>

 *     <listitem><para>The query is sent to all sink elements in the bin and the

 *     MAXIMUM of all values is returned. If no sinks are available in the bin,

 *     the query fails.

 *     </para></listitem>

 *   </varlistentry>

 *   <varlistentry>

 *     <term>OTHERS</term>

 *     <listitem><para>the query is forwarded to all sink elements, the result

 *     of the first sink that answers the query successfully is returned. If no

 *     sink is in the bin, the query fails.</para></listitem>

 *   </varlistentry>

 * </variablelist>

 *

 * A #GstBin will by default forward any event sent to it to all sink elements.

 * If all the sinks return TRUE, the bin will also return TRUE, else FALSE is

 * returned. If no sinks are in the bin, the event handler will return TRUE.

 *

 * </para>

 * </refsect2>

 *

 * Last reviewed on 2006-04-28 (0.10.6)

 */

#include "gst_private.h"

#include "gstevent.h"

#include "gstbin.h"

#include "gstmarshal.h"

#include "gstxml.h"

#include "gstinfo.h"

#include "gsterror.h"

#include "gstindex.h"

#include "gstindexfactory.h"

#include "gstutils.h"

#include "gstchildproxy.h"

#ifdef __SYMBIAN32__

#include <glib_global.h>

#endif

/* enable for DURATION caching.

 * FIXME currently too many elements don't update

 * their duration when it changes so we return inaccurate values. */

#undef DURATION_CACHING

/* latency is by default enabled now.

 * live-preroll and no-live-preroll in the environment var GST_COMPAT

 * to enables or disable it respectively.

 */

static gboolean enable_latency = TRUE;

GST_DEBUG_CATEGORY_STATIC (bin_debug);

#define GST_CAT_DEFAULT bin_debug

/* a bin is toplevel if it has no parent or when it is configured to behave like

 * a toplevel bin */

#define BIN_IS_TOPLEVEL(bin) ((GST_OBJECT_PARENT (bin) == NULL) || bin->priv->asynchandling)

struct _GstBinPrivate

{

  gboolean asynchandling;

};

typedef struct

{

  GstBin *bin;

  guint32 cookie;

  GstState pending;

} BinContinueData;

static void gst_bin_dispose (GObject * object);

static void gst_bin_set_property (GObject * object, guint prop_id,

    const GValue * value, GParamSpec * pspec);

static void gst_bin_get_property (GObject * object, guint prop_id,

    GValue * value, GParamSpec * pspec);

static GstStateChangeReturn gst_bin_change_state_func (GstElement * element,

    GstStateChange transition);

static GstStateChangeReturn gst_bin_get_state_func (GstElement * element,

    GstState * state, GstState * pending, GstClockTime timeout);

static void bin_handle_async_start (GstBin * bin, gboolean new_base_time);

static void bin_push_state_continue (BinContinueData * data);

static gboolean gst_bin_add_func (GstBin * bin, GstElement * element);

static gboolean gst_bin_remove_func (GstBin * bin, GstElement * element);

static void gst_bin_set_index_func (GstElement * element, GstIndex * index);

static GstClock *gst_bin_provide_clock_func (GstElement * element);

static gboolean gst_bin_set_clock_func (GstElement * element, GstClock * clock);

static void gst_bin_handle_message_func (GstBin * bin, GstMessage * message);

static gboolean gst_bin_send_event (GstElement * element, GstEvent * event);

static GstBusSyncReply bin_bus_handler (GstBus * bus,

    GstMessage * message, GstBin * bin);

static gboolean gst_bin_query (GstElement * element, GstQuery * query);

#ifndef GST_DISABLE_LOADSAVE

static xmlNodePtr gst_bin_save_thyself (GstObject * object, xmlNodePtr parent);

static void gst_bin_restore_thyself (GstObject * object, xmlNodePtr self);

#endif

static void bin_remove_messages (GstBin * bin, GstObject * src,

    GstMessageType types);

static void gst_bin_continue_func (BinContinueData * data);

static gint bin_element_is_sink (GstElement * child, GstBin * bin);

static gint bin_element_is_src (GstElement * child, GstBin * bin);

static GstIterator *gst_bin_sort_iterator_new (GstBin * bin);

/* Bin signals and properties */

enum

{

  ELEMENT_ADDED,

  ELEMENT_REMOVED,

  LAST_SIGNAL

};

#define DEFAULT_ASYNC_HANDLING	FALSE

enum

{

  PROP_0,

  PROP_ASYNC_HANDLING

      /* FILL ME */

};

static void gst_bin_child_proxy_init (gpointer g_iface, gpointer iface_data);

static guint gst_bin_signals[LAST_SIGNAL] = { 0 };

}

static void

gst_bin_base_init (gpointer g_class)

{

  GstElementClass *gstelement_class = GST_ELEMENT_CLASS (g_class);

  gst_element_class_set_details_simple (gstelement_class, "Generic bin",

      "Generic/Bin",

      "Simple container object",

      "Erik Walthinsen <omega@cse.ogi.edu>,"

      "Wim Taymans <wim.taymans@gmail.com>");

}

static GstObject *

gst_bin_child_proxy_get_child_by_index (GstChildProxy * child_proxy,

    guint index)

{

  GstObject *res;

  GstBin *bin;

  bin = GST_BIN_CAST (child_proxy);

  GST_OBJECT_LOCK (bin);

  if ((res = g_list_nth_data (bin->children, index)))

    gst_object_ref (res);

  GST_OBJECT_UNLOCK (bin);

  return res;

}

#ifdef __SYMBIAN32__

EXPORT_C

#endif

guint

gst_bin_child_proxy_get_children_count (GstChildProxy * child_proxy)

{

  guint num;

  GstBin *bin;

  bin = GST_BIN_CAST (child_proxy);

  GST_OBJECT_LOCK (bin);

  num = bin->numchildren;

  GST_OBJECT_UNLOCK (bin);

  return num;

}

static void

gst_bin_child_proxy_init (gpointer g_iface, gpointer iface_data)

{

  GstChildProxyInterface *iface = g_iface;

  iface->get_children_count = gst_bin_child_proxy_get_children_count;

  iface->get_child_by_index = gst_bin_child_proxy_get_child_by_index;

}

static void

gst_bin_class_init (GstBinClass * klass)

{

  GObjectClass *gobject_class;

  GstObjectClass *gstobject_class;

  GstElementClass *gstelement_class;

  GError *err;

  gobject_class = (GObjectClass *) klass;

  gstobject_class = (GstObjectClass *) klass;

  gstelement_class = (GstElementClass *) klass;

  gobject_class->set_property = GST_DEBUG_FUNCPTR (gst_bin_set_property);

  gobject_class->get_property = GST_DEBUG_FUNCPTR (gst_bin_get_property);

  /**

   * GstBin:async-handling

   *

   * If set to #TRUE, the bin will handle asynchronous state changes.

   * This should be used only if the bin subclass is modifying the state

   * of its children on its own.

   *

   * Since: 0.10.13

   */

  g_object_class_install_property (gobject_class, PROP_ASYNC_HANDLING,

      g_param_spec_boolean ("async-handling", "Async Handling",

          "The bin will handle Asynchronous state changes",

  /**

   * GstBin::element-added:

   * @bin: the #GstBin

   * @element: the #GstElement that was added to the bin

   *

   * Will be emitted after the element was added to the bin.

   */

  gst_bin_signals[ELEMENT_ADDED] =

      g_signal_new ("element-added", G_TYPE_FROM_CLASS (klass),

      G_SIGNAL_RUN_FIRST, G_STRUCT_OFFSET (GstBinClass, element_added), NULL,

      NULL, gst_marshal_VOID__OBJECT, G_TYPE_NONE, 1, GST_TYPE_ELEMENT);

  /**

   * GstBin::element-removed:

   * @bin: the #GstBin

   * @element: the #GstElement that was removed from the bin

   *

   * Will be emitted after the element was removed from the bin.

   */

  gst_bin_signals[ELEMENT_REMOVED] =

      g_signal_new ("element-removed", G_TYPE_FROM_CLASS (klass),

      G_SIGNAL_RUN_FIRST, G_STRUCT_OFFSET (GstBinClass, element_removed), NULL,

      NULL, gst_marshal_VOID__OBJECT, G_TYPE_NONE, 1, GST_TYPE_ELEMENT);

  gobject_class->dispose = GST_DEBUG_FUNCPTR (gst_bin_dispose);

#ifndef GST_DISABLE_LOADSAVE

  gstobject_class->save_thyself = GST_DEBUG_FUNCPTR (gst_bin_save_thyself);

  gstobject_class->restore_thyself =

      GST_DEBUG_FUNCPTR (gst_bin_restore_thyself);

#endif

  gstelement_class->change_state =

      GST_DEBUG_FUNCPTR (gst_bin_change_state_func);

  gstelement_class->get_state = GST_DEBUG_FUNCPTR (gst_bin_get_state_func);

  gstelement_class->set_index = GST_DEBUG_FUNCPTR (gst_bin_set_index_func);

  gstelement_class->provide_clock =

      GST_DEBUG_FUNCPTR (gst_bin_provide_clock_func);

  gstelement_class->set_clock = GST_DEBUG_FUNCPTR (gst_bin_set_clock_func);

  gstelement_class->send_event = GST_DEBUG_FUNCPTR (gst_bin_send_event);

  gstelement_class->query = GST_DEBUG_FUNCPTR (gst_bin_query);

  klass->add_element = GST_DEBUG_FUNCPTR (gst_bin_add_func);

  klass->remove_element = GST_DEBUG_FUNCPTR (gst_bin_remove_func);

  klass->handle_message = GST_DEBUG_FUNCPTR (gst_bin_handle_message_func);

  GST_DEBUG ("creating bin thread pool");

  err = NULL;

  klass->pool =

      g_thread_pool_new ((GFunc) gst_bin_continue_func, NULL, -1, FALSE, &err);

  if (err != NULL) {

    g_critical ("could alloc threadpool %s", err->message);

  }

}

static void

{

  GstBus *bus;

  bin->numchildren = 0;

  bin->children = NULL;

  bin->children_cookie = 0;

  bin->messages = NULL;

  bin->provided_clock = NULL;

  bin->clock_dirty = FALSE;

  /* Set up a bus for listening to child elements */

  bus = gst_bus_new ();

  bin->child_bus = bus;

  GST_DEBUG_OBJECT (bin, "using bus %" GST_PTR_FORMAT " to listen to children",

      bus);

  gst_bus_set_sync_handler (bus, (GstBusSyncHandler) bin_bus_handler, bin);

  bin->priv->asynchandling = DEFAULT_ASYNC_HANDLING;

}

static void

gst_bin_dispose (GObject * object)

{

  GstBin *bin = GST_BIN (object);

  GstBus **child_bus_p = &bin->child_bus;

  GstClock **provided_clock_p = &bin->provided_clock;

  GstElement **clock_provider_p = &bin->clock_provider;

  GST_CAT_DEBUG_OBJECT (GST_CAT_REFCOUNTING, object, "dispose");

  gst_object_replace ((GstObject **) child_bus_p, NULL);

  gst_object_replace ((GstObject **) provided_clock_p, NULL);

  gst_object_replace ((GstObject **) clock_provider_p, NULL);

  while (bin->children) {

    gst_bin_remove (bin, GST_ELEMENT_CAST (bin->children->data));

  }

  if (G_UNLIKELY (bin->children != NULL)) {

    g_critical ("could not remove elements from bin %s",

        GST_STR_NULL (GST_OBJECT_NAME (object)));

  }