add doc for asynchronous aspects

doc/source/examples.rst

@@ -79,9 +79,12 @@ Wait for a result
 
 Wait for workflow completion, and retrieve output::
 
-  >>> run.waitResult()
+  >>> res = run.waitResult()
   {'out': <vmw.vco.components.TypedValue object at 0x1b7a690>}
 
+  >>> print res['out'].value()
+  foo
+
 Cancel a workflow
 -----------------
 
@@ -108,3 +111,47 @@ requiring more interactions::
 
   >>> run.waitResult()
   {}
+
+Asynchronous examples
+=====================
+
+Here is a quick scenario to demonstrate how to use this API in an asynchronous
+way::
+
+  from vmw.vco.client import Client
+  from twisted.internet import reactor
+
+  def dummy():
+      c = Client(url='http://vco-gae.appspot.com:80/vmware-vmo-webcontrol/webservice',
+                 username='admin', password='admin', async=True)
+
+      def _display(val):
+          print val
+
+      c.getWorkflowForId("94db6b5e-cabf-11df-9ffb-002618405f6e")\
+       .addCallback(lambda wf: wf.execute({'in': 'foo'}))\
+       .addCallback(lambda run: run.WaitResult())\
+       .addCallback(lambda res: _display(res[out]))
+
+  dummy()
+  reactor.run()
+
+
+Alternately, using a Monocle-like syntax::
+
+  from vmw.vco.client import Client
+  from twisted.internet import reactor
+  from twisted.internet.defer import inlineCallbacks as _o
+
+  @_o
+  def dummy():
+      c = Client(url='http://vco-gae.appspot.com:80/vmware-vmo-webcontrol/webservice',
+                 username='admin', password='admin', async=True)
+
+      wf = yield c.getWorkflowForId("94db6b5e-cabf-11df-9ffb-002618405f6e")
+      run = yield wf.execute({'in': 'foo'})
+      res = yield run.WaitResult()
+      print res[out]
+
+  dummy()
+  reactor.run()

doc/source/intro.rst

@@ -13,6 +13,8 @@ in a Python environment, as well as a useful testing environment.
 The use cases covered by vmw.vco and this documentation are:
 
 * Communicate with a KL.next vCO using the :doc:`SOAP interface <soap>`.
+* Provide a consistent API for synchronous and asynchronous applications
+  (`Twisted <http://www.twistedmatric.com/>`_ is supported)
 * Write tests targetting vCO.
 * Provide enough information to extend vmw.vco in such a way that the above use
   cases remain consistent.