On 02/13/2011 12:08 PM, Anthony Liguori wrote:
Hi,
In my QAPI branch[1], I've now got almost every existing QMP command
converted with (hopefully) all of the hard problems solved. There is
only one remaining thing to attack before posting for inclusion and
that's events. Here's my current thinking about what to do.
Events in QMP Today
QMP events are asynchronous messages. They are not tied explicitly to
any type of context, do not have a well defined format, and are have
no mechanism to mask or filter events. As of right now, we have
somewhere around a dozen events.
Goals of QAPI
1) Make all interfaces consumable in C such that we can use the
interfaces in QEMU
2) Make all interfaces exposed through a library using code generation
from static introspection
3) Make all interfaces well specified in a formal schema
Proposal for events in QAPI
For QAPI, I'd like to model events on the notion of signals and
slots[2]. A client would explicitly connect to a signal through a QMP
interface which would result in a slot being added that then generates
an event. Internally in QEMU, we could also connect slots to the same
signals. Since we don't have an object API in QMP, we'd use a pair of
connect/disconnect functions that had enough information to identify
the signal.
Example:
We would define QEVENT_BLOCK_IO_EVENT as:
# qmp-schema.json
{ 'BlockIOEvent': {'device': 'str', 'action': 'str', 'operation':
'str'} }
The 'Event' suffix is used to determine that the type is an event and
not a structure. This would generate the following structures for QEMU:
typedef void (BlockIOEventFunc)(const char *device, const char
*action, const char *operation, void *opaque);
One thing I'm on the fence about, is making the slot callback take a
BlockIOEvent *event as the first argument. If we did this, the signals
would be compatible with GObject signals.
It's hard to map that to a libqmp though so I'm not sure.
Regards,
Anthony Liguori
typedef struct BlockIOEvent {
/* contents are private */
} BlockIOEvent;
/* Connect a slot to a BlockIOEvent signal and return a handle to the
connection */
int block_io_event_connect(BlockIOEvent *event, BlockIOEventFunc *cb,
void *opaque);
/* Signal any connect slots of a BlockIOEvent */
void block_io_event_signal(BlockIOEvent *event, const char *device,
const char *action, const char *operation);
/* Disconnect a slot from a signal based on a connection handle */
void block_io_event_disconnect(BlockIOEvent *event, int handle);
In the case of BlockIOEvent, this is a global signal that is not tied
to any specific object so there would be a global BlockIOEvent object
within QEMU.
From a QMP perspective, we would have the following function in the
schema:
[ 'block-io-event', {}, {}, 'BlockIOEvent' ]
A function definition that returns an Event is a signal accessor.
Within QEMU, we implement a signal accessor like so:
BlockIOEvent *qmp_block_io_event(Error **errp)
{
return &global_block_io_event;
}
For QMP and libqmp, signal accessors are handled specially. A signal
accessor is expanded into two QMP functions:
[ 'block-io-event-connect', {}, {}, 'str' ]
[ 'block-io-event-disconnect', {'tag' : 'str'}, {}, 'none' ]
Connect returns a handle to the connection as an opaque string.
Disconnect takes that handle. Both functions will also take any
arguments that the signal accessor takes and under the cover uses the
signal accessor to access the object.
In libqmp, the following interfaces will be generated:
int libqmp_block_io_event_connect(QmpSession *sess, BlockIOEventFunc
*cb, void *opaque, Error **errp);
void libqmp_block_io_event_disconnect(QmpSession *sess, int handle,
Error **errp);
Again, if the signal accessor takes additional arguments, they will be
passed here.
All existing events will be converted to signals with signal accessors
that take no arguments. However, BlockIOEvent is a good example of a
signal that we'll add a new version of that takes a 'const char
*device' as an argument for the signal accessor. This will let
clients register for block io events on specific block devices.
Backwards Compatibility
Right now, QMP events to not have any type of context information
which means that there's no way to communicate the connection handle.
We'll solve this by adding a new 'tag' field to events that are
registered through one of the connect interfaces. Since this is only
present on events registered through this new interface, backwards
compatibility is preserved.
Upon initial connection, we'll treat all existing signals as having a
'default signal connection'. We'll introduce a new QMP command that
can be executed while in capabilities mode to disconnect default
signal connections. The effect is that new clients can use the
explicit register/unregister interface while old clients will continue
to see the old style events.
We'll deprecate the 'default signal connections' and make sure to
never add a new one post 0.15. Old clients will need to be updated to
explicitly register for events.
Another Example
Here's an example of BlockDeviceEvent, the successor to BlockIOEvent.
It makes use of signal accessor arguments and QAPI enumeration support:
# qmp-schema.json
{ 'BlockDeviceAction': [ 'report', 'stop', 'none' ] }
{ 'BlockDeviceOperation': [ 'read', 'write' ] }
{ 'BlockDeviceActionReason': [ 'nospc', 'io', 'other' ] }
{ 'BlockDeviceEvent': { 'action': 'BlockDeviceAction', 'operation':
'BlockDeviceOperation', 'reason': 'BlockDeviceActionReason' } }
[ 'block-device-event', { 'device': 'str' }, {}, 'BlockDeviceEvent' ]
# qemu/block.c (Signal Accessor)
BlockDeviceEvent *qmp_block_device_event(const char *str, Error **errp)'
# qemu/qmp-types.h (Generated QMP interfaces)
typedef enum BlockDeviceAction {
BDA_REPORT = 0,
BDA_STOP,
BDA_NONE,
} BlockDeviceAction;
typedef enum BlockDeviceOperation {
BDO_READ = 0,
BDO_WRITE,
} BlockDeviceOperation;
typedef enum BlockDeviceActionReason {
BDAR_NOSPC = 0,
BDAR_IO,
BDAR_OTHER,
} BlockDeviceActionReason;
typedef struct BlockDeviceEvent {
/* private */
} BlockDeviceEvent;
typedef void (BlockDeviceEventFunc)(BlockDeviceAction action,
BlockDeviceOperation operator, BlockDeviceActionReason reason);
int block_device_event_connect(BlockDeviceEvent *event,
BlockDeviceEventFunc *cb, void *opaque);
void block_device_event_disconnect(BlockDeviceEvent *event, int handle);
# qemu/libqmp.h (Generated libqmp interfaces)
int libqmp_block_device_event_connect(QmpSession *sess, const char
*device, BlockDeviceEventFunc *cb, void *opaque);
void libqmp_block_device_event_disconnect(QmpSession *sess, const char
*device, int handle);
Regards,
Anthony Liguori
[1] http://repo.or.cz/w/qemu/aliguori.git/shortlog/refs/heads/glib
[2] http://en.wikipedia.org/wiki/Signals_and_slots
