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

Reply via email to