Eric Blake <ebl...@redhat.com> writes: > On 12/04/2014 08:56 AM, Markus Armbruster wrote: > >> >> @device is a sub-optimal name for this single parameter. Either we >> accept that and move on, or we deprecate it in favor of a new parameter >> with a better name. I guess the better name isn't worth that much >> trouble, in particular since the command name is already ugly. >> >> When @node-name is given, @device must not be given. So @device is >> mandatory *except* in the @node-name usage we retain for compatibility. >> Deprecate the usage. >> >> Command documentation could then look like this: >> >> ## >> # @block-resize >> # >> # Resize a block image while a guest is running. >> # >> # @device: the name of the block backend or node to resize (node names >> # supported since 2.3) >> # >> # @size: new image size in bytes >> # >> # Deprecated usage (since 2.3): >> # >> # @device: #optional the name of the block backend to resize >> # >> # @node-name: #optional name of the node to resize (since 2.0) >> # >> # Either @device or @node-name must be set but not both. > > But this isn't discoverable. You aren't changing whether any parameters > are optional, only enhancing the semantics of existing parameters. How > is libvirt supposed to know if qemu is old (node names have to go > through node-name) or new (node names are preferred through device)?
Good point. > Just blindly try the 'device' argument, and if it fails, fall back to an > attempt with node-name? Works, but "try interfaces one after the other until you find one that works" is a rather lame discovery technique. > On the other hand, if 'node-name' becomes the preferred interface, then > libvirt has a solution: if node-name is present (it is easy during > up-front QMP probing to determine whether 'node-name' is a recognized > optional argument or an unknown argument), then always use node-name. > As long as libvirt always names the nodes of each device (which it > should be doing, but that's a patch series for another day and another > list), then a device lookup is never needed. If 'node-name' is not > present, then only the 'device' form is supported, and libvirt can only > manage the top image of a backend (but can make that point obvious to > the end user that they should upgrade qemu for more functionality). If we deprecate @device instead of @node-name, we make the appropriate (non-deprecated) use of backend names rather than node names hard to probe. Command argument introspection could help only if it carried "deprecated" flags. Might be a good idea anyway, but command introspection is one of those nice-to-haves we can't seem to deliver. A possible alternative is our common way to cheat at probing: when probing for A is hard, probe for B, and assume support for B implies support for A. My guess that a "better name [than @device for the single parameter] isn't worth that much trouble" needs to be reevaluated with discoverability in mind. Yes, it's troublesome, but it's also easily discoverable. >> Let's get the easy case out of the way first: a query that reports only >> backend properties and not node properties can return an array where >> each element carries a backend name, like query-block does now. >> >> For queries that report node properties, we have a couple of options: >> >> * Flat array with node names >> >> Like current query-named-block-nodes. >> >> Can't report on nodes without names. Jeff's project to give all nodes >> names would moot this issue. > > I could live with this. > >> >> * Array of trees mirroring the actual node forest, >> >> Similar to current query-blockstats. >> >> Tree roots correspond to backends, and backends have names. >> >> Unfortunately, the nodes don't actually form a forest: node trees may >> be shared. To turn it into make a forest, we'd have to duplicate the >> shared trees. >> >> * Hybrid: array of trees, but named sub-trees are represented by name >> >> Like the previous one, except the recursion stops at named nodes. >> Instead of including such a sub-tree, we reference it by name, then >> add it to the array if it's not already there. > > This one seems like it might be easier for avoiding the reconstruction > of relationships; but if management doesn't already know relationships, > I'm not sure it is worth the complexity. > >> >> "Flat array" seems simplest. > > Simplest to implement. Management can't easily reconstruct the tree, > but for looking up information about a known node, iterating over the > simpler structure will be faster than trying to find a known node in a > complex structure. Tree reconstruction is possible only if all nodes have names, and the array elements refer to their children by name.
