Go to file
Nick Thomas 25fa6d2cbe Fix a couple of examples in the README 2011-11-13 20:57:28 +00:00
lib Add the error response type to the library 2011-11-13 20:09:55 +00:00
test/unit Add the error response type to the library 2011-11-13 20:09:55 +00:00
.gitignore Project framework + socket connector 2011-11-12 21:45:14 +00:00
LICENSE Release qmp_client under the MIT license 2011-11-13 12:01:09 +00:00
README Fix a couple of examples in the README 2011-11-13 20:57:28 +00:00
Rakefile Alter the interface presented by Connectors::Socket 2011-11-13 12:00:15 +00:00


== qmp_client

This library interfaces with a running QEMU process using the QMP protocol. It
also works with the QEMU-KVM branch.

To get a QMP socket for a QEMU process, use one of these command-line arguments:
  -qmp tcp:[host]:port[,server][,nowait][,nodelay]
  -qmp unix:path[,server][,nowait]
  -qmp stdio
  -qmp pipe:filename

The QMP protocol is still evolving, and the kinds of things you can do with it
are changing with each release. It's also currently (QEMU 0.15) impossible to
set every option available on the command line via the QMP console. However,
there are plans to make that possible, and this library will track the features
available from the server as closely as possible.

Usage example:

  QMPClient::connect_tcp("", 4440) do |api|

    api.on_event('BLOCK_IO_ERROR') do |e|
      puts "Block I/O error detected: #{e.inspect}"

    msg = api.sync_query("status") # Blocks until a response comes back
    puts "VM status: #{m.inspect}"

    api.command('eject', 'device' => 'ide1-cd0') {|m| puts "CDROM ejected" }
    api.query("status") {|m| puts "VM status now: #{m.inspect}" }

    api.wait # Blocks until no commands or queries are outstanding.

    api.command('quit') # Specifying a callback is optional

You can also do this perfectly safely:

  stopq = Queue.new
  api_outer = nil
  Thread.new do
    QMPClient::connect_tcp("", 4440) do |api_inner|
      api = api_inner

  sleep(0.1) while api_outer.nil?
  # do stuff with the api object

Or, indeed, this:

  QMPClient::connect_tcp("", 4440) do |api|
    Thread.new { }.join # use the API object in here

Callbacks are run on a thread pool; if an exception is raised on one of those
threads, the process aborts. The default thread pool size is 10. Both of these
things will be made configurable later.

More information about QMP can be found at the following locations:


Patches to fix bugs or support new functionality are welcome. To submit a patch
or report a bug, go to http://github.com/lupine/qmp_client - follow the usual
fork, commit fixes and tests, send pull request procedure for github.

The aim is to be compatible with Ruby 1.8.7 and 1.9.3 as implemented by MRI,
Rubinius and JRuby - tests and fixes to that aim are especially welcomed.

See LICENSE for copyright details.

 - Nick Thomas <nick@lupine.me.uk>