API: add gst_update_registry() (#391296).

Original commit message from CVS:
* docs/gst/gstreamer-sections.txt:
* gst/gst.c: (load_plugin_func), (scan_and_update_registry),
(init_post), (gst_deinit), (gst_update_registry):
* gst/gst.h:
API: add gst_update_registry() (#391296).
* tests/check/Makefile.am:
* tests/check/gst/gstregistry.c:
* tests/check/gst/.cvsignore:
Simple unit test for the above.

ChangeLog

@@ -1,3 +1,16 @@
+2007-01-08  Tim-Philipp Müller  <tim at centricular dot net>
+
+	* docs/gst/gstreamer-sections.txt:
+	* gst/gst.c: (load_plugin_func), (scan_and_update_registry),
+	(init_post), (gst_deinit), (gst_update_registry):
+	* gst/gst.h:
+	  API: add gst_update_registry() (#391296).
+
+	* tests/check/Makefile.am:
+	* tests/check/gst/gstregistry.c:
+	* tests/check/gst/.cvsignore:
+	  Simple unit test for the above.
+
 2007-01-08  Tim-Philipp Müller  <tim at centricular dot net>
 
 	* gst/gstregistry.c: (gst_registry_scan_path_level):

docs/gst/gstreamer-sections.txt

@@ -29,6 +29,7 @@ gst_segtrap_is_enabled
 gst_segtrap_set_enabled
 gst_registry_fork_is_enabled
 gst_registry_fork_set_enabled
+gst_update_registry
 <SUBSECTION Private>
 GST_QUARK
 GstQuarkId

gst/gst.c

@@ -499,8 +499,6 @@ load_plugin_func (gpointer data, gpointer user_data)
       GST_WARNING ("Failed to load plugin: \"%s\"", filename);
     }
   }
-
-  g_free (data);
 }
 
 static void
@@ -651,10 +649,8 @@ scan_and_update_registry (GstRegistry * default_registry,
     GST_INFO ("Scanning plugin path: \"%s\"", (gchar *) l->data);
     /* CHECKME: add changed |= here as well? */
     gst_registry_scan_path (default_registry, (gchar *) l->data);
-    g_free (l->data);
   }
-  g_list_free (plugin_paths);
-  plugin_paths = NULL;
+  /* keep plugin_paths around in case a re-scan is forced later on */
 
   /* GST_PLUGIN_PATH specifies a list of directories to scan for
    * additional plugins.  These take precedence over the system plugins */
@@ -961,12 +957,10 @@ init_post (GOptionContext * context, GOptionGroup * group, gpointer data,
     return FALSE;
 #endif /* GST_DISABLE_REGISTRY */
 
-  /* if we need to preload plugins */
-  if (preload_plugins) {
+  /* if we need to preload plugins, do so now */
   g_slist_foreach (preload_plugins, load_plugin_func, NULL);
-    g_slist_free (preload_plugins);
-    preload_plugins = NULL;
-  }
+  /* keep preload_plugins around in case a re-scan is forced later on */
+
 #ifndef GST_DISABLE_TRACE
   _gst_trace_on = 0;
   if (_gst_trace_on) {
@@ -1174,6 +1168,14 @@ gst_deinit (void)
     return;
   }
 
+  g_slist_foreach (preload_plugins, (GFunc) g_free, NULL);
+  g_slist_free (preload_plugins);
+  preload_plugins = NULL;
+
+  g_list_foreach (plugin_paths, (GFunc) g_free, NULL);
+  g_list_free (plugin_paths);
+  plugin_paths = NULL;
+
   clock = gst_system_clock_obtain ();
   gst_object_unref (clock);
   gst_object_unref (clock);
@@ -1307,3 +1309,55 @@ gst_registry_fork_set_enabled (gboolean enabled)
   _gst_enable_registry_fork = enabled;
 #endif /* HAVE_FORK */
 }
+
+
+/**
+ * gst_update_registry:
+ *
+ * Forces GStreamer to re-scan its plugin paths and update the default
+ * plugin registry.
+ *
+ * Applications will almost never need to call this function, it is only
+ * useful if the application knows new plugins have been installed (or old
+ * ones removed) since the start of the application (or, to be precise, the
+ * first call to gst_init()) and the application wants to make use of any
+ * newly-installed plugins without restarting the application.
+ *
+ * Applications should assume that the registry update is neither atomic nor
+ * thread-safe and should therefore not have any dynamic pipelines running
+ * (including the playbin and decodebin elements) and should also not create
+ * any elements or access the GStreamer registry while the update is in
+ * progress.
+ *
+ * Note that this function may block for a significant amount of time.
+ *
+ * Returns: %TRUE if the registry has been updated successfully (does not
+ *          imply that there were changes), otherwise %FALSE.
+ *
+ * Since: 0.10.12
+ */
+gboolean
+gst_update_registry (void)
+{
+  gboolean res = FALSE;
+
+#ifndef GST_DISABLE_REGISTRY
+  GError *err = NULL;
+
+  res = ensure_current_registry (&err);
+  if (err) {
+    GST_WARNING ("registry update failed: %s", err->message);
+    g_error_free (err);
+  } else {
+    GST_LOG ("registry update succeeded");
+  }
+
+  if (preload_plugins) {
+    g_slist_foreach (preload_plugins, load_plugin_func, NULL);
+  }
+#else
+  GST_WARNING ("registry update failed: %s", "registry disabled");
+#endif /* GST_DISABLE_REGISTRY */
+
+  return res;
+}

gst/gst.h

@@ -91,6 +91,8 @@ void            gst_segtrap_set_enabled         (gboolean enabled);
 gboolean        gst_registry_fork_is_enabled    (void);
 void            gst_registry_fork_set_enabled   (gboolean enabled);
 
+gboolean        gst_update_registry (void);
+
 G_END_DECLS
 
 #endif /* __GST_H__ */

tests/check/Makefile.am

@@ -50,6 +50,7 @@ REGISTRY_CHECKS =				\
 	gst/gstghostpad				\
 	gst/gstplugin				\
 	gst/gstquery				\
+	gst/gstregistry				\
 	gst/gstutils				\
 	generic/sinks				\
 	elements/fakesink			\

tests/check/gst/.gitignore

@@ -16,6 +16,7 @@ gstobject
 gstpad
 gstpipeline
 gstplugin
+gstregistry
 gstsegment
 gststructure
 gstsystemclock

tests/check/gst/gstregistry.c

@@ -0,0 +1,205 @@
+/* GStreamer unit tests for the plugin registry
+ *
+ * Copyright (C) 2006 Tim-Philipp Müller <tim centricular net>
+ *
+ * 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.
+ */
+
+#ifdef HAVE_CONFIG_H
+# include <config.h>
+#endif
+
+#include <gst/check/gstcheck.h>
+#include <string.h>
+
+static gint
+plugin_name_cmp (GstPlugin * a, GstPlugin * b)
+{
+  const gchar *name_a = gst_plugin_get_name (a);
+  const gchar *name_b = gst_plugin_get_name (b);
+
+  return strcmp (name_a, name_b);
+}
+
+
+static void
+print_plugin (const gchar * marker, GstRegistry * registry, GstPlugin * plugin)
+{
+  const gchar *name;
+  GList *features, *f;
+
+  name = gst_plugin_get_name (plugin);
+
+  GST_DEBUG ("%s: plugin %p %d %s", marker, plugin,
+      GST_OBJECT_REFCOUNT (plugin), name);
+
+  features = gst_registry_get_feature_list_by_plugin (registry, name);
+  for (f = features; f != NULL; f = f->next) {
+    GstPluginFeature *feature;
+
+    feature = GST_PLUGIN_FEATURE (f->data);
+
+    GST_LOG ("%s:    feature: %p %s", marker, feature,
+        gst_plugin_feature_get_name (feature));
+  }
+  gst_plugin_feature_list_free (features);
+}
+
+GST_START_TEST (test_registry_update)
+{
+  GstPluginFeature *old_identity, *new_identity;
+  GstPluginFeature *old_pipeline, *new_pipeline;
+  GstRegistry *registry;
+  GList *plugins_before, *plugins_after, *l;
+
+  registry = gst_registry_get_default ();
+  fail_unless (registry != NULL);
+  ASSERT_OBJECT_REFCOUNT (registry, "default registry", 1);
+
+  /* refcount should still be 1 the second time */
+  registry = gst_registry_get_default ();
+  fail_unless (registry != NULL);
+  ASSERT_OBJECT_REFCOUNT (registry, "default registry", 1);
+
+  old_identity = gst_registry_lookup_feature (registry, "identity");
+  fail_unless (old_identity != NULL, "Can't find plugin feature 'identity'");
+
+  old_pipeline = gst_registry_lookup_feature (registry, "pipeline");
+  fail_unless (old_pipeline != NULL, "Can't find plugin feature 'pipeline'");
+
+  /* plugins should have a refcount of 2: the registry holds one reference,
+   * and the other one is ours for the list */
+  plugins_before = gst_registry_get_plugin_list (registry);
+  for (l = plugins_before; l; l = l->next) {
+    GstPlugin *plugin;
+
+    plugin = GST_PLUGIN (l->data);
+
+    print_plugin ("before1", registry, plugin);
+
+    ASSERT_OBJECT_REFCOUNT (plugin, "plugin", 2);
+  }
+
+  fail_unless (gst_update_registry () != FALSE, "registry update failed");
+
+  GST_LOG (" -----------------------------------");
+  GST_LOG ("          registry updated          ");
+  GST_LOG (" -----------------------------------");
+
+  /* static plugins should have the same refcount as before (ie. 2), whereas
+   * file-based plugins should have been replaced by a newly-created objects
+   * (when reading the updated registry.xml file), so there should be only one
+   * reference left for those, and that's ours */
+  for (l = plugins_before; l; l = l->next) {
+    GstPlugin *plugin;
+
+    plugin = GST_PLUGIN (l->data);
+
+    print_plugin ("before2", registry, plugin);
+
+    if (gst_plugin_get_filename (plugin)) {
+      /* file-based plugin */
+      ASSERT_OBJECT_REFCOUNT (plugin, "plugin", 1);
+    } else {
+      /* static plugin */
+      ASSERT_OBJECT_REFCOUNT (plugin, "plugin", 2);
+    }
+  }
+
+  GST_LOG (" -----------------------------------");
+
+  plugins_after = gst_registry_get_plugin_list (registry);
+  for (l = plugins_after; l; l = l->next) {
+    GstPlugin *plugin;
+
+    plugin = GST_PLUGIN (l->data);
+
+    print_plugin ("after  ", registry, plugin);
+
+    /* file-based plugins should have a refcount of 2 (one for the registry,
+     * one for us for the list), static plugins should have one of 3 (one for
+     * the registry, one for the new list and one for the old list).
+     * This implicitly also makes sure that all static plugins are the same
+     * objects as they were before and that all non-static ones have been
+     * replaced by new objects */
+    if (gst_plugin_get_filename (plugin)) {
+      ASSERT_OBJECT_REFCOUNT (plugin, "plugin", 2);
+    } else {
+      ASSERT_OBJECT_REFCOUNT (plugin, "plugin", 3);
+    }
+  }
+
+  /* check that we still have all plugins in the new list that we had before */
+  for (l = plugins_after; l; l = l->next) {
+    GstPlugin *plugin;
+
+    plugin = GST_PLUGIN (l->data);
+
+    fail_unless (g_list_find_custom (plugins_before, plugin,
+            (GCompareFunc) plugin_name_cmp) != NULL,
+        "Plugin %s is in new list but not in old one?!",
+        gst_plugin_get_name (plugin));
+  }
+  for (l = plugins_before; l; l = l->next) {
+    GstPlugin *plugin;
+
+    plugin = GST_PLUGIN (l->data);
+    fail_unless (g_list_find_custom (plugins_after, plugin,
+            (GCompareFunc) plugin_name_cmp) != NULL,
+        "Plugin %s is in old list but not in new one?!",
+        gst_plugin_get_name (plugin));
+  }
+
+  new_identity = gst_registry_lookup_feature (registry, "identity");
+  fail_unless (new_identity != NULL, "Can't find plugin feature 'identity'");
+  fail_unless (old_identity != new_identity, "Old and new 'identity' feature "
+      "should be different but are the same object");
+
+  ASSERT_OBJECT_REFCOUNT (old_identity, "old identity feature after update", 1);
+
+  new_pipeline = gst_registry_lookup_feature (registry, "pipeline");
+  fail_unless (new_pipeline != NULL, "Can't find plugin feature 'pipeline'");
+  fail_unless (old_pipeline == new_pipeline, "Old and new 'pipeline' feature "
+      "objects should be the same, but are different objects");
+
+  gst_plugin_list_free (plugins_before);
+  plugins_before = NULL;
+  gst_plugin_list_free (plugins_after);
+  plugins_after = NULL;
+  registry = NULL;
+
+  gst_object_unref (old_identity);
+  gst_object_unref (new_identity);
+  gst_object_unref (old_pipeline);
+  gst_object_unref (new_pipeline);
+}
+
+GST_END_TEST;
+
+static Suite *
+registry_suite (void)
+{
+  Suite *s = suite_create ("registry");
+  TCase *tc_chain = tcase_create ("general");
+
+  suite_add_tcase (s, tc_chain);
+
+  tcase_add_test (tc_chain, test_registry_update);
+
+  return s;
+}
+
+GST_CHECK_MAIN (registry);