Re: example of proton documentation
On Tue, Feb 26, 2013 at 8:02 AM, Alan Conway wrote: > This is a good start! We should start a proton book so this has a place > to live. The Qpid books are in docbook under qpid/doc/book. I'm not a > huge fan of docbook but probably best to stick with it unless there's > something significantly better. > > A few comments on the content: > > On Fri, 2013-02-22 at 05:14 -0500, Michael Goulish wrote: > [snip] > > > > You can also grant 'infinite' credit by using a negative > > value as the second arg to pn_messenger_recv(). This will > > have the effect of granting 10 units of credit to every link > > on that call to pn_messenger_recv(). > > Typo, "10 units of" should be "infinite". > I wouldn't say it's infinite, it's just an unspecified amount. The implementation will attempt to manage an optimal bound based on the assumption that you will be receiving messages indefinitely. > > A single messenger, listening on a single port, may have > > many incoming links. > > Clarify - is the credit per-link or per-messenger? Also move this out of > the "infinite credit" section, it doesn't apply only to infinite credit. > Also, a single messenger may have many incoming links regardless of whether it is listening on a single port, many ports, or no ports at all. > > According to API docs recv(self, n) > > Receives up to n messages into the incoming queue of the > Messenger. This method will block until at least one message is > available or the operation times out. > > So it sounds like credit is per messenger, so it is incorrect to say > that recv "grants N units of credit to every link." > > > Credit does not drain > > -- > > > > Once granted by a call to pn_messenger_recv(), unusued credit > > on a link does not go away when control returns from > > pn_messenger_recv(). It remains at the link, and successive > > calls can increase it. > > Successive calls to what? > > Can I control the credit per link? messenger_recv sets it globally for > the messenger. What happens if I call messenger_recv again - does the > credit get reset on existing Links, or does it apply only to new links. > > Presumably credit get used up as messages arrive. Need to discuss that > and also when/how "used" credit gets "unused" - is it at > pn_messenger_get or is it delayed till the user acknowledges the > message. (How do you acknowledge a message in proton? I couldn't find > anything obvious in the API doc. The semantics of pn_messenger_recv is intended to match exactly a typical blocking read call you make to do file or socket I/O. Calling read(n) will block until at least one byte of data is available and return no more than n bytes. Likewise, calling pn_messenger_recv(n) will block until at least one message is available and it will never receive more than n messages. I don't actually know if the implementation behaves this way (I suspect it doesn't) as it depends on properly implementing drain and early on not everyone did that (including messenger itself), so it isn't a code path that's been tested much. --Rafael
Re: example of proton documentation
This is a good start! We should start a proton book so this has a place to live. The Qpid books are in docbook under qpid/doc/book. I'm not a huge fan of docbook but probably best to stick with it unless there's something significantly better. A few comments on the content: On Fri, 2013-02-22 at 05:14 -0500, Michael Goulish wrote: [snip] > > You can also grant 'infinite' credit by using a negative > value as the second arg to pn_messenger_recv(). This will > have the effect of granting 10 units of credit to every link > on that call to pn_messenger_recv(). Typo, "10 units of" should be "infinite". > A single messenger, listening on a single port, may have > many incoming links. Clarify - is the credit per-link or per-messenger? Also move this out of the "infinite credit" section, it doesn't apply only to infinite credit. According to API docs recv(self, n) Receives up to n messages into the incoming queue of the Messenger. This method will block until at least one message is available or the operation times out. So it sounds like credit is per messenger, so it is incorrect to say that recv "grants N units of credit to every link." > Credit does not drain > -- > > Once granted by a call to pn_messenger_recv(), unusued credit > on a link does not go away when control returns from > pn_messenger_recv(). It remains at the link, and successive > calls can increase it. Successive calls to what? Can I control the credit per link? messenger_recv sets it globally for the messenger. What happens if I call messenger_recv again - does the credit get reset on existing Links, or does it apply only to new links. Presumably credit get used up as messages arrive. Need to discuss that and also when/how "used" credit gets "unused" - is it at pn_messenger_get or is it delayed till the user acknowledges the message. (How do you acknowledge a message in proton? I couldn't find anything obvious in the API doc.)
Re: example of proton documentation
Jakub -- I agree with your concerns about clarity here, and I will rework the doc and send out a new version. Also, I'm not a math guy, but I have a feeling that you are correct that "infinite" is definitely not equal to 10. Or even 10 * N_LINKS. I think maybe I could choose a more appropriate word there... ( oops. ) :-)How about in the code we put: #define NOT_VERY_INFINITE10 #define KIND_OF_INFINITE 100 #define STILL_NOT_INFINITE_BUT_GETTING_WARM 1000 No. Certainly not. OK -- I'll just change that word. I'll get a new version of the doc out in an hour or so. -- Mick . - Original Message - From: "Jakub Scholz" To: proton@qpid.apache.org Sent: Monday, February 25, 2013 6:25:29 PM Subject: Re: example of proton documentation Hi Michael, I'm rather a foreigner in the land of Proton, but that point of view might make the feedback useful as well :-). As someone who didn't worked with proton much, I would probably raise following questions ... a) If I remember correctly, in (some of) the old Qpid APIs the flow control was able to work as windows based or credit based. From your description it is not entirely clear to me whether the flow control in Proton is credit or window based. You talk about credit, but afterwards you mention the dequeuing using pn_messenger_get(...) function which makes me wonder whether this call restores the credit. If it is not related to the credit, I would probably remove the last part of the chapter mentioning the pn_messenger_get() call. Since flow control is slightly more advanced topic, I would assume that the pn_messenger_get() should be explained already in previous chapters. b) Again, if I remember correctly, (some of) the old Qpid APIs allowed to specify flow control limits in messages or in bytes. You mention only limit in messages - that might immediately raise questions how can I specify the limit in bytes. I think it would be great if you can add a note that the flow control limit in bytes is not supported. c) 10 units per link doesn't really sound like infinite credit. People tend to often read only half of the documentation - many of them might stop after reading "You can also grant 'infinite' credit by using a negative value" and afterwards they will wonder why is it only 10 per link and not really infinite. I would probably also rename the chapter and/or rephrase the first sentence. d) It is not entirely clear to me, whether the "infinite credit" is then somehow auto-refreshed or whether the 10 units are consumed by the messages. e) "It remains at the link, and successive calls can increase it." ... can the credit be really only increased? Or can it be also decreased? I would suggest to mention it there even if it is not possible to decrease the credit ... just to avoid questions. f) It would be great if the typical pattern can be slightly more complex and include the refreshing of the credit with further pn_messenger_recv(...) call. g) Also, I would probably structure the chapters as 1. Controlling Message Flow with Credit, 1.1 Credit does not drain, 1.2 A typical pattern and 1.3 Infinite credit Anyway, thanks a lot for your effort ... keep the good work ... without a good documentation, it doesn't matter how good Proton is - nobody will use it. When we started with AMQP / Qpid / MRG Messaging, the documentation was pretty much useless and we had to write our own "Programming Guide" because nobody from our customers was able to even connect. It would be great if we can avoid it in the next version :-). Thanks & Regards Jakub On Fri, Feb 22, 2013 at 11:14 AM, Michael Goulish wrote: > > I wonder if anybody out there in Proton Land has an > opinion about this little piece of Proton doc. > > This is an example of the documentation I'm creating as > I use the Proton interface to > > I'd be interested to hear about > > 1. correctness > 2. clarity > 3. focus > 4. usefulness > 5. anything else that strikes you > > > I don't know what to call this -- a mini-tutorial? -- a 'topic'? -- > but in any case, I expect I will have 5 or 6 pieces like this for > the Proton Messenger doc when I'm done, so I wanted to See What You Think. > Yes, *you* ! > > > - everything below this point is the doc - > > > > > > Controlling Message Flow with Credit > = > > > To control the flow of messages into your Proton application, > use the second argument to > > pn_messenger_recv ( messenger, credit ); > > If you set credit to a positive value, it will limit the number > of messages that pn_messenger_recv enqu
Re: example of proton documentation
Hi Michael,
I'm rather a foreigner in the land of Proton, but that point of view might
make the feedback useful as well :-). As someone who didn't worked with
proton much, I would probably raise following questions ...
a) If I remember correctly, in (some of) the old Qpid APIs the flow control
was able to work as windows based or credit based. From your description it
is not entirely clear to me whether the flow control in Proton is credit or
window based. You talk about credit, but afterwards you mention
the dequeuing using pn_messenger_get(...) function which makes me wonder
whether this call restores the credit. If it is not related to the credit,
I would probably remove the last part of the chapter mentioning the
pn_messenger_get() call. Since flow control is slightly more advanced
topic, I would assume that the pn_messenger_get() should be explained
already in previous chapters.
b) Again, if I remember correctly, (some of) the old Qpid APIs allowed to
specify flow control limits in messages or in bytes. You mention only limit
in messages - that might immediately raise questions how can I specify the
limit in bytes. I think it would be great if you can add a note that the
flow control limit in bytes is not supported.
c) 10 units per link doesn't really sound like infinite credit. People tend
to often read only half of the documentation - many of them might stop
after reading "You can also grant 'infinite' credit by using a negative
value" and afterwards they will wonder why is it only 10 per link and not
really infinite. I would probably also rename the chapter and/or rephrase
the first sentence.
d) It is not entirely clear to me, whether the "infinite credit" is then
somehow auto-refreshed or whether the 10 units are consumed by the messages.
e) "It remains at the link, and successive calls can increase it." ... can
the credit be really only increased? Or can it be also decreased? I would
suggest to mention it there even if it is not possible to decrease the
credit ... just to avoid questions.
f) It would be great if the typical pattern can be slightly more complex
and include the refreshing of the credit with further
pn_messenger_recv(...) call.
g) Also, I would probably structure the chapters as 1. Controlling Message
Flow with Credit, 1.1 Credit does not drain, 1.2 A typical pattern and 1.3
Infinite credit
Anyway, thanks a lot for your effort ... keep the good work ... without a
good documentation, it doesn't matter how good Proton is - nobody will use
it. When we started with AMQP / Qpid / MRG Messaging, the documentation was
pretty much useless and we had to write our own "Programming Guide" because
nobody from our customers was able to even connect. It would be great if we
can avoid it in the next version :-).
Thanks & Regards
Jakub
On Fri, Feb 22, 2013 at 11:14 AM, Michael Goulish wrote:
>
> I wonder if anybody out there in Proton Land has an
> opinion about this little piece of Proton doc.
>
> This is an example of the documentation I'm creating as
> I use the Proton interface to
>
> I'd be interested to hear about
>
> 1. correctness
> 2. clarity
> 3. focus
> 4. usefulness
> 5. anything else that strikes you
>
>
> I don't know what to call this -- a mini-tutorial? -- a 'topic'? --
> but in any case, I expect I will have 5 or 6 pieces like this for
> the Proton Messenger doc when I'm done, so I wanted to See What You Think.
> Yes, *you* !
>
>
> - everything below this point is the doc -
>
>
>
>
>
> Controlling Message Flow with Credit
> =
>
>
> To control the flow of messages into your Proton application,
> use the second argument to
>
> pn_messenger_recv ( messenger, credit );
>
> If you set credit to a positive value, it will limit the number
> of messages that pn_messenger_recv enqueues for you on that
> call.
>
> The number you provide is a maximum. The call to pn_messenger_recv
> may also enqueue fewer messages, or none. You can learn how many
> were received with:
>
> pn_messenger_incoming ( messenger );
>
> You can then dequeue each message, one at a time, into your
> application with successive calls to
>
> pn_messenger_get ( messenger );
>
>
>
>
> A typical pattern
> ---
>
> int i, incoming;
>
> pn_messenger_recv ( messenger, credit );
> incoming = pn_messenger_incoming ( messenger );
> for ( i = 0; i < incoming; ++ i )
> {
> pn_messenger_get ( messenger, message );
> consume_message ( message );
> }
>
>
> Infinite Credit
> --
>
> You can also grant 'infinite' credit by using a negative
> value as the second arg to pn_messenger_recv(). This will
> have the effect of granting 10 units of credit to every link
> on that call to pn_messenger_recv().
>
> A single messenger, listening on a single port, may have
> many incoming links.
>
>
Re: example of proton documentation
Hi Michael,
Looks like a good start.
Where are you intending to store this documentation? Similarly, where are
you intending to publish it, e.g. as HTML and/or PDF on our web site, as a
wiki page etc?
I'm particularly interested in this topic because I'm focusing on the lower
level Engine layer at the moment and might write some documentation for it,
so I'll want it to be complementary to your Messenger docs.
Phil
On 22 February 2013 10:14, Michael Goulish wrote:
>
> I wonder if anybody out there in Proton Land has an
> opinion about this little piece of Proton doc.
>
> This is an example of the documentation I'm creating as
> I use the Proton interface to
>
> I'd be interested to hear about
>
> 1. correctness
> 2. clarity
> 3. focus
> 4. usefulness
> 5. anything else that strikes you
>
>
> I don't know what to call this -- a mini-tutorial? -- a 'topic'? --
> but in any case, I expect I will have 5 or 6 pieces like this for
> the Proton Messenger doc when I'm done, so I wanted to See What You Think.
> Yes, *you* !
>
>
> - everything below this point is the doc -
>
>
>
>
>
> Controlling Message Flow with Credit
> =
>
>
> To control the flow of messages into your Proton application,
> use the second argument to
>
> pn_messenger_recv ( messenger, credit );
>
> If you set credit to a positive value, it will limit the number
> of messages that pn_messenger_recv enqueues for you on that
> call.
>
> The number you provide is a maximum. The call to pn_messenger_recv
> may also enqueue fewer messages, or none. You can learn how many
> were received with:
>
> pn_messenger_incoming ( messenger );
>
> You can then dequeue each message, one at a time, into your
> application with successive calls to
>
> pn_messenger_get ( messenger );
>
>
>
>
> A typical pattern
> ---
>
> int i, incoming;
>
> pn_messenger_recv ( messenger, credit );
> incoming = pn_messenger_incoming ( messenger );
> for ( i = 0; i < incoming; ++ i )
> {
> pn_messenger_get ( messenger, message );
> consume_message ( message );
> }
>
>
> Infinite Credit
> --
>
> You can also grant 'infinite' credit by using a negative
> value as the second arg to pn_messenger_recv(). This will
> have the effect of granting 10 units of credit to every link
> on that call to pn_messenger_recv().
>
> A single messenger, listening on a single port, may have
> many incoming links.
>
>
>
>
> Credit does not drain
> --
>
> Once granted by a call to pn_messenger_recv(), unusued credit
> on a link does not go away when control returns from
> pn_messenger_recv(). It remains at the link, and successive
> calls can increase it.
>
>
>
>
>
