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 );
