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.)