On 12.07.2018 21:45, Eduardo Habkost wrote: > The documentation for QOM is not clear about who owns references > to objects (i.e. who is responsible for calling object_unref() > later). > > This is important considering there are a few inconsistencies in > the API (e.g. callers of object_new() need to call object_unref() > later, but callers of object_new_with_props() must not do it). > > Update the documentation so that every mention of object > references also mention who exactly owns the reference. > > Signed-off-by: Eduardo Habkost <ehabk...@redhat.com> > --- > include/qom/object.h | 73 +++++++++++++++++++++++++------------------- > 1 file changed, 42 insertions(+), 31 deletions(-) > > diff --git a/include/qom/object.h b/include/qom/object.h > index f3d2308d56..08a1bbba7d 100644 > --- a/include/qom/object.h > +++ b/include/qom/object.h > @@ -376,7 +376,7 @@ typedef void (ObjectUnparent)(Object *obj); > * ObjectFree: > * @obj: the object being freed > * > - * Called when an object's last reference is removed. > + * Called when an object's last reference is dropped using object_unref(). > */ > typedef void (ObjectFree)(void *obj); > > @@ -601,8 +601,8 @@ struct InterfaceClass > * @typename: The name of the type of the object to instantiate. > * > * This function will initialize a new object using heap allocated memory. > - * The returned object has a reference count of 1, and will be freed when > - * the last reference is dropped. > + * The returned object has a reference count of 1, and the reference will be > + * owned by the caller. > * > * Returns: The newly allocated and instantiated object. > */ > @@ -617,8 +617,8 @@ Object *object_new(const char *typename); > * @...: list of property names and values > * > * This function will initialize a new object using heap allocated memory. > - * The returned object has a reference count of 1, and will be freed when > - * the last reference is dropped. > + * The returned object has a reference count of 1, and the reference will > + * be owned by the caller.
That's the description of object_new_with_props here already, isn't it? So the reference will be owned by the parent object, not by the caller. > * The @id parameter will be used when registering the object as a > * child of @parent in the composition tree. > @@ -652,8 +652,8 @@ Object *object_new(const char *typename); > * </programlisting> > * </example> > * > - * The returned object will have one stable reference maintained > - * for as long as it is present in the object hierarchy. > + * The returned object will have one reference, <emphasis>owned by the > + * parent object</emphasis> (not by the caller). ... and then this information here is somewhat redundant. I suggest to remove one of the two spots. Thomas
