[jira] [Assigned] (PROTON-249) Build fails on Win8 / VS 2012 with path error
[ https://issues.apache.org/jira/browse/PROTON-249?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ] Keith Wall reassigned PROTON-249: - Assignee: Keith Wall Build fails on Win8 / VS 2012 with path error - Key: PROTON-249 URL: https://issues.apache.org/jira/browse/PROTON-249 Project: Qpid Proton Issue Type: Bug Components: proton-j Affects Versions: 0.4 Environment: Windows 8 64 bit w/ cmake v. 2.8.10.12 and Visual Studio 2012 Reporter: Paul O'Fallon Assignee: Keith Wall The build in Visual Studio generates one error, which is the following (from the build output): 3 Building Java objects for proton-api.jar 3 javac: file not found: C:\qpid-proton-0.4\proton-j\proton-api\src\main\java\org\apache\qpi\proton\driver\Connector.java 3 Usage: javac options source files Note that the path is qpi, not qpid -- This message is automatically generated by JIRA. If you think it was sent incorrectly, please contact your JIRA administrators For more information on JIRA, see: http://www.atlassian.com/software/jira
[jira] [Comment Edited] (PROTON-249) Build fails on Win8 / VS 2012 with path error
[ https://issues.apache.org/jira/browse/PROTON-249?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanelfocusedCommentId=13585836#comment-13585836 ] Keith Wall edited comment on PROTON-249 at 2/25/13 12:56 PM: - I've successfully reproduced Paul's problem. The problem is the handling of long command lines under the Windows OS. It seems Windows looses a byte at every 8192 boundary within the command line -- effectively limiting command lines to less than 8192 bytes.Our command line is ~11,000 characters long. We are currently testing a workaround which will use javac's @ flag to specify a file containing a list of source files, thus avoiding the requirement for long command lines. (A defect http://public.kitware.com/Bug/view.php?id=13028 was raised against Cmake's UseJava module but unfortunately this never got assigned and has been subsequently closed without action). was (Author: k-wall): I've successfully reproduced Paul's problem. The problem is the handling of long command lines under the Windows OS. It seems Windows looses a byte at every 8192 boundary within the command line -- effectively limiting command lines to less than 8192 bytes.Our command line is ~11,000 characters long. We are currently testing a workaround which will use javac's @ flag to specify a file containing a list of source files, thus avoiding the requirement for long command lines. (A defect http://public.kitware.com/Bug/view.php?id=13028 was raised against Cmake's UseJava module but unfortunately this never got assigned). Build fails on Win8 / VS 2012 with path error - Key: PROTON-249 URL: https://issues.apache.org/jira/browse/PROTON-249 Project: Qpid Proton Issue Type: Bug Components: proton-j Affects Versions: 0.4 Environment: Windows 8 64 bit w/ cmake v. 2.8.10.12 and Visual Studio 2012 Reporter: Paul O'Fallon Assignee: Keith Wall The build in Visual Studio generates one error, which is the following (from the build output): 3 Building Java objects for proton-api.jar 3 javac: file not found: C:\qpid-proton-0.4\proton-j\proton-api\src\main\java\org\apache\qpi\proton\driver\Connector.java 3 Usage: javac options source files Note that the path is qpi, not qpid -- This message is automatically generated by JIRA. If you think it was sent incorrectly, please contact your JIRA administrators For more information on JIRA, see: http://www.atlassian.com/software/jira
[jira] [Updated] (PROTON-249) Build fails on Win8 / VS 2012 with path error
[ https://issues.apache.org/jira/browse/PROTON-249?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ] Keith Wall updated PROTON-249: -- Priority: Blocker (was: Major) Build fails on Win8 / VS 2012 with path error - Key: PROTON-249 URL: https://issues.apache.org/jira/browse/PROTON-249 Project: Qpid Proton Issue Type: Bug Components: proton-j Affects Versions: 0.4 Environment: Windows 8 64 bit w/ cmake v. 2.8.10.12 and Visual Studio 2012 Reporter: Paul O'Fallon Assignee: Keith Wall Priority: Blocker The build in Visual Studio generates one error, which is the following (from the build output): 3 Building Java objects for proton-api.jar 3 javac: file not found: C:\qpid-proton-0.4\proton-j\proton-api\src\main\java\org\apache\qpi\proton\driver\Connector.java 3 Usage: javac options source files Note that the path is qpi, not qpid -- This message is automatically generated by JIRA. If you think it was sent incorrectly, please contact your JIRA administrators For more information on JIRA, see: http://www.atlassian.com/software/jira
[jira] [Commented] (PROTON-249) Build fails on Win8 / VS 2012 with path error
[ https://issues.apache.org/jira/browse/PROTON-249?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanelfocusedCommentId=13585838#comment-13585838 ] Keith Wall commented on PROTON-249: --- Marked as Blocker as this currently prevents users from successfully running the build on Windows, and I'm not aware of any reasonable workaround. Build fails on Win8 / VS 2012 with path error - Key: PROTON-249 URL: https://issues.apache.org/jira/browse/PROTON-249 Project: Qpid Proton Issue Type: Bug Components: proton-j Affects Versions: 0.4 Environment: Windows 8 64 bit w/ cmake v. 2.8.10.12 and Visual Studio 2012 Reporter: Paul O'Fallon Assignee: Keith Wall Priority: Blocker The build in Visual Studio generates one error, which is the following (from the build output): 3 Building Java objects for proton-api.jar 3 javac: file not found: C:\qpid-proton-0.4\proton-j\proton-api\src\main\java\org\apache\qpi\proton\driver\Connector.java 3 Usage: javac options source files Note that the path is qpi, not qpid -- This message is automatically generated by JIRA. If you think it was sent incorrectly, please contact your JIRA administrators For more information on JIRA, see: http://www.atlassian.com/software/jira
Re: 0.4 RC2
Hi Paul I've successfuly reproduced your issue and are tracking our progress under PROTON-249. We don't need your debug output at this stage. Kind regards, Keith. On 24 February 2013 00:27, Paul O'Fallon p...@ofallonfamily.com wrote: I filed this as https://issues.apache.org/jira/browse/PROTON-249 I have some files to attach (my cmake debug output and the vs2012 build output) but I couldn't see in Jira where to attach the files (maybe I don't have permission?) Thanks, Paul On Sat, Feb 23, 2013 at 3:04 PM, Paul O'Fallon p...@ofallonfamily.com wrote: Sure, I'll do that. This error is from the VS 2012 build output (cmake runs with no errors). I'm running v. 2.8.10.2 of cmake. I know with other projects I've run into issues when the depth of directories on Windows grows too large -- not sure if this structure is that deep yet (although that's why I moved it to the root dir of my machine to give it the best shot of working). - Paul On Sat, Feb 23, 2013 at 2:35 PM, Keith Wall keith.w...@gmail.com wrote: I'm getting much closer I still get one error 4 javac: file not found: C:\qpid-proton-0.4\proton-j\proton-api\src\main\java\org\apache\qpi\proton\driver\Connector.java 4 Usage: javac options source files 4 use -help for a list of possible options Paul, That sounds odd. The proton-api cmakelist is really simple so I wonder what we might be doing wrong to cause such an error. We have nothing that manipulates the paths. Would you be able to repeat with cmake in verbose/debug mode (sorry I forget the precise name of the cmake option and am travelling right now) and attach the output to a new Jira, What version of cmake are you using? What exact commands are you issuing to get the error? Kind regards. Keith.
Re: [documentation] -- Intro to Proton
I think I will be landing it in the code tree first, and from there, I don't know. Any suggestions? In the code -- I assume it should be at the top level? i.e. a sibling of the README file? i.e. qpid-proton-0.4/pulitzer_prize_winning_documentation or something along those lines? Agree? Disagree? - Original Message - From: Phil Harvey p...@philharveyonline.com To: proton@qpid.apache.org Sent: Monday, February 25, 2013 12:14:00 PM Subject: Re: [documentation] -- Intro to Proton Hi Michael, Maybe you didn't see my previous question (or maybe I didn't see your answer). Where are you intending to store this documentation? Similarly, where are you intending to publish it, e.g. as HTML and/or PDF on our web site, as a wiki page etc? Thanks Phil On 25 February 2013 16:15, Michael Goulish mgoul...@redhat.com wrote: Here's the introduction I'm planning on. If anyone has any opinions, I'd be happy to get them -- is there too much detail for a quick intro? Too little? A crucial bit I left out? Something I got wrong? ## Introduction to Proton === The Messenger interface is a simple, high-level API that lets you create point-to-point messaging applications quickly and easily. The interface offers four main categories of functionality. Messenger Operation --- There are only a few operations that are not directly concerning with message transmission. A messenger can be created, named, and freed. It can be started and stopped, and it can be checked for errors after any operation. Sending and Receiving --- Both sending and receiving happen in two stages, the inner stage moving the message between your application and a queue, the outer stage transmitting messages between your queues and remote messaging nodes. By changing the ratio of transmissions to queue transfers, you can optimize your messaging application for message latency or for overall throughput. Subscriptions control what sources your messenger can receive from, and what sources it can send to. Your messenger subscribes to the sources you want to receive from, while your outgoing messages will be received by messengers that have subscribed to your outgoing address. Message Disposition --- When you receive messages, you must either accept or reject them. You can either configure your messenger to automatically accept all messages that you get, or you can exercise finer control over message acceptance and rejection, individually or in groups. Trackers and Windows let you set or check the disposition of messages in groups. Applying the disposition operations to groups of messages can improve your system's throughput. When receiving messages, you can create a tracker for the most recently received message, and later use that tracker to accept or reject all messages up to (and including) that one. When sending messages, you can create a tracker for your most recently sent message, and later use it to inquire about the remote disposition of all sent messages up to that point. If you don't want to let a receiver make you wait forever to see what he's going to do, you can set a timeout that will control how long he can take making up his mind. By using incoming and outgoing Windows, you can limit the number of messages that these operations affect. Security --- The messenger interface allows you to use the Secure Sockets Layer by exposing an interface to the OpenSSL library.
Re: [documentation] -- Intro to Proton
I'm strong believer in maintaining our docs in the source tree, as it makes it easy to release docs along side the code. Also it helps keep the docs current. The wiki based documentation in the past had many issues, the chief complaint being stale most of the time. We could look at doing something similar to the qpid docs, or we could also use this opportunity to experiment with a different approach/tool set. Rajith On Mon, Feb 25, 2013 at 1:50 PM, Michael Goulish mgoul...@redhat.com wrote: I think I will be landing it in the code tree first, and from there, I don't know. Any suggestions? In the code -- I assume it should be at the top level? i.e. a sibling of the README file? i.e. qpid-proton-0.4/pulitzer_prize_winning_documentation or something along those lines? Agree? Disagree? - Original Message - From: Phil Harvey p...@philharveyonline.com To: proton@qpid.apache.org Sent: Monday, February 25, 2013 12:14:00 PM Subject: Re: [documentation] -- Intro to Proton Hi Michael, Maybe you didn't see my previous question (or maybe I didn't see your answer). Where are you intending to store this documentation? Similarly, where are you intending to publish it, e.g. as HTML and/or PDF on our web site, as a wiki page etc? Thanks Phil On 25 February 2013 16:15, Michael Goulish mgoul...@redhat.com wrote: Here's the introduction I'm planning on. If anyone has any opinions, I'd be happy to get them -- is there too much detail for a quick intro? Too little? A crucial bit I left out? Something I got wrong? ## Introduction to Proton === The Messenger interface is a simple, high-level API that lets you create point-to-point messaging applications quickly and easily. The interface offers four main categories of functionality. Messenger Operation --- There are only a few operations that are not directly concerning with message transmission. A messenger can be created, named, and freed. It can be started and stopped, and it can be checked for errors after any operation. Sending and Receiving --- Both sending and receiving happen in two stages, the inner stage moving the message between your application and a queue, the outer stage transmitting messages between your queues and remote messaging nodes. By changing the ratio of transmissions to queue transfers, you can optimize your messaging application for message latency or for overall throughput. Subscriptions control what sources your messenger can receive from, and what sources it can send to. Your messenger subscribes to the sources you want to receive from, while your outgoing messages will be received by messengers that have subscribed to your outgoing address. Message Disposition --- When you receive messages, you must either accept or reject them. You can either configure your messenger to automatically accept all messages that you get, or you can exercise finer control over message acceptance and rejection, individually or in groups. Trackers and Windows let you set or check the disposition of messages in groups. Applying the disposition operations to groups of messages can improve your system's throughput. When receiving messages, you can create a tracker for the most recently received message, and later use that tracker to accept or reject all messages up to (and including) that one. When sending messages, you can create a tracker for your most recently sent message, and later use it to inquire about the remote disposition of all sent messages up to that point. If you don't want to let a receiver make you wait forever to see what he's going to do, you can set a timeout that will control how long he can take making up his mind. By using incoming and outgoing Windows, you can limit the number of messages that these operations affect. Security --- The messenger interface allows you to use the Secure Sockets Layer by exposing an interface to the OpenSSL library.
[jira] [Created] (PROTON-250) Add -fvisibility option when building shared libraries
Irina Boverman created PROTON-250: - Summary: Add -fvisibility option when building shared libraries Key: PROTON-250 URL: https://issues.apache.org/jira/browse/PROTON-250 Project: Qpid Proton Issue Type: Improvement Components: proton-c Affects Versions: 0.3 Environment: GNU Compiler Reporter: Irina Boverman Priority: Minor Add an option to hide symbols in shared libraries except when they are declared public. Extends efforts already in place for Windows builds. Excludes an effort to determine what symbols should be considered public interfaces. The gcc 4 -fvisibility option is said to: ...very substantially improve linking and load times of shared object libraries, produce more optimized code, provide near-perfect API export and prevent symbol clashes. It is strongly recommended that you use this in any shared objects you distribute. See here: http://gcc.gnu.org/wiki/Visibility -- This message is automatically generated by JIRA. If you think it was sent incorrectly, please contact your JIRA administrators For more information on JIRA, see: http://www.atlassian.com/software/jira
[jira] [Updated] (PROTON-250) Add -fvisibility option when building shared libraries
[ https://issues.apache.org/jira/browse/PROTON-250?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ] Irina Boverman updated PROTON-250: -- Description: Add an option to hide symbols in shared libraries except when they are declared public. Extends efforts already in place for Windows builds. Excludes an effort to determine what symbols should be considered public interfaces. The gcc 4 -fvisibility option is said to: ...very substantially improve linking and load times of shared object libraries, produce more optimized code, provide near-perfect API export and prevent symbol clashes. It is strongly recommended that you use this in any shared objects you distribute. See here: http://gcc.gnu.org/wiki/Visibility Attached patch (patch.txt) will build libqpid-proton.so shared library using this flag. It reduces number of symbols from 700+ to 500+. was: Add an option to hide symbols in shared libraries except when they are declared public. Extends efforts already in place for Windows builds. Excludes an effort to determine what symbols should be considered public interfaces. The gcc 4 -fvisibility option is said to: ...very substantially improve linking and load times of shared object libraries, produce more optimized code, provide near-perfect API export and prevent symbol clashes. It is strongly recommended that you use this in any shared objects you distribute. See here: http://gcc.gnu.org/wiki/Visibility Add -fvisibility option when building shared libraries --- Key: PROTON-250 URL: https://issues.apache.org/jira/browse/PROTON-250 Project: Qpid Proton Issue Type: Improvement Components: proton-c Affects Versions: 0.3 Environment: GNU Compiler Reporter: Irina Boverman Priority: Minor Add an option to hide symbols in shared libraries except when they are declared public. Extends efforts already in place for Windows builds. Excludes an effort to determine what symbols should be considered public interfaces. The gcc 4 -fvisibility option is said to: ...very substantially improve linking and load times of shared object libraries, produce more optimized code, provide near-perfect API export and prevent symbol clashes. It is strongly recommended that you use this in any shared objects you distribute. See here: http://gcc.gnu.org/wiki/Visibility Attached patch (patch.txt) will build libqpid-proton.so shared library using this flag. It reduces number of symbols from 700+ to 500+. -- This message is automatically generated by JIRA. If you think it was sent incorrectly, please contact your JIRA administrators For more information on JIRA, see: http://www.atlassian.com/software/jira
[RESULT] [VOTE] 0.4 RC3
The vote carries with 5 +1's and 0 -1's. I'll upload the artifacts shortly. --Rafael On Thu, Feb 21, 2013 at 1:54 PM, Rafael Schloming r...@alum.mit.edu wrote: Hi everyone, I've spun an RC3 with fixes for the two immediately soluble issues that turned up with RC2. Please check it out and cast your vote. Source is here: - http://people.apache.org/~rhs/qpid-proton-0.4rc3/ Java binaries are here: - https://repository.apache.org/content/repositories/orgapacheqpid-292/ Changes since RC2: PROTON-230, PROTON-246: Copying nested data fails in some cases PROTON-245: make swig skip pn_dtag for compatibility with older versions of swig [ ] Yes, I believe we should make 0.4 RC3 into 0.4 final [ ] No, because ...
Re: [RESULT] [VOTE] 0.4 RC3
I've uploaded the artifacts and updated the download page[1]. It will be about 24 hours or so until the mirrors are fully synced. [1] http://qpid.apache.org/proton/download.html --Rafael On Mon, Feb 25, 2013 at 12:44 PM, Rafael Schloming r...@alum.mit.edu wrote: The vote carries with 5 +1's and 0 -1's. I'll upload the artifacts shortly. --Rafael On Thu, Feb 21, 2013 at 1:54 PM, Rafael Schloming r...@alum.mit.eduwrote: Hi everyone, I've spun an RC3 with fixes for the two immediately soluble issues that turned up with RC2. Please check it out and cast your vote. Source is here: - http://people.apache.org/~rhs/qpid-proton-0.4rc3/ Java binaries are here: - https://repository.apache.org/content/repositories/orgapacheqpid-292/ Changes since RC2: PROTON-230, PROTON-246: Copying nested data fails in some cases PROTON-245: make swig skip pn_dtag for compatibility with older versions of swig [ ] Yes, I believe we should make 0.4 RC3 into 0.4 final [ ] No, because ...
[jira] [Commented] (PROTON-215) Add tests to verify AMQP 1.0 type support for all language bindings
[ https://issues.apache.org/jira/browse/PROTON-215?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanelfocusedCommentId=13586391#comment-13586391 ] Alan Conway commented on PROTON-215: The approach is slightly different to that described in the first comment. The data is split up into separate files containing fragments of AMQP-encoded data, with a unit test for each fragment in each binding. This has the advantage that if there is a failure on one fragment, you can still verify the others independently, you can skip tests individually etc. With a single message containing all types, there's just one test and any failure means the whole interop test fails. This has already been useful as a couple of encode bugs were found and fixed in the process of creating the tests. There is also a file test for a full encoded message so the message encoding is tested, we probably will wan to extend the tests to cover messages with various headers etc. Add tests to verify AMQP 1.0 type support for all language bindings --- Key: PROTON-215 URL: https://issues.apache.org/jira/browse/PROTON-215 Project: Qpid Proton Issue Type: Test Components: proton-c Affects Versions: 0.3 Reporter: Ken Giusti Assignee: Alan Conway Labels: test For each language binding, we need to verify that the language can encode to and decode from the AMQP 1.0 types. -- This message is automatically generated by JIRA. If you think it was sent incorrectly, please contact your JIRA administrators For more information on JIRA, see: http://www.atlassian.com/software/jira
Re: [documentation] -- Intro to Proton
Hi Michael, I know you mentioned plans to write some bigger document ... it is not entirely clear to me, whether this is supposed to be a standalone introduction or just a first chapter of the larger document. It suppose the second is correct, right? Also, is it introduction to Proton or just to the Proton Messenger API? From what I understood so far from the discussions here in the mailing list, Proton is much more than just the Messenger API. I would either call it Proton Messenger introduction or add some short explanation that the Messenger API is just one part of Proton which might be the most interesting for beginners. Thanks Regards Jakub On Mon, Feb 25, 2013 at 5:15 PM, Michael Goulish mgoul...@redhat.comwrote: The messenger interface allows you to use the Secure Sockets Layer by exposing an interface to the OpenSSL library.
Re: example of proton documentation
Hi Michael,
I'm rather a foreigner in the land of Proton, but that point of view might
make the feedback useful as well :-). As someone who didn't worked with
proton much, I would probably raise following questions ...
a) If I remember correctly, in (some of) the old Qpid APIs the flow control
was able to work as windows based or credit based. From your description it
is not entirely clear to me whether the flow control in Proton is credit or
window based. You talk about credit, but afterwards you mention
the dequeuing using pn_messenger_get(...) function which makes me wonder
whether this call restores the credit. If it is not related to the credit,
I would probably remove the last part of the chapter mentioning the
pn_messenger_get() call. Since flow control is slightly more advanced
topic, I would assume that the pn_messenger_get() should be explained
already in previous chapters.
b) Again, if I remember correctly, (some of) the old Qpid APIs allowed to
specify flow control limits in messages or in bytes. You mention only limit
in messages - that might immediately raise questions how can I specify the
limit in bytes. I think it would be great if you can add a note that the
flow control limit in bytes is not supported.
c) 10 units per link doesn't really sound like infinite credit. People tend
to often read only half of the documentation - many of them might stop
after reading You can also grant 'infinite' credit by using a negative
value and afterwards they will wonder why is it only 10 per link and not
really infinite. I would probably also rename the chapter and/or rephrase
the first sentence.
d) It is not entirely clear to me, whether the infinite credit is then
somehow auto-refreshed or whether the 10 units are consumed by the messages.
e) It remains at the link, and successive calls can increase it. ... can
the credit be really only increased? Or can it be also decreased? I would
suggest to mention it there even if it is not possible to decrease the
credit ... just to avoid questions.
f) It would be great if the typical pattern can be slightly more complex
and include the refreshing of the credit with further
pn_messenger_recv(...) call.
g) Also, I would probably structure the chapters as 1. Controlling Message
Flow with Credit, 1.1 Credit does not drain, 1.2 A typical pattern and 1.3
Infinite credit
Anyway, thanks a lot for your effort ... keep the good work ... without a
good documentation, it doesn't matter how good Proton is - nobody will use
it. When we started with AMQP / Qpid / MRG Messaging, the documentation was
pretty much useless and we had to write our own Programming Guide because
nobody from our customers was able to even connect. It would be great if we
can avoid it in the next version :-).
Thanks Regards
Jakub
On Fri, Feb 22, 2013 at 11:14 AM, Michael Goulish mgoul...@redhat.comwrote:
I wonder if anybody out there in Proton Land has an
opinion about this little piece of Proton doc.
This is an example of the documentation I'm creating as
I use the Proton interface to
I'd be interested to hear about
1. correctness
2. clarity
3. focus
4. usefulness
5. anything else that strikes you
I don't know what to call this -- a mini-tutorial? -- a 'topic'? --
but in any case, I expect I will have 5 or 6 pieces like this for
the Proton Messenger doc when I'm done, so I wanted to See What You Think.
Yes, *you* !
- everything below this point is the doc -
Controlling Message Flow with Credit
=
To control the flow of messages into your Proton application,
use the second argument to
pn_messenger_recv ( messenger, credit );
If you set credit to a positive value, it will limit the number
of messages that pn_messenger_recv enqueues for you on that
call.
The number you provide is a maximum. The call to pn_messenger_recv
may also enqueue fewer messages, or none. You can learn how many
were received with:
pn_messenger_incoming ( messenger );
You can then dequeue each message, one at a time, into your
application with successive calls to
pn_messenger_get ( messenger );
A typical pattern
---
int i, incoming;
pn_messenger_recv ( messenger, credit );
incoming = pn_messenger_incoming ( messenger );
for ( i = 0; i incoming; ++ i )
{
pn_messenger_get ( messenger, message );
consume_message ( message );
}
Infinite Credit
--
You can also grant 'infinite' credit by using a negative
value as the second arg to pn_messenger_recv(). This will
have the effect of granting 10 units of credit to every link
on that call to pn_messenger_recv().
A single messenger, listening on a single port, may have
many incoming links.
Credit does not drain
--
Once granted by
Re: [documentation] -- Intro to Proton
I do agree with you that having documentation committed alongside code is the right approach. I propose that we write this documentation in Markdown syntax. That gives us (or our users) the option of easily generating HTML whilst keeping the barrier to entry low for authors. I recognise that Markdown lacks the semantic richness of Docbook (used for the Qpid Broker), but I believe that's ok in this case since our documentation should be quite short (or we're doing something wrong). Phil On Feb 25, 2013 7:07 PM, Rajith Attapattu rajit...@gmail.com wrote: I'm strong believer in maintaining our docs in the source tree, as it makes it easy to release docs along side the code. Also it helps keep the docs current. The wiki based documentation in the past had many issues, the chief complaint being stale most of the time. We could look at doing something similar to the qpid docs, or we could also use this opportunity to experiment with a different approach/tool set. Rajith On Mon, Feb 25, 2013 at 1:50 PM, Michael Goulish mgoul...@redhat.com wrote: I think I will be landing it in the code tree first, and from there, I don't know. Any suggestions? In the code -- I assume it should be at the top level? i.e. a sibling of the README file? i.e. qpid-proton-0.4/pulitzer_prize_winning_documentation or something along those lines? Agree? Disagree? - Original Message - From: Phil Harvey p...@philharveyonline.com To: proton@qpid.apache.org Sent: Monday, February 25, 2013 12:14:00 PM Subject: Re: [documentation] -- Intro to Proton Hi Michael, Maybe you didn't see my previous question (or maybe I didn't see your answer). Where are you intending to store this documentation? Similarly, where are you intending to publish it, e.g. as HTML and/or PDF on our web site, as a wiki page etc? Thanks Phil On 25 February 2013 16:15, Michael Goulish mgoul...@redhat.com wrote: Here's the introduction I'm planning on. If anyone has any opinions, I'd be happy to get them -- is there too much detail for a quick intro? Too little? A crucial bit I left out? Something I got wrong? ## Introduction to Proton === The Messenger interface is a simple, high-level API that lets you create point-to-point messaging applications quickly and easily. The interface offers four main categories of functionality. Messenger Operation --- There are only a few operations that are not directly concerning with message transmission. A messenger can be created, named, and freed. It can be started and stopped, and it can be checked for errors after any operation. Sending and Receiving --- Both sending and receiving happen in two stages, the inner stage moving the message between your application and a queue, the outer stage transmitting messages between your queues and remote messaging nodes. By changing the ratio of transmissions to queue transfers, you can optimize your messaging application for message latency or for overall throughput. Subscriptions control what sources your messenger can receive from, and what sources it can send to. Your messenger subscribes to the sources you want to receive from, while your outgoing messages will be received by messengers that have subscribed to your outgoing address. Message Disposition --- When you receive messages, you must either accept or reject them. You can either configure your messenger to automatically accept all messages that you get, or you can exercise finer control over message acceptance and rejection, individually or in groups. Trackers and Windows let you set or check the disposition of messages in groups. Applying the disposition operations to groups of messages can improve your system's throughput. When receiving messages, you can create a tracker for the most recently received message, and later use that tracker to accept or reject all messages up to (and including) that one. When sending messages, you can create a tracker for your most recently sent message, and later use it to inquire about the remote disposition of all sent messages up to that point. If you don't want to let a receiver make you wait forever to see what he's going to do, you can set a timeout that will control how long he can take making up his mind. By using incoming and outgoing Windows, you can limit the number of messages that these operations affect. Security --- The messenger
