I think Rafi brought up a kind of unassailable point when he
suggested that a document about the Messenger API should
probably confine itself to concepts that are ... in the Messenger API.
I would be happy to explain the use of credit sometime (after the impl
settles down...) but the Messenger API doc is not the place for that.
SO! here is a rewrite just describing how sending and receiving works,
without talking bout "links" "credit" or other concepts that the Messenger
API is specifically trying to shield the developer from.
- start - - start - - - start - - - - - start - - - - - - - start
===================================================
Messenger I/O
===================================================
Each messenger has a single queue of incoming messages,
and a single queue of outgoing messages. Both input and
output happen in two stages: between your application
and the queue, and between the queue and the senders
and receivers that your application is talking with.
Input
----------------------------------------
Incoming messages are received and placed on the
incoming queue with pn_messenger_recv(). The second
argument is the upper limit on how many messages will
be enqueued.
pn_messenger_recv ( messenger, 100 );
A call to pn_messenger_recv() will return when at least
one message is available, or when the call times out if
you have set a time limit with pn_messenger_set_timeout().
The call to pn_messenger_recv() may enqueue fewer than
the number of messages you allowed To find how many messages
it enqueued, use
int enqueued = pn_messenger_incoming ( messenger );
When you are ready to process your incoming messages,
dequeue them one at a time into your application:
( This is the second stage of message input. )
int i;
pn_message_t msg;
for ( i = 0; i < enqueued; ++ i )
{
pn_messenger_get ( messenger, & msg );
}
Output
-------------------------------------------
Output is also accomplished in two stages: first enqueing
as many messages as you wish, and and then transmitting them all.
Enqueue your messages one at a time with:
pn_messenger_put ( messenger, & msg );
To learn how many you have on the outgoing queue waiting to be
sent, use:
int outgoing = pn_messenger_outgoing ( messenger );
And to transmit the messages in your output queue:
pn_messenger_send ( messenger );
Unspecified Limits on Input
--------------------------------------------
By using -1 as the second argument to pn_messenger_recv(),
you let the Messenger implementation decide what limit to
set on how many messages you may receive.
It will give a chance to all senders that are currently connected
to your application, but will try to set a reasonable bound on
messages per sender.
Performance Implications
--------------------------------------------
Messaging system performance is always a tradeoff between
throughput and latency. Throughput is the number of messages
or number of bytes you can transmit and receive per unit time.
Latency is the average time between the creation of a message
by its sender, and its processing by a receiver.
The two-stage Messenger I/O model allows you to make whatever
balance you choose between throughput and latency.
If you build up larger batches of messages before transmitting,
your will improve your throughput at the expense of having a
higher average latency per message. Transmitting messages in
small batches, down to one at a time if you wish, will minimize
latency, but will increase transmission and computation overhead,
which will decrease throughput.
- end - - end - - - end - - - - - end - - - - - - - end
