== 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("127.0.0.1", 4440) do |api|

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

    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
  end

You can also do this perfectly safely:

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

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

Or, indeed, this:

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

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:

http://wiki.qemu.org/QMP
http://wiki.qemu.org/Features/QAPI

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>