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_INFINITE 10 #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" <ja...@scholz.cz> 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 <mgoul...@redhat.com>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. > > > > >