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
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.comwrote:
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
example of proton documentation
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.
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 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.
