You are viewing a plain text version of this content. The canonical link for it is here.

Posted to dev@qpid.apache.org by Alan Conway <ac...@redhat.com> on 2008/05/23 16:59:23 UTC

C++ sync/async client API (was Re: sync needed in fanout example?)

Change of plan, requesting feedback:

MOTIVATION: as per Andrews comment on the bugzilla, sync and async
versions of a command should have _different return values_. A sync
command should return void or a result object.  An async command must
return a Future object (Completion or TypedResult) that allows the
caller to wait for the command to complete. The current API returns
futures regardless, which makes the sync API needlessly clumsy.

The follow proposal is
  - just as conveneient as an optional async parameter for bot mostly-sync and 
mostly-async users.
  - requires no more example changes than an async param.
  - sync API has normal C++ return values, not Futures.
  - slightly asymmetric (favouring sync), hard to use async commands by accident.


// Summary of API:

class Session {
   void executionSync();
   MessageAcquireResult messageAcquire(const SequenceSet& transfers=SequenceSet());
   // ... sync ops.

   AsyncSession& async;
};

class AsyncSession {
   Completion executionSync();
   TypedResult<MessageAcquireResult> messageAcquire(const SequenceSet& 
transfers=SequenceSet());

   Session& sync;
};

// === Example, mostly sync:

Session s ...;
s.declare(...);
ExchangeQueryResult ex = s.exchangeQuery(...);
for (lots of messages) {
   s.async.transfer(...);
}
s.sync();
// Now we know all messages are sent.


// === Example mostly async:

Session s ...;
AsyncSession as = s.async;
as.declare()
Completion bind = as.bind(); // allow waiting for specific command
TypedResult<ExchangeQueryResult> ex = as.exchangeQuery(...);
...
bind.wait(); // Wait for bind command
ExchangeQueryResult ex = ex.get(); // Waits for query to return

Re: C++ sync/async client API (was Re: sync needed in fanout example?)

Posted by Jonathan Robie <jo...@redhat.com>.

Alan Conway wrote:
> Carl Trieloff wrote:
>> Alan Conway wrote:
>>> Change of plan, requesting feedback:
>>>
>>> MOTIVATION: as per Andrews comment on the bugzilla, sync and async
>>> versions of a command should have _different return values_. A sync
>>> command should return void or a result object.  An async command must
>>> return a Future object (Completion or TypedResult) that allows the
>>> caller to wait for the command to complete. The current API returns
>>> futures regardless, which makes the sync API needlessly clumsy.
>>>
>>> The follow proposal is
>>>  - just as conveneient as an optional async parameter for bot 
>>> mostly-sync and mostly-async users.
>>>  - requires no more example changes than an async param.
>>>  - sync API has normal C++ return values, not Futures.
>>>  - slightly asymmetric (favouring sync), hard to use async commands 
>>> by accident.
>>>
>>>
>>> // Summary of API:
>>>
>>> class Session {
>>>   void executionSync();
>>>   MessageAcquireResult messageAcquire(const SequenceSet& 
>>> transfers=SequenceSet());
>>>   // ... sync ops.
>>>
>>>   AsyncSession& async;
>>> };
>>>
>>> class AsyncSession {
>>>   Completion executionSync();
>>>   TypedResult<MessageAcquireResult> messageAcquire(const 
>>> SequenceSet& transfers=SequenceSet());
>>>
>>>   Session& sync;
>>> };
>>>
>>> // === Example, mostly sync:
>>>
>>> Session s ...;
>>> s.declare(...);
>>> ExchangeQueryResult ex = s.exchangeQuery(...);
>>> for (lots of messages) {
>>>   s.async.transfer(...);
>>> }
>>> s.sync();
>>> // Now we know all messages are sent.
>>>
>>>
>>> // === Example mostly async:
>>>
>>> Session s ...;
>>> AsyncSession as = s.async;
>>> as.declare()
>>> Completion bind = as.bind(); // allow waiting for specific command
>>> TypedResult<ExchangeQueryResult> ex = as.exchangeQuery(...);
>>> ...
>>> bind.wait(); // Wait for bind command
>>> ExchangeQueryResult ex = ex.get(); // Waits for query to return
>>>
>>
>> looks nice -- what is the impact to existing client code?
>> Carl.
>
> 1. Remove the SYNC/ASYNC paramemter from newSession
>   Session s = c.newSession(SYNC) --> s = c.newSession()
>
> 2. If you want mostly-sync, then fix the async calls:
>  s.transfer(...) --> async(s).transfer(...)
>
> 3. If you want mostly-async then modify the newsession and fix sync 
> calls:
>  AsyncSession s = c.newSession()
>  s.foo(...) --> sync(s).foo
>


I like this.

Jonathan