Added non-optional enum { SYNC, ASYNC } parameter to newSession.

Updated API doc in client/SessionBase.h


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

4 files changed, 49 insertions, 13 deletions

diff --git a/cpp/src/qpid/client/Connection.cpp b/cpp/src/qpid/client/Connection.cpp
index b2508f4a24..26113c1254 100644
--- a/cpp/src/qpid/client/Connection.cpp
+++ b/cpp/src/qpid/client/Connection.cpp
@@ -70,12 +70,15 @@ void Connection::open(
 }
 
 void Connection::openChannel(Channel& channel) {
-    channel.open(newSession());
+    channel.open(newSession(ASYNC));
 }
 
-Session_0_10 Connection::newSession(uint32_t detachedLifetime) {
+Session_0_10 Connection::newSession(SynchronousMode sync,
+                                    uint32_t detachedLifetime)
+{
     shared_ptr<SessionCore> core(
         new SessionCore(impl, ++channelIdCounter, max_frame_size));
+    core->setSync(sync);
     impl->addSession(core);
     core->open(detachedLifetime);
     return Session_0_10(core);
diff --git a/cpp/src/qpid/client/Connection.h b/cpp/src/qpid/client/Connection.h
index 053949a51b..e6bfbddef6 100644
--- a/cpp/src/qpid/client/Connection.h
+++ b/cpp/src/qpid/client/Connection.h
@@ -39,7 +39,6 @@ namespace qpid {
  */
 namespace client {
 
-
 /**
  * \defgroup clientapi Application API for an AMQP client
  */
@@ -135,7 +134,7 @@ class Connection
      * that the broker may discard the session state. Default is 0,
      * meaning the session cannot be resumed.
      */
-    Session_0_10 newSession(uint32_t detachedLifetime=0);
+    Session_0_10 newSession(SynchronousMode sync, uint32_t detachedLifetime=0);
 
     /**
      * Resume a suspendded session. A session may be resumed
diff --git a/cpp/src/qpid/client/SessionBase.cpp b/cpp/src/qpid/client/SessionBase.cpp
index 9b6123cbc4..0e1fa67bda 100644
--- a/cpp/src/qpid/client/SessionBase.cpp
+++ b/cpp/src/qpid/client/SessionBase.cpp
@@ -29,8 +29,14 @@ SessionBase::~SessionBase() {}
 SessionBase::SessionBase(shared_ptr<SessionCore> core) : impl(core) {}
 void SessionBase::suspend() { impl->suspend(); }
 void SessionBase::close() { impl->close(); }
+
 void SessionBase::setSynchronous(bool isSync) { impl->setSync(isSync); }
+void SessionBase::setSynchronous(SynchronousMode m) { impl->setSync(m); }
 bool SessionBase::isSynchronous() const { return impl->isSync(); }
+SynchronousMode SessionBase::getSynchronous() const {
+    return SynchronousMode(impl->isSync());
+}
+
 Execution& SessionBase::getExecution() { return impl->getExecution(); }
 Uuid SessionBase::getId() const { return impl->getId(); }
 framing::FrameSet::shared_ptr SessionBase::get() { return impl->get(); }
diff --git a/cpp/src/qpid/client/SessionBase.h b/cpp/src/qpid/client/SessionBase.h
index 87c0892b61..3565145bb9 100644
--- a/cpp/src/qpid/client/SessionBase.h
+++ b/cpp/src/qpid/client/SessionBase.h
@@ -45,6 +45,32 @@ using framing::MethodContent;
 using framing::SequenceNumberSet;
 using framing::Uuid;
 
+/** \defgroup clientapi Synchronous mode of a session.
+ * 
+ * SYNC means that Session functions do not return until the remote
+ * broker has confirmed that the command was executed. 
+ * 
+ * ASYNC means that the client sends commands asynchronously, Session
+ * functions return immediately.
+ *
+ * ASYNC mode gives better performance for high-volume traffic, but
+ * requires some additional caution:
+ * 
+ * Session functions return immediately. If the command causes an
+ * exception on the broker, the exception will be thrown on a
+ * <em>later</em> function call. 
+ *
+ * If you need to notify some extenal agent that some actions have
+ * been taken (e.g. binding queues to exchanages), you must call
+ * Session::sync() first, to ensure that all the commands are complete.
+ *
+ * You can freely switch between modes by calling Session::setSynchronous()
+ * 
+ * @see Session::sync(), Session::setSynchronous()
+ */
+enum SynchronousMode { SYNC=true, ASYNC=false };
+
+
 /**
  * Basic session operations that are not derived from AMQP XML methods.
  */
@@ -61,20 +87,20 @@ class SessionBase
     Uuid getId() const;
 
     /**
-     * In synchronous mode, the session sets the sync bit on every
-     * command and waits for the broker's response before returning.
-     * Note this gives lower throughput than non-synchronous mode.
+     * In synchronous mode, wait for the broker's response before
+     * returning. Note this gives lower throughput than asynchronous
+     * mode.
      *
-     * In non-synchronous mode commands are sent without waiting
+     * In asynchronous mode commands are sent without waiting
      * for a respose (you can use the returned Completion object
      * to wait for completion.)
      * 
-     *@param if true set the session to synchronous mode, else
-     * set it to non-synchronous mode.
+     * @see SynchronousMode
      */
-    void setSynchronous(bool isSync);
-
+    void setSynchronous(SynchronousMode mode);
+    void setSynchronous(bool set);
     bool isSynchronous() const;
+    SynchronousMode getSynchronous() const;
 
     /**
      * Suspend the session, can be resumed on a different connection.
@@ -85,8 +111,10 @@ class SessionBase
     /** Close the session */
     void close();
 
-    /** Synchronize with the broker. Wait for all commands issued so far in
+    /**
+     * Synchronize with the broker. Wait for all commands issued so far in
      * the session to complete.
+     * @see SynchronousMode
      */
     void sync();