On Thu, Nov 21, 2024 at 02:20:44PM +0100, Markus Armbruster wrote: > Peter Xu <pet...@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 <pet...@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