I like this. I don't think this is the same thing as high level conceptual intro, but may well be more useful right now, and it will always be very useful as recipe book style documentation.
I think this is actually quite helpful for the ongoing API discussions. One of the tricky things about developing a simple API is that everyone has their own scenario that they want to be simple, and sometimes making one scenario simpler ends up making another one more difficult, so it's actually really useful to have them all laid out so concisely so that we can observe the overall effect of any changes. I'm thinking we should expand this with the API changes I proposed in the other thread and see how they work out. --Rafael On Wed, Mar 6, 2013 at 9:43 AM, Michael Goulish <mgoul...@redhat.com> wrote: > > 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 ); > > > >
