[Gstreamer-bugs] [Bug 109857] New - GStreamer application development manual encourages incorrect g_error() usage

[bugzilla-daemon at widget.gnome.org]

Please do not reply to this email- if you want to comment on the bug, go to the
URL shown below and enter your comments there.

http://bugzilla.gnome.org/show_bug.cgi?id=109857

Changed by dilinger at voxel.net.

--- shadow/109857	Thu Apr  3 03:35:42 2003
+++ shadow/109857.tmp.13528	Thu Apr  3 03:35:42 2003
@@ -0,0 +1,58 @@
+Bug#: 109857
+Product: GStreamer
+Version: cvs
+OS: Linux
+OS Details: 
+Status: NEW   
+Resolution: 
+Severity: minor
+Priority: Normal
+Component: don't know
+AssignedTo: gstreamer-maint at bugzilla.gnome.org                            
+ReportedBy: dilinger at voxel.net               
+QAContact: gstreamer-maint at bugzilla.gnome.org
+TargetMilestone: 0.6.x
+URL: 
+Summary: GStreamer application development manual encourages incorrect g_error() usage
+
+This has been bugging me while reading the documentation.  A lot of the
+examples have code like (taken from chap. 19):
+
+int 
+main (int argc, char *argv[]) 
+{
+  GstElement *pipeline, *src, *demux;
+
+  gst_init (&argc, &argv);
+
+  pipeline = gst_pipeline_new ("pipeline");
+  g_return_val_if_fail (pipeline != NULL, -1);
+
+
+According to
+http://developer.gnome.org/doc/API/2.0/glib/glib-Error-Reporting.html:
+"If the programmer has screwed up, then you should use g_warning(),
+g_return_if_fail(), g_assert(), g_error(), or some similar facility.
+(Incidentally, remember that the g_error() function should only be used for
+programming errors, it should not be used to print any error reportable via
+GError.)"
+
+In other words, g_return_val_if_fail() should be used for programmer checks
+(ie, at the beginning of functions, to ensure an argument that was passed
+was not NULL), not runtime errors.  gst_pipeline_new() (well,
+gst_element_factory_make) may return NULL; this is a valid return value,
+according to the API docs.  It is not a programmer error, but rather, a
+runtime error (running out of memory, unable to load a plugin/module, etc).
+ Things like that would normally use GError (if they desire details of the
+failure).
+
+To encourage usage of g_return_val_if_fail() for such situations is a very
+bad idea; programmers will later on have to unlearn techiques they've been
+taught from the gst docs.  In place of g_return_val_if_fail(), i'd suggest
+something similar to
+if (pipeline == NULL) {
+    g_printerr("could not allocate pipeline!");
+    return -1;
+}
+
+I'll submit patches if you agree.