[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[Qemu-devel] [PATCH v2 16/25] qmp: update qmp-spec about async capabilit
From: |
Marc-André Lureau |
Subject: |
[Qemu-devel] [PATCH v2 16/25] qmp: update qmp-spec about async capability |
Date: |
Wed, 18 Jan 2017 20:03:23 +0400 |
Signed-off-by: Marc-André Lureau <address@hidden>
---
docs/qmp-spec.txt | 48 +++++++++++++++++++++++++++++++++++++++++-------
1 file changed, 41 insertions(+), 7 deletions(-)
diff --git a/docs/qmp-spec.txt b/docs/qmp-spec.txt
index f8b5356015..b45c0700b6 100644
--- a/docs/qmp-spec.txt
+++ b/docs/qmp-spec.txt
@@ -83,9 +83,41 @@ The greeting message format is:
2.2.1 Capabilities
------------------
-As of the date this document was last revised, no server or client
-capability strings have been defined.
+The "capabilities" member of the greeting message and qmp_capabilities
+is a json-array of json-string of the following values:
+- "async"
+
+This capability indicates asynchronous commands support.
+
+An async command is a regular client message request with the "id"
+member mandatory (see 2.3), but the reply may be delivered
+asynchronously and out of order by the server if the client supports
+it too.
+
+If both the server and the client have the "async" capability, the
+client can make requests while previous async requests are being
+processed.
+
+If the client doesn't have the "async" capability, it may still call
+an async command, and make multiple outstanding calls. In this case,
+the commands are processed in order, so the replies will also be in
+order (this is sometime called 'pipelining'). The "id" member isn't
+mandatory in this case.
+
+The client should match the replies with the "id" member associated
+with the requests.
+
+When a client is disconnected, the pending commands are not
+necessarily canceled. But the future clients will not get replies from
+commands they didn't make (they might, however, receive side-effects
+events).
+
+Note that without "async" support, a client may still receive
+asynchronous messages (or events) from the server between the time a
+request is handled by the server and the reply is received. It must
+thus be prepared to handle dispatching both events and reply after
+sending a request.
2.3 Issuing Commands
--------------------
@@ -102,10 +134,11 @@ The format for command execution is:
required. Each command documents what contents will be considered
valid when handling the json-argument
- The "id" member is a transaction identification associated with the
- command execution, it is optional and will be part of the response if
- provided. The "id" member can be any json-value, although most
+ command execution and will be part of the response if provided.
+ If "async" is negotiated (see 2.2.1), it is mandatory, optional
+ otherwise. The "id" member can be any json-value, although most
clients merely use a json-number incremented for each successive
- command
+ command.
2.4 Commands Responses
----------------------
@@ -202,11 +235,12 @@ This section provides some examples of real QMP usage, in
all of them
-------------------
S: { "QMP": { "version": { "qemu": { "micro": 50, "minor": 6, "major": 1 },
- "package": ""}, "capabilities": []}}
+ "package": ""}, "capabilities": [ "async" ]}}
3.2 Client QMP negotiation
--------------------------
-C: { "execute": "qmp_capabilities" }
+C: { "execute": "qmp_capabilities",
+ "arguments": { "capabilities": [ "async" ] } }
S: { "return": {}}
3.3 Simple 'stop' execution
--
2.11.0.295.gd7dffce1c
- [Qemu-devel] [PATCH v2 06/25] qmp: add qmp_return_is_cancelled(), (continued)
- [Qemu-devel] [PATCH v2 06/25] qmp: add qmp_return_is_cancelled(), Marc-André Lureau, 2017/01/18
- [Qemu-devel] [PATCH v2 08/25] qapi: ignore top-level 'id' field, Marc-André Lureau, 2017/01/18
- [Qemu-devel] [PATCH v2 07/25] qmp: introduce async command type, Marc-André Lureau, 2017/01/18
- [Qemu-devel] [PATCH v2 09/25] qmp: take 'id' from request, Marc-André Lureau, 2017/01/18
- [Qemu-devel] [PATCH v2 10/25] qmp: check that async command have an 'id', Marc-André Lureau, 2017/01/18
- [Qemu-devel] [PATCH v2 11/25] scripts: learn 'async' qapi commands, Marc-André Lureau, 2017/01/18
- [Qemu-devel] [PATCH v2 12/25] tests: add dispatch async tests, Marc-André Lureau, 2017/01/18
- [Qemu-devel] [PATCH v2 13/25] monitor: add 'async' capability, Marc-André Lureau, 2017/01/18
- [Qemu-devel] [PATCH v2 14/25] monitor: add !qmp pre-conditions, Marc-André Lureau, 2017/01/18
- [Qemu-devel] [PATCH v2 15/25] monitor: suspend when running async and client has no async, Marc-André Lureau, 2017/01/18
- [Qemu-devel] [PATCH v2 16/25] qmp: update qmp-spec about async capability,
Marc-André Lureau <=
- [Qemu-devel] [PATCH v2 17/25] qtest: add qtest-timeout, Marc-André Lureau, 2017/01/18
- [Qemu-devel] [PATCH v2 19/25] tests: add tests for async and non-async clients, Marc-André Lureau, 2017/01/18
- [Qemu-devel] [PATCH v2 18/25] qtest: add qtest_init_qmp_caps(), Marc-André Lureau, 2017/01/18
- [Qemu-devel] [PATCH v2 20/25] qapi: improve 'screendump' documentation, Marc-André Lureau, 2017/01/18
- [Qemu-devel] [PATCH v2 21/25] console: graphic_hw_update return true if async, Marc-André Lureau, 2017/01/18
- [Qemu-devel] [PATCH v2 22/25] console: add graphic_hw_update_done(), Marc-André Lureau, 2017/01/18
- [Qemu-devel] [PATCH v2 23/25] console: make screendump async, Marc-André Lureau, 2017/01/18