You are viewing a plain text version of this content. The canonical link for it is here.
Posted to proton@qpid.apache.org by Ken Giusti <kg...@redhat.com> on 2013/07/10 17:59:35 UTC
Q: how to drain a link (via the engine api)
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?
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?
thanks,
-K
Re: Q: how to drain a link (via the engine api)
Posted by Rafael Schloming <rh...@alum.mit.edu>.
On Wed, Jul 10, 2013 at 2:35 PM, Ken Giusti <kg...@redhat.com> wrote:
> Hi Rafi, see inline:
>
> ----- Original Message -----
> > From: "Rafael Schloming" <rh...@alum.mit.edu>
> > To: proton@qpid.apache.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 <kg...@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?
>
No, I don't think so. All you would care about as a receiver is that the
credit of the sender has dropped to zero. That way you know there won't be
anymore incoming messages from that sender unless you issue more credit.
>
>
> >
> > >
> > > 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.
>
We should probably fix that.
--Rafael
Re: Q: how to drain a link (via the engine api)
Posted by Ken Giusti <kg...@redhat.com>.
Hi Rafi, see inline:
----- Original Message -----
> From: "Rafael Schloming" <rh...@alum.mit.edu>
> To: proton@qpid.apache.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 <kg...@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.
>
> --Rafael
>
--
-K
Re: Q: how to drain a link (via the engine api)
Posted by Rafael Schloming <rh...@alum.mit.edu>.
On Wed, Jul 10, 2013 at 11:59 AM, Ken Giusti <kg...@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.
>
> 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. 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.
--Rafael