OK, I'm trying here to express the spirit of Messenger I/O ,
greatly based on the conversation of the last 24 hrs.
This probably needs some elaboration yet, but I want to
see if I'm at least generally on the right track.
Oh, please, give me feedback.
Sending and Receiving Messages
=======================================================
The Proton Messenger API provides a mixture of synchronous
and asynchronous operations to give you flexibility in
deciding when you application should block waiting for I/O,
and when it should not.
When sending messages, you can:
* send a message immediately,
* enqueue a message to be sent later,
* block until all enqueued messages are sent,
* send enqueued messages until a timeout occurs, or
* send all messages that can be sent without blocking.
When receiving messages, you can:
* receive messages that can be received without blocking,
* block until at least one message is received,
* receive no more than a fixed number of messages.
Examples
------------------------------
1. send a message immediately
put ( messenger, msg );
send ( messenger );
2. enqueue a message to be sent later
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.
3. block until all enqueued messages are sent
set_timeout ( messenger, -1 );
send ( messenger );
note:
A negative timeout means 'forever'. That is the initial
default for a messenger.
4. send enqueued messages until a timeout occurs
set_timeout ( messenger, 100 ); /* 100 msec */
send ( messenger );
5. send all messages that can be sent without blocking
set_timeout ( messenger, 0 );
send ( messenger );
6. receive messages that can be received without blocking
set_timeout ( messenger, 0 );
recv ( messenger, -1 );
7. block until at least one message is received
set_timeout ( messenger, -1 );
recv ( messenger, -1 );
note: -1 is initial messenger default.
If you didn't change it, you don't need to set it.
8. receive no more than a fixed number of messages
recv ( messenger, 10 );
