Re: put vs. send -- new doc
On Thu, Mar 7, 2013 at 3:18 PM, Michael Goulish wrote: > > > > 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 ? > Right, I wouldn't put it in the tree, just go for the list right now. --Rafael
Re: put vs. send -- new doc
- 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 > 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 ); > > > > > > > > >
Re: put vs. send -- new doc
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 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 ); > > > >
Re: put vs. send -- new doc
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 );
