GNOME Bugzilla – Bug 641363
GInitable documentation isn't clear about that finalize is called on error case
Last modified: 2011-02-08 04:36:16 UTC
Created attachment 179997 [details] [review] Patch that improves the documentation In case the GInitable's initialization doesn't succeed and the error gets set, it's not clear from the documentation that finalize is called. It's important for the developer to understand that finalize is called because that means that he most ensure that his finalize implementation must handle halfway initialized instances. For example this wouldn't work right : public class Test : Object, Initable { Object object1, object2; void this_thows_error () throws Error () { throw new Error (); } // This would be translated to g_initable_new public Test (Cancellable c) throws Error { object1 = new Something(); this_thows_error (); object2 = new Something(); } ~Test () { object1.unref(); object2.unref(); } } This would work right: public class Test : Object, Initable { Object object1 = null, object2 = null; void this_thows_error () throws Error () { throw new Error (); } // This would be translated to g_initable_new public Test (Cancellable c) throws Error { object1 = new Something(); this_thows_error (); object2 = new Something(); } ~Test () { if (object1 != null) object1.unref(); if (object2 != null) object2.unref(); } }
Review of attachment 179997 [details] [review]: ::: gio/ginitable.c @@ +44,3 @@ * g_initable_new() directly, or indirectly via a foo_thing_new() wrapper. * This will call g_initable_init() under the cover, returning %NULL and + * setting a %GError on failure, at which point the finalize function will probably looks better like "setting a %GError on failure (at which point the finalize function will be called)." @@ +50,3 @@ * exceptions the binding could check for objects implemention %GInitable * during normal construction and automatically initialize them, throwing + * an exception on failure, at which point the finalize function will be only needs to be said once
Created attachment 179998 [details] [review] Improvement for previous patch based on Ryan's comments
Not only finalize() would get called, also dispose(). The halfway initialized object would get g_object_unref()-ed with all the things it implies.
(In reply to comment #3) > Not only finalize() would get called, also dispose(). The halfway initialized > object would get g_object_unref()-ed with all the things it implies. Is this something you think should be stated in the documentation? Any preference on how to word that in the documentation? Perhaps "(at which point the instance is unreferenced)." ? Note that the pseudo code in the original report isn't intended to be Vala (in Vala the pseudo would in fact be wrong).
(In reply to comment #4) > (In reply to comment #3) > > Not only finalize() would get called, also dispose(). The halfway initialized > > object would get g_object_unref()-ed with all the things it implies. > > > Is this something you think should be stated in the documentation? Any > preference on how to word that in the documentation? > > Perhaps "(at which point the instance is unreferenced)." ? > I understand it better with that wording, yes... although maybe its just myself
Created attachment 180055 [details] [review] Same patch, but with "unreference" as wording, for Aleksander's suggestion I'm not marking 17998 as obsolete, I'll let the maintainer decide which one to pick.