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