Add a README file illustrating the desired API

README

@@ -0,0 +1,80 @@
+== 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}" }
+
+    msg = my_own_magic_builder_method(arg1, arg2)
+    api.send_message(msg) {|m| puts m.inspect }
+    result = api.sync_send_message(msg) # Blocks until a response comes back
+
+    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.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>