Re: [PATCH 02/12] qom: New container_create()

[Peter Xu <peterx@redhat.com>]

On Thu, Nov 21, 2024 at 02:20:44PM +0100, Markus Armbruster wrote:
> Peter Xu <peterx@redhat.com> writes:
> 
> > To move towards explicit creations of containers, starting that by
> > providing a helper for creating container objects.
> >
> > Signed-off-by: Peter Xu <peterx@redhat.com>
> > ---
> >  include/qom/object.h | 12 ++++++++++++
> >  qom/container.c      | 18 +++++++++++++++---
> >  2 files changed, 27 insertions(+), 3 deletions(-)
> >
> > diff --git a/include/qom/object.h b/include/qom/object.h
> > index 3ba370ce9b..41ef53241e 100644
> > --- a/include/qom/object.h
> > +++ b/include/qom/object.h
> > @@ -2033,6 +2033,18 @@ int object_child_foreach_recursive(Object *obj,
> >   */
> >  Object *container_get(Object *root, const char *path);
> >  
> > +
> > +/**
> > + * container_create:
> > + * @root: root of the object to create the new container
> > + * @name: name of the new container
> 
> Is this the name of the property of @root to hold the new container?
> Peeking ahead to the implementation... yes.
> 
> > + *
> > + * Create a container object under @root with @name.
> > + *
> > + * Returns: the newly created container object.
> > + */
> > +Object *container_create(Object *root, const char *name);
> 
> No function in this file is named like FOO_create().  Hmm.
> 
> Compare:
> 
>    /**
>     * object_property_try_add_child:
>     * @obj: the object to add a property to
>     * @name: the name of the property
>     * @child: the child object
>     * @errp: pointer to error object
>     *
>     * Child properties form the composition tree.  All objects need to be a child
>     * of another object.  Objects can only be a child of one object.
>     *
>     * There is no way for a child to determine what its parent is.  It is not
>     * a bidirectional relationship.  This is by design.
> 
> Aside: this is nonsense.  While you're not supposed to simply use
> obj->parent (it's documented as private), you can still get the child's
> canonical path with object_get_canonical_path(), split off its last
> component to get the parent's canonical path, then use
> object_resolve_path() to get the parent.
> 
>     *
>     * The value of a child property as a C string will be the child object's
>     * canonical path. It can be retrieved using object_property_get_str().
>     * The child object itself can be retrieved using object_property_get_link().
>     *
>     * Returns: The newly added property on success, or %NULL on failure.
>     */
> 
> What about
> 
>    /**
>     * object_property_add_new_container:
>     * @obj: the parent object
>     * @name: the name of the parent object's property to add
>     *
>     * Add a newly created container object to a parent object.
>     *
>     * Returns: the newly created container object.  Its reference count
>     * is 1, and the reference is owned by the parent object.
>     */

Sure, this may indeed align better with the rest function names.

> 
> > +
> >  /**
> >   * object_property_help:
> >   * @name: the name of the property
> > diff --git a/qom/container.c b/qom/container.c
> > index cfec92a944..da657754a4 100644
> > --- a/qom/container.c
> > +++ b/qom/container.c
> > @@ -24,6 +24,20 @@ static void container_register_types(void)
> >      type_register_static(&container_info);
> >  }
> >  
> > +Object *container_create(Object *obj, const char *name)
> > +{
> > +    Object *child = object_new(TYPE_CONTAINER);
> > +
> > +    object_property_add_child(obj, name, child);
> > +    /*
> > +     * Simplify the caller by always drop the refcount directly here, as
> > +     * containers are normally never destroyed after created anyway.
> > +     */
> > +    object_unref(child);
> 
> Do we still need the comment if we document the reference count in the
> function comment?

Probably not.  I'll drop this comment while taking above suggestion.

Thanks,

-- 
Peter Xu