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.
