Re: new send / recv proposal, documented
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
Re: new send / recv proposal, documented
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. This is very clear, I like it. Comments in-line [snip] 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 Superfluous "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 )` Missing msg parameter^ Stage message for later transmission, and possibly transmit any messages currently staged that are not blocked. This function will not block. * `pn_messenger_send ( messenger, N )` N < 0: block until all staged messages are sent N == 0: send whatever can be sent without blocking N > 0: block until exactly N messages are sent. _note: Messages may also be received during this call._ * `pn_messenger_get ( messenger, msg )` Dequeue the head of the incoming message queue to your application. This call does not block. What does it do if there is no message available without blocking? How do you find out how many messages are on the queue? * `pn_messenger_recv ( messenger )` Missing parameter N -^ N < 0: Block until at least 1 message received. N == 0: Receive whatever can be receive without blocking. N > 0: block until at least 1 and no more than N messages are received. _note: Staged messages may also be sent during this call._ Examples -- * send a message immediately pn_messenger_put ( messenger, msg ); pn_messenger_send ( messenger, N ); I think N should be -1 here. If you want to ensure the message you just _put gets sent then you need send(-1). Using send(1) might not send the message you just _put if there were already messages on the outgoing queue. * enqueue a message to be sent later pn_messenger_put ( messenger, msg ); _note: The message will be sent whenever it is not blocked and the Messenger code has other I/O work to be done._ *IS THIS STILL TRUE?* * block until all enqueued messages are sent pn_messenger_send ( messenger, -1 ); * send all messages that can be sent without blocking pn_messenger_send ( messenger, 0 ); * receive messages that can be received without blocking pn_messenger_recv ( messenger, 0 ); * block until at least one message is received pn_messenger_recv ( messenger, -1 ); * receive at least 1 but no more than N messages pn_messenger_recv ( messenger, N ); A minor incongruity: For outgoing messages you talk about "staged messages", but for incoming messages you talk about the "incoming queue". Suggest either using "incoming/outgoing queue" or "staged/received messages" to be consistent. Cheers, Alan.
new send / recv proposal, documented
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. * `pn_messenger_send ( messenger, N )` N < 0: block until all staged messages are sent N == 0: send whatever can be sent without blocking N > 0: block until exactly N messages are sent. _note: Messages may also be received during this call._ * `pn_messenger_get ( messenger, msg )` Dequeue the head of the incoming message queue to your application. This call does not block. * `pn_messenger_recv ( messenger )` N < 0: Block until at least 1 message received. N == 0: Receive whatever can be receive without blocking. N > 0: block until at least 1 and no more than N messages are received. _note: Staged messages may also be sent during this call._ Examples -- * send a message immediately pn_messenger_put ( messenger, msg ); pn_messenger_send ( messenger, N ); * enqueue a message to be sent later pn_messenger_put ( messenger, msg ); _note: The message will be sent whenever it is not blocked and the Messenger code has other I/O work to be done._ *IS THIS STILL TRUE?* * block until all enqueued messages are sent pn_messenger_send ( messenger, -1 ); * send all messages that can be sent without blocking pn_messenger_send ( messenger, 0 ); * receive messages that can be received without blocking pn_messenger_recv ( messenger, 0 ); * block until at least one message is received pn_messenger_recv ( messenger, -1 ); * receive at least 1 but no more than N messages pn_messenger_recv ( messenger, N );
