Re: [Qemu-devel] [RFC 6/6] docs: Document QMP event rate limiting

[Markus Armbruster <armbru@redhat.com>]

Eric Blake <eblake@redhat.com> writes:

> On 09/25/2015 08:00 AM, Markus Armbruster wrote:
>> Signed-off-by: Markus Armbruster <armbru@redhat.com>
>> ---
>>  docs/qmp/qmp-events.txt | 12 ++++++++++++
>>  docs/qmp/qmp-spec.txt   |  5 +++++
>>  2 files changed, 17 insertions(+)
>
> Obvious rebase implied if your other patch to s,docs/qmp/,docs/, goes
> through.
>
>> 
>> diff --git a/docs/qmp/qmp-events.txt b/docs/qmp/qmp-events.txt
>> index d92cc48..d2f1ce4 100644
>> --- a/docs/qmp/qmp-events.txt
>> +++ b/docs/qmp/qmp-events.txt
>> @@ -28,6 +28,8 @@ Example:
>>      "data": { "actual": 944766976 },
>>      "timestamp": { "seconds": 1267020223, "microseconds": 435656 } }
>>  
>> +Note: this event is rate-limited.
>
> Marc-Andre's series moves all the documentation into the .json files;
> maybe we could make it easier by just listing rate-limiting in the .json
> files for now, rather than having to churn through which file(s)
> document things.

As long as qmp-events.txt exists, shouldn't we document rate-limiting
there?

> Do we want to document that VSERPORT_CHANGE rate limiting is per-"id"?

I did:

    @@ -632,6 +640,8 @@ Example:
         "data": { "id": "channel0", "open": true },
         "timestamp": { "seconds": 1401385907, "microseconds": 422329 } }

    +Note: this event is rate-limited separately for each "id".
    +
     WAKEUP
     ------

>> +++ b/docs/qmp/qmp-spec.txt
>> @@ -175,6 +175,11 @@ The format of asynchronous events is:
>>  For a listing of supported asynchronous events, please, refer to the
>>  qmp-events.txt file.
>>  
>> +Some events are rate-limited to at most one per second.  If more
>> +events arrive within one second, all but the last one are dropped, and
>> +the last one is delayed.  Rate-limiting applies to each kind of event
>> +separately.
>
> Do we also want to document that limits might be further tuned according
> to other elements of the event, with VSERPORT_CHANGE "id" as the example?

You need to interpret "each kind of event" in a sufficiently fuzzy
manner :)

Seriously, I'm open to suggestions for better language here.