----- Original Message ----- > I like this.
Good! I'm trying to get at the intention, as I understood it from online discussions, and make a doc that makes the intention easy to see. > 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. No, this isn't the intro -- I'm re-working that now. I guess I should have said what category of docs this is part of. Except I don't actually know. I guess I have an idea of a set of docs at this level that discuss different topics. i.e. addressing, message management, etc. > > 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. Sure -- like a doc for your recent proposals for changes. That would be fun, and useful I agree. But -- probably shouldn't check that into tree, right? Since it's for hypothetical code. Just post to list ? > > --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 ); > > > > > > > > >
