qpid-proton mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Ted Ross <tr...@redhat.com>
Subject Re: [doc] I will check these in on Friday the 4th...
Date Mon, 30 Sep 2013 18:43:52 GMT
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?




Mime
View raw message