qpid-proton mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Rafael Schloming <...@alum.mit.edu>
Subject Re: [doc] I will check these in on Friday the 4th...
Date Tue, 01 Oct 2013 11:44:22 GMT
Comments inline...

On Mon, Sep 30, 2013 at 2:43 PM, Ted Ross <tross@redhat.com> wrote:

> 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?
>

This is a good point. We probably need some sort of API level description
that states basic assumptions like this. To answer Ted's question, in
general the API is single threaded. The only exception to that is
pn_messenger_interrupt which can be safely called from another thread to
interrupt a blocking call.


>
> -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.


That's not intentional, it's just passing up the driver error code. We
probably should fix this.


>
>
>  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?


The description isn't quite right. It is supposed to return the number of
messages that could be inbound, i.e. the credit you've given messenger to
use for incoming messages. This does correspond to what was most recently
passed to recv, however it should change as incoming messages arrive.


>
>
>  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?


It allows a layer of indirection between addresses in your application and
addresses you use on the wire, e.g. you can use "FOOBAR" inside your app
and then configure messenger to rewrite that into "//bar.com/foo" or
something like that. Internally the mechanism is used to rewrite
credentials out of addresses.


>
>
>  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?
>

It doesn't block, it just reports whether a messenger is started/stopped.
There shouldn't be any multi threading implications. I guess it might help
to define what started/stopped means. A stopped messenger has no network
connections and is not allowed to create them (hypothetically, right now
that part is not enforced). A started messenger might not have network
connections, but is allowed to create them if needed.

--Rafael

Mime
  • Unnamed multipart/alternative (inline, None, 0 bytes)
View raw message