qemu/qapi
Eric Blake f545504420 qapi-introspect: Document lack of sorting
qapi-code-gen.txt already claims that types, commands, and
events share a common namespace; set this in stone by further
documenting that our introspection output will never have
collisions with the same name tied to more than one meta-type.

Our largest QMP enum currently has 125 values, our largest
object type has 27 members, and the mean for each is less than
10.  These sizes are small enough that the per-element overhead
of O(log n) binary searching probably outweighs the speed
possible with direct O(n) linear searching (a better algorithm
with more overhead will only beat a leaner naive algorithm only
as you scale to larger input sizes).

Arguably, the overall SchemaInfo array could be sorted by name;
there, we currently have 531 entities, large enough for a binary
search to be faster than linear.  However, remember that we have
mutually-recursive types, which means there is no topological
ordering that will allow clients to learn all information about
that type in a single linear pass; thus clients will want to do
random access over the data, and they will probably read the
introspection output into a hashtable for O(1) lookup rather
than O(log n) binary searching, at which point, pre-sorting our
introspection output doesn't help the client.

It doesn't help that sorting can be subjective if you introduce
locales into the mix (I'm not experienced enough with Python
to know for sure, but at least it looks like it defaults to
sorting in the C locale even when run under a different locale).
And while our current introspection output is deterministic
(because we visit entities in a sorted order), we may want
to change that order in the future (such as using OrderedDict
to stick to .json declaration order).

For these reasons, we simply document that clients should not
rely on any particular order of items in introspection output.
And since it is now a documented part of the contract, we have
the freedom to later rearrange output if needed, without
worrying about breaking well-written clients.

Signed-off-by: Eric Blake <eblake@redhat.com>
Message-Id: <1446791754-23823-13-git-send-email-eblake@redhat.com>
[Commit message tweaked]
Signed-off-by: Markus Armbruster <armbru@redhat.com>
2015-11-10 08:10:28 +01:00
..
block-core.json blockdev: Allow creation of BDS trees without BB 2015-10-23 18:18:22 +02:00
block.json qapi: add missing @ 2015-10-08 19:46:47 +03:00
common.json qapi: Drop inline nested struct in query-version 2015-05-05 18:39:02 +02:00
crypto.json crypto: introduce new base module for TLS credentials 2015-09-15 14:47:37 +01:00
event.json migration: create migration event 2015-07-07 14:54:55 +02:00
introspect.json qapi-introspect: Document lack of sorting 2015-11-10 08:10:28 +01:00
Makefile.objs rename parse_enum_option to qapi_enum_parse and make it public 2014-09-08 11:12:43 +01:00
opts-visitor.c utils: rename strtosz to use qemu prefix 2015-09-25 12:04:41 +02:00
qapi-dealloc-visitor.c qapi: Introduce a first class 'any' type 2015-09-21 09:56:49 +02:00
qapi-util.c qom: Make enum string tables const-correct 2015-06-19 18:42:18 +02:00
qapi-visit-core.c qapi: Introduce a first class 'any' type 2015-09-21 09:56:49 +02:00
qmp-dispatch.c qerror: Clean up QERR_ macros to expand into a single string 2015-06-22 18:20:40 +02:00
qmp-event.c qapi/qmp-event.c: Don't manually include os-win32.h/os-posix.h 2015-08-19 16:29:53 +01:00
qmp-input-visitor.c qstring: Make conversion from QObject * accept null 2015-10-29 14:34:45 +01:00
qmp-output-visitor.c qapi: Introduce a first class 'any' type 2015-09-21 09:56:49 +02:00
qmp-registry.c qemu-ga: Extend 'guest-info' command to expose flag 'success-response' 2013-10-10 14:52:37 -05:00
rocker.json qmp/hmp: add rocker device support 2015-06-12 13:42:17 +01:00
string-input-visitor.c qerror: Clean up QERR_ macros to expand into a single string 2015-06-22 18:20:40 +02:00
string-output-visitor.c Include qapi/qmp/qerror.h exactly where needed 2015-06-22 18:20:41 +02:00
trace.json qapi: Use 'struct' instead of 'type' in schema 2015-05-05 18:39:01 +02:00