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?
