On Thu, Sep 14, 2017 at 04:33:34PM +0100, Stefan Hajnoczi wrote:
> On Thu, Sep 14, 2017 at 03:50:35PM +0800, Peter Xu wrote:
> > diff --git a/docs/devel/qapi-code-gen.txt b/docs/devel/qapi-code-gen.txt
> > index 61fa167..47d16bb 100644
> > --- a/docs/devel/qapi-code-gen.txt
> > +++ b/docs/devel/qapi-code-gen.txt
> > @@ -665,6 +665,16 @@ allowed to run out-of-band can also be introspected
> > using
> > query-qmp-schema command. Please see the section "Client JSON
> > Protocol introspection" for more information.
> >
> > +To execute a command in out-of-band way, we need to specify the
> > +"control" field in the request, with "run-oob" set to true. Example:
> > +
> > + => { "execute": "command-support-oob",
> > + "arguments": { ... },
> > + "control": { "run-oob": true } }
> > + <= { "return": { } }
> > +
> > +Without it, even the commands that supports out-of-band execution will
> > +still be run in-band.
>
> Is there a more relevant place to document QMP run-oob behavior than the
> "How to use the QAPI code generator document"?
I agree, but I don't really know it. :(
Markus, could you provide a hint?
>
> > @@ -3963,6 +3964,16 @@ static void handle_qmp_command(JSONMessageParser
> > *parser, GQueue *tokens,
> > req_obj->id = id;
> > req_obj->req = req;
> >
> > + if (qmp_is_oob(req)) {
> > + /*
> > + * Trigger fast-path to handle the out-of-band request, by
> > + * executing the command directly in parser.
> > + */
> > + trace_monitor_qmp_cmd_out_of_band(qobject_get_str(req_obj->id));
> > + monitor_qmp_dispatch_one(req_obj);
> > + return;
> > + }
>
> A "fast-path" is a performance optimization. OOB is not a performance
> optimization, it changes the semantics of command execution. Please
> mention the semantics of OOB command execution instead.
I'll remove the "fast-path" wording and try to think out something
better than this comment. After I know a good place to document, I
can put it there as well. Thanks,
--
Peter Xu
