[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: [Qemu-devel] [RFC 1/3] qom: Document reference count ownership rules
From: |
Thomas Huth |
Subject: |
Re: [Qemu-devel] [RFC 1/3] qom: Document reference count ownership rules |
Date: |
Fri, 13 Jul 2018 11:07:15 +0200 |
User-agent: |
Mozilla/5.0 (X11; Linux x86_64; rv:52.0) Gecko/20100101 Thunderbird/52.8.0 |
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 <address@hidden>
> ---
> 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