From 8b2a0de8689dffb697e436b4abf697d22bdf3caf Mon Sep 17 00:00:00 2001 From: Alan Conway Date: Tue, 27 May 2008 15:39:42 +0000 Subject: Additional API documentation around sync vs. async sessions. git-svn-id: https://svn.apache.org/repos/asf/incubator/qpid/trunk/qpid@660562 13f79535-47bb-0310-9956-ffa450edef68 --- cpp/src/qpid/client/Connection.h | 34 +++++++++++++++++++++++++++++++++- 1 file changed, 33 insertions(+), 1 deletion(-) (limited to 'cpp/src/qpid/client/Connection.h') diff --git a/cpp/src/qpid/client/Connection.h b/cpp/src/qpid/client/Connection.h index eb63802161..81a7ffa008 100644 --- a/cpp/src/qpid/client/Connection.h +++ b/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 + * 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 -- cgit v1.2.1