ObjectPropertyInfo design (was: [PATCH v7 00/65] Hi)

[Markus Armbruster <armbru@redhat.com>]

Marc-André's series evolves ObjectPropertyInfo and ObjectPropertyValue:
it adds member @qapi-type and changes many values of member @type.

I'd like to take a step back and discuss design.  I trimmed Cc:
accordingly.


= The current interface

qom-list returns information on an object's properties, one
ObjectPropertyInfo per property.

qom-list-properties returns information on properties an instance of a
type is known to have[*], one ObjectPropertyInfo per property.

qom-list-get returns information on the properties of several objects,
one ObjectPropertyValue per property.

ObjectPropertyInfo and ObjectPropertyValue provide @name and @type.

ObjectPropertyInfo additionally provides @description and
@default-value, both optional.

ObjectPropertyValue additionally provides optional @value, absent when
the property cannot be read.

If ObjectPropertyValue was an extension of ObjectPropertyInfo, then
qom-list-get would be a strictly more powerful version of qom-list.
It isn't.  However, I think the information lost when moving from
qom-list to qom-list-get is not useful:

* @description is rarely present (I see under 15% in a quick test).  The
  description text is commonly misleading for QMP.  For instance, qdev
  bool properties have description "on/off".  The possible values are
  actually JSON false and true.

* @default-value can be useful with qom-list-properties, which operates
  on types.  I doubt it is with qom-list, which operates on objects.

Let's pretend @description doesn't exist, and @default-value exists only
with qom-list-properties.

This makes qom-list-get strictly more powerful than qom-list, so let's
further pretend qom-list doesn't exist.


= Simplified interface for the sake of discussion

qom-list-properties returns information on properties an instance of a
type is known to have[*]: @name, @type, and maybe @default-value.

qom-list-get returns information on the properties of several objects:
@name, @type, and maybe @value.


= The meaning of @type

Three cases:

1. For a child property (created with object_property_add_child() etc.),
   @type is "child<T>", where T is the child's QOM type.

2. For a link property (created with object_class_property_add_link()
   etc.), @type is "link<T>", where T is the target's QOM type.

3. For other properties, @type can be anything.  We commonly use QAPI
   type names (occasionally misspelled), and also "well-known" (but
   undocumented) non-QAPI names for primitive types.  Every now and
   then, developers get lazy and use values like "list", or creative and
   use values like "guest statistics".  Nobody has gotten sufficiently
   masochistic to use values starting with "child<" or "link<" so far,
   although nothing would stop that.

Cases 1 and 2 go against the QAPI/QMP design maxim "don't encode stuff
in strings".

Case 3 is is hard to use for anything.  You're forced into stupid and
brittle hardcoding.

Marc-André's work adds a new optional member @qapi_type that refers to a
QAPI type in the output of query-qmp-schema.  It's present for a large
subset of case 3.  When it's present, @type should not be used.

It also cleans up many crap cases of 3, but without making it robust.  I
understand this isn't something the series tries to do, it's just
something that's easier to do than not to do.  If it creates
compatibility problems, we have to not do it.  I hope it doesn't.


= Can we do better?

What information are we trying to convey?  Four cases:

1. Child property: the child's QOM type

2. Link property: the target's QOM type

3. QAPI-backed property: the property's QAPI type

4. Other property: we have nothing useful to offer

Case 4 should go away eventually.

How would we encode this in QAPI on a green field?  With a union, of
course:

    { 'enum': 'ObjectPropertyKind',
      'data': [ 'child', 'link', 'qapi', 'other'] }

    { 'struct': 'ObjectPropertyInfoLink',
      'data': { 'qom-type': 'str' } }

    { 'struct': 'ObjectPropertyInfoQAPI',
      'data': { 'qapi-type': 'str' } }

    { 'union': 'ObjectProperty...',
      'base': { 'kind': 'ObjectPropertyKind',
                ... more ... },
      'discriminator': 'kind',
      'data': {
          'child': 'ObjectPropertyInfoLink',
          'link': 'ObjectPropertyInfoLink',
          'qapi': 'ObjectPropertyInfoQAPI' } }

To make this a compatible evolution of ObjectPropertyInfo, we need
... more ... to be

                'type': 'str',
                '*description': 'str'
                '*default-value': 'any',

Sadly, we need to duplicate the union for ObjectPropertyValue.  There,
... more ... needs to be

                'type': 'str',
                '*value': 'any'

We should deprecate @type.  I'd also deprecate @description.

Thoughts?


[*] It may have more; see the note in the doc comment of
qom-list-properties.