From fe20af8eaeff0a1d6f0b5ed6f1439a35fce33d38 Mon Sep 17 00:00:00 2001
From: =?utf8?q?Tim-Philipp=20M=C3=BCller?= <tim@centricular.net>
Date: Wed, 8 Mar 2006 14:30:40 +0000
Subject: [PATCH] docs/manual/advanced-dataaccess.xml: Add some very very basic
 error checking.

Original commit message from CVS:
* docs/manual/advanced-dataaccess.xml:
Add some very very basic error checking.
* docs/pwg/appendix-checklist.xml:
Some updates to the list of things to check when writing an element.
---
 ChangeLog                           |  8 ++++++
 docs/manual/advanced-dataaccess.xml | 21 +++++++++++++++
 docs/pwg/appendix-checklist.xml     | 51 +++++++++++++++++++++++++++++--------
 3 files changed, 69 insertions(+), 11 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index 8a81555..7580665 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,11 @@
+2006-03-08  Tim-Philipp Müller  <tim at centricular dot net>
+
+	* docs/manual/advanced-dataaccess.xml:
+	  Add some very very basic error checking.
+
+	* docs/pwg/appendix-checklist.xml:
+	  Some updates to the list of things to check when writing an element.
+
 2006-03-08  Wim Taymans  <wim@fluendo.com>
 
 	* docs/design/part-element-transform.txt:
diff --git a/docs/manual/advanced-dataaccess.xml b/docs/manual/advanced-dataaccess.xml
index f1e5743..222a9ec 100644
--- a/docs/manual/advanced-dataaccess.xml
+++ b/docs/manual/advanced-dataaccess.xml
@@ -76,9 +76,23 @@ main (gint   argc,
   /* build */
   pipeline = gst_pipeline_new ("my-pipeline");
   src = gst_element_factory_make ("videotestsrc", "src");
+  if (src == NULL)
+    g_error ("Could not create 'videotestsrc' element");
+
   filter = gst_element_factory_make ("capsfilter", "filter");
+  g_assert (filer != NULL); /* should always exist */
+
   csp = gst_element_factory_make ("ffmpegcolorspace", "csp");
+  if (csp == NULL)
+    g_error ("Could not create 'ffmpegcolorspace' element");
+
   sink = gst_element_factory_make ("xvimagesink", "sink");
+  if (sink == NULL) {
+    sink = gst_element_factory_make ("ximagesink", "sink");
+    if (sink == NULL)
+      g_error ("Could not create neither 'xvimagesink' nor 'ximagesink' element");
+  }
+
   gst_bin_add_many (GST_BIN (pipeline), src, filter, csp, sink, NULL);
   gst_element_link_many (src, filter, csp, sink, NULL);
   filtercaps = gst_caps_new_simple ("video/x-raw-rgb",
@@ -98,6 +112,13 @@ main (gint   argc,
 
   /* run */
   gst_element_set_state (pipeline, GST_STATE_PLAYING);
+
+  /* wait until it's up and running or failed */
+  if (gst_element_get_state (pipeline, NULL, NULL, -1) == GST_STATE_CHANGE_FAILURE) {
+    g_error ("Failed to go into PLAYING state");
+  }
+
+  g_print ("Running ...\n");
   g_main_loop_run (loop);
 
   /* exit */
diff --git a/docs/pwg/appendix-checklist.xml b/docs/pwg/appendix-checklist.xml
index 9c1de58..503031f 100644
--- a/docs/pwg/appendix-checklist.xml
+++ b/docs/pwg/appendix-checklist.xml
@@ -92,6 +92,29 @@ gst_myelement_class_init (GstMyelementClass *klass)
           option <command>--gst-debug=myelement:5</command>.
         </para>
       </listitem>
+      <listitem>
+        <para>
+          Elements should use GST_DEBUG_FUNCPTR when setting pad functions or
+          overriding element class methods, for example:
+          <programlisting>
+gst_pad_set_event_func (myelement->srcpad,
+    GST_DEBUG_FUNCPTR (my_element_src_event));
+          </programlisting>
+          This makes debug output much easier to read later on.
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          Elements that are aimed for inclusion into one of the GStreamer
+          modules should ensure consistent naming of the element name,
+          structures and function names. For example, if the element type is
+          GstYellowFooDec, functions should be prefixed with
+          gst_yellow_foo_dec_ and the element should be registered
+          as 'yellowfoodec'. Separate words should be separate in this scheme,
+          so it should be GstFooDec and gst_foo_dec, and not GstFoodec and
+          gst_foodec.
+        </para>
+      </listitem>
     </itemizedlist>
   </sect1>
 
@@ -109,21 +132,27 @@ gst_myelement_class_init (GstMyelementClass *klass)
       </listitem>
       <listitem>
         <para>
-          All elements that are event-aware (their
-          <classname>GST_ELEMENT_EVENT_AWARE</classname> flag is set)
-          should implement event handling for <emphasis>all</emphasis>
-          events, either specifically or using
-          <function>gst_pad_event_default ()</function>. Elements that
-          you should handle specifically are the interrupt event, in
-          order to properly bail out as soon as possible if state is
-          changed. Events may never be dropped unless specifically
-          intended.
+          Elements should make sure they forward events they do not
+          handle with gst_pad_event_default (pad, event) instead of
+          just dropping them. Events should never be dropped unless
+          specifically intended.
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          Elements should make sure they forward queries they do not
+          handle with gst_pad_query_default (pad, query) instead of
+          just dropping them.
         </para>
       </listitem>
       <listitem>
         <para>
-          Loop-based elements should always implement event handling,
-          in order to prevent hangs (infinite loop) on state changes.
+          Elements should use gst_pad_get_parent() in event and query
+          functions, so that they hold a reference to the element while they
+          are operating. Note that gst_pad_get_parent() increases the
+          reference count of the element, so you must be very careful to call
+          gst_object_unref (element) before returning from your query or
+          event function, otherwise you will leak memory.
         </para>
       </listitem>
     </itemizedlist>
-- 
2.7.4