On 7/9/2025 4:39 AM, Markus Armbruster wrote:
Steve Sistare <steven.sist...@oracle.com> writes:
Define the qom-list-getv command, which fetches all the properties and
values for a list of paths. This is faster than qom-tree-get when
fetching a subset of the QOM tree. See qom.json for details.
Signed-off-by: Steve Sistare <steven.sist...@oracle.com>
You cover letter explains *why* we want this. Please include the
relevant parts here, so the rationale gets captured in git.
Sure, and I forgot to delete the reference to qom-tree-get:
Define the qom-list-get command, which fetches all the properties and
values for a list of paths. This is faster than qom-list plus qom-get,
especially when fetching a large subset of the QOM tree. Some managers
do so when starting a new VM, and this cost can be a substantial fraction
of start up time.
---
qapi/qom.json | 50 ++++++++++++++++++++++++++++++++++++++++++++++++++
qom/qom-qmp-cmds.c | 53 +++++++++++++++++++++++++++++++++++++++++++++++++++++
2 files changed, 103 insertions(+)
diff --git a/qapi/qom.json b/qapi/qom.json
index b133b06..c16c2dd 100644
--- a/qapi/qom.json
+++ b/qapi/qom.json
@@ -46,6 +46,34 @@
'*default-value': 'any' } }
##
+# @ObjectPropertyValue:
+#
+# @name: the name of the property
+#
+# @type: the type of the property, as described in @ObjectPropertyInfo
+#
+# @value: the value of the property. Absent when the property cannot
+# be read.
Best to consistently end the descriptions with a period.
OK.
The majority of short descriptions in this file do not end with a period,
so I inferred that was the recommended style.
+#
+# Since 10.1
+##
+{ 'struct': 'ObjectPropertyValue',
+ 'data': { 'name': 'str',
+ 'type': 'str',
+ '*value': 'any' } }
+
+##
+# @ObjectPropertiesValues:
+#
+# @properties: a list of properties.
+#
+# Since 10.1
+##
+{ 'struct': 'ObjectPropertiesValues',
+ 'data': { 'properties': [ 'ObjectPropertyValue' ] }}
+
+
+##
# @qom-list:
#
# This command will list any properties of a object given a path in
@@ -126,6 +154,28 @@
'allow-preconfig': true }
##
+# @qom-list-getv:
+#
+# List properties and their values for each object path in the input
+# list.
+#
+# @paths: The absolute or partial path for each object, as described
+# in @qom-get
John Snow's "[PATCH 00/18] QAPI: add cross-references to qapi docs"
rewrites things so they become links in generated HTML. @qom-get
beccomes `qom-get`. Please use `qom-get` to avoid the semantic
conflict.
OK. I see his pending changes in this file.
+#
+# Errors:
+# - If any path is not valid or is ambiguous
+#
+# Returns: A list of @ObjectPropertiesValues. Each element contains
+# the properties of the corresponding element in @paths.
I understand you patterned this after qom-get. It comes out like
Return:
"[""ObjectPropertiesValues""]" -- A list of
"ObjectPropertiesValues". Each element contains the properties
of the corresponding element in "paths".
in the generated manual. 'A list of "ObjectPropertiesValues"' is
redundant. John Snow's "[PATCH v5 4/4] qapi: rephrase return docs to
avoid type name" cleans up existing instances, including qom-get.
Perhaps something like "A list where each element contains information
on the properties of the object referenced by the corresponding element
in @paths." Or shorter: "A list where each element is the result for
the corresponding element of @paths".
OK, I'll use the latter.
+#
+# Since 10.1
+##
+{ 'command': 'qom-list-getv',
+ 'data': { 'paths': [ 'str' ] },
+ 'returns': [ 'ObjectPropertiesValues' ],
+ 'allow-preconfig': true }
+
+##
# @qom-set:
#
# This command will set a property from a object model path.
The schema looks good. Not entirely happy with the names. Naming is
hard! Type names are not part of the interface, so let's not worry
about them too much. The command name will be set in stone, though.
When you named the command qom-list-getv, you also had qom-list-get.
qom-list-get works on a single path, and -getv on multiple paths. The
"v" suffix feels like a natural choice among people used to C. But does
it make sense without its buddy?
How do you feel about calling it qom-list-get? qom-get-many? Other
ideas?
qom-list-get is good, as long as we never add the single-path version of the
call. No reason to IMO.
In the cover letter I will rename the existing qom-list-get to qom-list-get-one
for the purpose of describing the experiments.
diff --git a/qom/qom-qmp-cmds.c b/qom/qom-qmp-cmds.c
[...]
The C code looks good to me.
Cool.
- Steve
