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 <[email protected]> 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. > > > > >
