On 03/08/2013 09:31 AM, Michael Goulish wrote:
based on Rafi's proposal a couple days ago.
The idea here is to use this document to clearly
see what the proposal is.
Is this what we want ?
Comment early and often.
PLEASE NOTE one big difference. I don't have to talk about timeouts
anymore to show how things are done. Timeouts are just timeouts.
This is in markdown format. ( If you want to
see it rendered, go to http://daringfireball.net/projects/markdown/dingus
paste it in the window, and hit the "convert" button )
- -- --- ----- ------- ----------- -------------
Sending and Receiving Messages
=======================================================
The Proton Messenger API provides a mixture of synchronous
and asynchronous operations to give you flexibility in
balancing the work you want to be done against the blocking
that you are willing to accept.
When sending messages, you can:
* send a message immediately,
* enqueue a message to be sent later,
* block until all enqueued messages are sent,
* block until exactly N messages are sent,
* send all messages that can be sent without blocking, or
When receiving messages, you can:
* block until at least 1 message is received,
* block until at least one message, but no more than
N messages are received, or
* receive s many messages as possible without blocking.
Functions
------------------------------
* `pn_messenger_put ( messenger )`
Stage message for later transmission, and possibly
transmit any messages currently staged that are not
blocked.
This function will not block.
The "possibly transmit" portion is, I think, misleading. It suggests
that you can write a pure producer without ever calling
pn_messenger_send. This is asymmetric with the receive side is it not?
You can't receive without calling pn_messenger_recv right? So it would
be consistent to say that you can't send without calling pn_messenger_send.
Currently pn_messenger_put does not transmit any messages. The above
text leads one to believe that it will. It would be clearer to document
that pn_messenger_put will never send a message, only enqueue it for
later sending. To suggest that it might, when it won't, is going to
cause confusion.
-Ted
