Additional API documentation around sync vs. async sessions.

git-svn-id: https://svn.apache.org/repos/asf/incubator/qpid/trunk@660562 13f79535-47bb-0310-9956-ffa450edef68

3 files changed, 45 insertions, 1 deletions

diff --git a/qpid/cpp/src/qpid/client/Completion.h b/qpid/cpp/src/qpid/client/Completion.h
index 19d5b31777..22cc70607a 100644
--- a/qpid/cpp/src/qpid/client/Completion.h
+++ b/qpid/cpp/src/qpid/client/Completion.h
@@ -29,6 +29,11 @@
 namespace qpid {
 namespace client {
 
+/** 
+ * Returned by asynchronous commands that do not return any result.
+ * You can use this to wait for an individual command to complete.
+ * \clientapi
+ */
 class Completion
 {
 protected:
@@ -40,6 +45,7 @@ public:
 
     Completion(Future f, shared_ptr<SessionImpl> s) : future(f), session(s) {}
 
+    /** Wait for the command to complete */
     void wait()
     {
         future.wait(*session);
diff --git a/qpid/cpp/src/qpid/client/Connection.h b/qpid/cpp/src/qpid/client/Connection.h
index eb63802161..81a7ffa008 100644
--- a/qpid/cpp/src/qpid/client/Connection.h
+++ b/qpid/cpp/src/qpid/client/Connection.h
@@ -108,7 +108,39 @@ class Connection
     /**
      * Create a new session on this connection.  Sessions allow
      * multiple streams of work to be multiplexed over the same
-     * connection.
+     * connection. The returned Session provides functions to send
+     * commands to the broker.
+     *
+     * Session functions are synchronous. In other words, a Session
+     * function will send a command to the broker and does not return
+     * until it receives the broker's response confirming the command
+     * was executed.
+     *
+     * AsyncSession provides asynchronous versions of the same
+     * functions.  These functions send a command to the broker but do
+     * not wait for a response. 
+     *
+     * You can convert a Session s into an AsyncSession as follows:
+     * @code
+     *  #include <qpid/client/AsyncSession.h>
+     *  AsyncSession as = async(s);
+     * @endcode
+     *
+     * You can execute a single command asynchronously will a Session s
+     * like ths:
+     * @code
+     *  async(s).messageTransfer(...);
+     * @endcode
+     * 
+     * Using an AsyncSession is faster for sending large numbers of
+     * commands, since each command is sent as soon as possible
+     * without waiting for the previous command to be confirmed.
+     *
+     * However with AsyncSession you cannot assume that a command has
+     * completed until you explicitly synchronize. The simplest way to
+     * do this is to call Session::sync() or AsyncSession::sync().
+     * Both of these functions wait for the broker to confirm all
+     * commands issued so far on the session.
      *
      *@param name: A name to identify the session. @see qpid::SessionId
      * If the name is empty (the default) then a unique name will be
diff --git a/qpid/cpp/src/qpid/client/TypedResult.h b/qpid/cpp/src/qpid/client/TypedResult.h
index 0b36be9716..79df9d0e69 100644
--- a/qpid/cpp/src/qpid/client/TypedResult.h
+++ b/qpid/cpp/src/qpid/client/TypedResult.h
@@ -27,6 +27,11 @@
 namespace qpid {
 namespace client {
 
+/**
+ * Returned by asynchronous commands that return a result.
+ * You can use get() to wait for completion and get the result value.
+ * \clientapi
+ */
 template <class T> class TypedResult : public Completion
 {
     T result;
@@ -35,6 +40,7 @@ template <class T> class TypedResult : public Completion
 public:
     TypedResult(Future f, shared_ptr<SessionImpl> s) : Completion(f, s), decoded(false) {}
 
+    /** Wait for command to complete and return the result */
     T& get() 
     {
         if (!decoded) {