Hi Rafi, see inline:
----- Original Message -----
> From: "Rafael Schloming" <r...@alum.mit.edu>
> To: firstname.lastname@example.org
> Sent: Wednesday, July 10, 2013 12:38:21 PM
> Subject: Re: Q: how to drain a link (via the engine api)
> On Wed, Jul 10, 2013 at 11:59 AM, Ken Giusti <kgiu...@redhat.com> wrote:
> > Hi,
> > AMQP 1.0 defines a way to force a sending link to exhaust its credit via a
> > drain flag in the Flow frame (see the flow control section in the spec).
> > Hate to admit my ignorance, but how does one properly drain a link using
> > the Proton engine api?
> > From what I can tell (using the proton-c api here), the application
> > initiates the drain by calling pn_link_drain() for a given link:
> > pn_link_drain( myLink, X )
> > How does the application know when the drain has completed? My guess is
> > that the drain can be considered complete when the pn_link_credit() call
> > returns zero (no more credit) - is that correct?
> Almost, pn_link_credit() would return the local view of the credit, what we
> actually need here is to add a pn_link_remote_credit() call which is what
> you would use.
Would I have to check that both are zero in order to ensure the drain has
completed at both ends?
> > Furthermore, it appears that then engine api requires the sending
> > application acknowledge the drain request by calling pn_link_drained() on
> > the sending link. But I don't see an engine interface that notifies the
> > application that a drain has been requested for the link.
> > Are we missing a "get drain flag" api call for the sender link?
> We could add that certainly, although it's not strictly speaking necessary.
> We've said to date that the sender should simply always call
> pn_link_drained() when there are no more messages available and the
> implementation of the engine will do the appropriate thing depending on the
> mode of the link.
Aha! I did not realize that was the intended usage of that method. That makes
perfect sense now. BTW, messenger.c (my by default reference model for engine
use) does not call pn_link_drained() at all.
> The application itself doesn't need to know/care about
> the drain flag, simply notify the engine whenever the supply of messages is
> exhausted. Obviously if there is some burden/overhead/etc associated with
> the application knowing when the supply of messages is exhausted then that
> would be good reason to add visibility to the drain flag, but so far it
> doesn't seem to have been an issue.