Re: [doc] I will check these in on Friday the 4th...
Comments in-line below...
A general question/comment: Is the single-threaded nature of this API
clearly spelled out somewhere? There's a lot of the use of the "returns
X associated with the most recent call to Y" pattern, which isn't
multi-thread-friendly. Then, there are calls like
pn_messenger_interrupt and pn_messenger_stopped that suggest
multi-threaded use. What's the intent here?
-Ted
On 09/30/2013 01:46 PM, Michael Goulish wrote:
I will check this stuff in this coming Friday, 4 Oct,
( at midnight, in the last timezone on Earth...)
if I don't hear any objections / suggestions,
so please take a look before then if you would like to
provide feedback.
These are expanded descriptions that I'd like to add to the C API
documentation. ( These are the descriptions only -- where the
current info already explains the parameters and returns values
I will just leave those in place. )
These are the only ones I plan to change at this time.
Please take a look to see
1. whether the description matches your understanding
of what the functions do, and how they fit together.
2. whether you, as a developer using this code, would
find the description useful, sufficient, understandable,
etc.
Question 2 is still very valuable even if you have no
idea about Question 1.
This is not yet a complete list. Some of the functions are
clear already, and some I have no clue about as yet.
Here they are:
pn_messenger_interrupt
{
Call this from a non-messenger thread to interrupt
a messenger that is blocking.
Return value: 0 if all is well, or -1.
If -1 is returned, that is not PN_EOS. It is the return
value of the system call write(3), and can be printed with
perror(3).
}
It appears that the error-space for this function is different from all
of the other functions. This call uses the posix errors whereas
pn_messenger_error uses a Proton-specific error code.
pn_messenger_receiving
{
Returns the number of messages that
was requested by the most recent call
to pn_messenger_recv.
}
I'd like to see a case where this is needed? When would you use it?
pn_messenger_reject
{
Rejects the message indicated by the tracker. If the PN_CUMULATIVE
flag is used this call will also reject all prior messages that
have not already been settled. The semantics of message rejection
are application-specific. If messages represent work requests,
then rejection would leave the sender free to try another receiver,
without fear of having the same task done twice.
}
It is my understanding that rejected messages should never be re-sent.
Isn't the above description appropriate for RELEASED, not REJECTED?
pn_messenger_rewrite
{
Similar to pn_messenger_route(), except that the destination of
the message is determined before the message address is rewritten.
If a message has an outgoing address of "amqp://0.0.0.0:5678", and a
rewriting rule that changes its outgoing address to "foo", it will still
arrive at the peer that is listening on "amqp://0.0.0.0:5678", but when
it arrives there, its outgoing address will have been changed to "foo".
}
What is the purpose of this function? If the to-field has been
re-written to "foo", how will it then arrive at your intended destination?
pn_messenger_stopped
{
If a call to pn_messenger_stop returns a non-zero code,
use this to determine whether the messenger has stopped.
}
Does this function block? Do you need to call it in a loop? What are
the multi-threading implications?
[jira] [Commented] (PROTON-342) installing into custom location doesn't work nicely (and is not properly documented)
[ https://issues.apache.org/jira/browse/PROTON-342?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=13782072#comment-13782072 ] Darryl L. Pierce commented on PROTON-342: - Looking into this more, the pkg-config file (libqpid-proton.pc) seems to be setting its values properly. There was a separate bug (PROTON-412) that fixed issues with that file, where the paths were being misconfigured. The only issue that'll come up is that the paths within it are based on the environment as described to CMake prior to the build. Using DESTDIR isn't meant to update the paths in that file but is used for things like building for a package distribution; i.e., you wouldn't use it to actually install onto your system. The dynamic languages are behaving as expected, as they will install to directories as specified by the dynamic languages themselves. Should we then close this issue? > installing into custom location doesn't work nicely (and is not properly > documented) > > > Key: PROTON-342 > URL: https://issues.apache.org/jira/browse/PROTON-342 > Project: Qpid Proton > Issue Type: Bug > Components: proton-c >Affects Versions: 0.4 >Reporter: Gordon Sim >Assignee: Darryl L. Pierce > > The README suggests setting -DCMAKE_INSTALL_PREFIX when running cmake, it > does not mention setting DESTDIR when invoking make install. > If you don't set the DESTDIR on make install it will honour the > CMAKE_INSTALL_PREFIX for some parts of the installation (e.g. header files, > native libraries, pkg-config file etc) but the python bindings (and I assume > other bindings) will still install in the standard location which will fail > if you are not running as root. > However if you set DESTDIR then this alters the location of the headers, > libraries and pkg-config , which now install into > $DESTDIR/$CMAKE_INSTALL_PREFIX and the pkg-config file no longer has the > correct include or library paths in it. -- This message was sent by Atlassian JIRA (v6.1#6144)
[doc] I will check these in on Friday the 4th...
I will check this stuff in this coming Friday, 4 Oct,
( at midnight, in the last timezone on Earth...)
if I don't hear any objections / suggestions,
so please take a look before then if you would like to
provide feedback.
These are expanded descriptions that I'd like to add to the C API
documentation. ( These are the descriptions only -- where the
current info already explains the parameters and returns values
I will just leave those in place. )
These are the only ones I plan to change at this time.
Please take a look to see
1. whether the description matches your understanding
of what the functions do, and how they fit together.
2. whether you, as a developer using this code, would
find the description useful, sufficient, understandable,
etc.
Question 2 is still very valuable even if you have no
idea about Question 1.
This is not yet a complete list. Some of the functions are
clear already, and some I have no clue about as yet.
Here they are:
pn_messenger_accept
{
Signal the sender that you have received and have acted on the message
pointed to by the tracker. If the PN_CUMULATIVE flag is set, all
messages prior to the tracker will also be accepted, back to the
beginning of your incoming window.
}
pn_messenger_errno
{
Return the code for the most recent error.
Initialized to zero at messenger creation.
Error numbers are "sticky" i.e. are not reset to 0
at the end of successful API calls.
(NOTE! This is the only description that is intentionally false.
There *is* one API call that resets errno to 0 -- but I think
it shouldn't, and I will complain about it Real Soon Now.)
}
pn_messenger_error
{
Return a text description of the most recent error.
Initialized to null at messenger creation.
Error text is "sticky" i.e. not reset to null
at the end of successful API calls.
}
pn_messenger_get
{
Pop the oldest message off your incoming message queue,
and copy it into the given message structure.
If the given pointer to a message structure in NULL,
the popped message is discarded.
Returns PN_EOS if there are no messages to get.
Returns an error code only if there is a problem in
decoding the message.
}
pn_messenger_get_certificate
{
Return the certificate path if one has been set,
by pn_messenger_set_certificate, or null.
}
pn_messenger_get_incoming_window
{
Returns the size of the incoming window that was
set with pn_messenger_set_incoming_window. The
default is 0.
}
pn_messenger_get_outgoing_window
{
Returns the size of the incoming window that was
set with pn_messenger_set_incoming_window. The
default is 0.
}
pn_messenger_incoming_subscription
{
Returns a pointer to the subscription of the message returned by the
most recent call to pn_messenger_get(), or NULL if pn_messenger_get()
has never been called.
}
pn_messenger_incoming_tracker
{
Returns a tracker for the message most recently fetched by
pn_messenger_get(). The tracker allows you to accept or reject its
message, or its message plus all prior messages that are still within
your incoming window.
}
pn_messenger_interrupt
{
Call this from a non-messenger thread to interrupt
a messenger that is blocking.
Return value: 0 if all is well, or -1.
If -1 is returned, that is not PN_EOS. It is the return
value of the system call write(3), and can be printed with
perror(3).
}
pn_messenger_is_blocking
{
Accessor for messenger blocking mode.
Note: this tells you only whether the messenger is in
blocking mode. This will not tell you (if called from
a separate thread) that a messenger is currently blocking
}
pn_messenger_outgoing_tracker
{
Returns a tracker for the outgoing message most recently given
to pn_messenger_put. Use this tracker with pn_messenger_status
to determine the delivery status of the message, as long as the
message is still within your outgoing window.
}
pn_messenger_put
{
Puts the message onto the messenger's outgoing queue.
The message may also be sent if transmission would not cause
blocking. This call will not block.
}
pn_messenger_receiving
{
Returns the number of messages that
was requested by the most recent call
to pn_messenger_recv.
}
pn_messenger_recv
{
( add this text to current description )
After receiving messages onto your incoming queue,
use pn_messenger_get to bring messages into your application code.
}
pn_messenger_reject
{
Rejects the message indicated by the tracker. If the PN_CUMULATIVE
flag is used this call will also reject all prior messages that
have not already been settled. The semantics of message rejection
are application-specific. If messages represent work requests,
then rejection would leave the sender free to try another receiver,
without fear of having the same task done twice.
}
pn_messenger_rewrite
{
Similar to pn_messenger_route(), except that the destination of
the messag
[jira] [Resolved] (PROTON-375) Engine does not indicate when a link has completed draining.
[ https://issues.apache.org/jira/browse/PROTON-375?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ] Rafael H. Schloming resolved PROTON-375. Resolution: Fixed Assignee: Rafael H. Schloming (was: Ken Giusti) > Engine does not indicate when a link has completed draining. > > > Key: PROTON-375 > URL: https://issues.apache.org/jira/browse/PROTON-375 > Project: Qpid Proton > Issue Type: Bug > Components: proton-c, proton-j >Affects Versions: 0.4 >Reporter: Ken Giusti >Assignee: Rafael H. Schloming > > The engine API provides the pn_link_drain() method, which allows the > application to force the peer to drain its credit. > The engine API does not provide a way for the application to know when the > remote has completed draining. At least there needs to be a way to find out > when the remote credit value has been exhausted. -- This message was sent by Atlassian JIRA (v6.1#6144)
[jira] [Commented] (PROTON-375) Engine does not indicate when a link has completed draining.
[ https://issues.apache.org/jira/browse/PROTON-375?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=13781840#comment-13781840 ] ASF subversion and git services commented on PROTON-375: Commit 1527576 from r...@apache.org in branch 'proton/trunk' [ https://svn.apache.org/r1527576 ] PROTON-375: added pn_link_draining/Receiver.draining() > Engine does not indicate when a link has completed draining. > > > Key: PROTON-375 > URL: https://issues.apache.org/jira/browse/PROTON-375 > Project: Qpid Proton > Issue Type: Bug > Components: proton-c, proton-j >Affects Versions: 0.4 >Reporter: Ken Giusti >Assignee: Ken Giusti > > The engine API provides the pn_link_drain() method, which allows the > application to force the peer to drain its credit. > The engine API does not provide a way for the application to know when the > remote has completed draining. At least there needs to be a way to find out > when the remote credit value has been exhausted. -- This message was sent by Atlassian JIRA (v6.1#6144)
[jira] [Resolved] (PROTON-401) Ordering issue prevents credit drain from working properly
[ https://issues.apache.org/jira/browse/PROTON-401?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ] Rafael H. Schloming resolved PROTON-401. Resolution: Not A Problem > Ordering issue prevents credit drain from working properly > -- > > Key: PROTON-401 > URL: https://issues.apache.org/jira/browse/PROTON-401 > Project: Qpid Proton > Issue Type: Bug > Components: proton-c >Affects Versions: 0.4 >Reporter: Ken Giusti >Assignee: Ken Giusti > Attachments: drain-error.patch, drain-hack.patch > > > If the sending link calls pn_link_drained() to indicate that it has send all > pending data, and afterwards it receives a Flow frame with drain=true from > the peer, then the drain never completes. > The ordering is the problem: if the flow frame w/drain=true is received > _BEFORE_ the sender calls pn_link_drained(), then it works. -- This message was sent by Atlassian JIRA (v6.1#6144)
[jira] [Commented] (PROTON-401) Ordering issue prevents credit drain from working properly
[ https://issues.apache.org/jira/browse/PROTON-401?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=13781811#comment-13781811 ] Ken Giusti commented on PROTON-401: --- I see your point - I'll update the PROTON-200 patch to call drained as you explain in your comment. > Ordering issue prevents credit drain from working properly > -- > > Key: PROTON-401 > URL: https://issues.apache.org/jira/browse/PROTON-401 > Project: Qpid Proton > Issue Type: Bug > Components: proton-c >Affects Versions: 0.4 >Reporter: Ken Giusti >Assignee: Ken Giusti > Attachments: drain-error.patch, drain-hack.patch > > > If the sending link calls pn_link_drained() to indicate that it has send all > pending data, and afterwards it receives a Flow frame with drain=true from > the peer, then the drain never completes. > The ordering is the problem: if the flow frame w/drain=true is received > _BEFORE_ the sender calls pn_link_drained(), then it works. -- This message was sent by Atlassian JIRA (v6.1#6144)
[jira] [Commented] (PROTON-401) Ordering issue prevents credit drain from working properly
[ https://issues.apache.org/jira/browse/PROTON-401?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=13781785#comment-13781785 ] Rafael H. Schloming commented on PROTON-401: After looking at the proposed patch and tests, I believe that this isn't really a bug but rather a missunderstanding of how the API is supposed to behave. The patch is effectively modifying the engine to remember that the application previously indicated that it was drained.This will, however, introduce race conditions since the engine can't actually know if the application is currently drained or simply was drained at some point in the past. To understand the semantics, it helps to imagine an application that has implemented a message queue exposed via AMQP at both ends, with strict semantics regarding "emptiness". In such a scenario, you should be able to push a message onto the tail of the queue, verify that it is accepted, and then drain from the head of the queue and be guaranteed of receiving at least one message. With this patch you would no longer have that guarantee. You would have a race condition where the engine remembers the queue used to be empty and drains the credit even though there is a message to supply. I believe the fix for the scenario is for the application to call drained more frequently, i.e. whenever it wakes up and there is positive credit on the link and no messages to send. > Ordering issue prevents credit drain from working properly > -- > > Key: PROTON-401 > URL: https://issues.apache.org/jira/browse/PROTON-401 > Project: Qpid Proton > Issue Type: Bug > Components: proton-c >Affects Versions: 0.4 >Reporter: Ken Giusti >Assignee: Ken Giusti > Attachments: drain-error.patch, drain-hack.patch > > > If the sending link calls pn_link_drained() to indicate that it has send all > pending data, and afterwards it receives a Flow frame with drain=true from > the peer, then the drain never completes. > The ordering is the problem: if the flow frame w/drain=true is received > _BEFORE_ the sender calls pn_link_drained(), then it works. -- This message was sent by Atlassian JIRA (v6.1#6144)
[jira] [Commented] (PROTON-200) [Proton-c] Credit distribution by messenger is not balanced across all links
[ https://issues.apache.org/jira/browse/PROTON-200?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=13781780#comment-13781780 ] ASF subversion and git services commented on PROTON-200: Commit 1527535 from r...@apache.org in branch 'proton/trunk' [ https://svn.apache.org/r1527535 ] Modified the engine to track how much credit is drained vs used. This should simplify PROTON-200. > [Proton-c] Credit distribution by messenger is not balanced across all links > > > Key: PROTON-200 > URL: https://issues.apache.org/jira/browse/PROTON-200 > Project: Qpid Proton > Issue Type: Bug > Components: proton-c >Affects Versions: 0.3 >Reporter: Ken Giusti >Assignee: Ken Giusti > Attachments: proton-200.patch, upstream-credit.patch > > > The method used to distribute credit to receiving links may lead to > starvation when the number of receiving links is > the available credit. > The distribution algorithm always starts with the same link - see > messenger.c::pn_messenger_flow() -- This message was sent by Atlassian JIRA (v6.1#6144)
