qpid-proton mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Michael Goulish <mgoul...@redhat.com>
Subject [doc] I will check these in on Friday the 4th...
Date Mon, 30 Sep 2013 17:46:43 GMT



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



pn_messenger_send
{
  If blocking has been set with pn_messenger_set_blocking, this call
  will block until n messages have been sent.  A value of -1 for n means
  "all messages in the outgoing queue".

  In addition, if a nonzero size has been set for the outgoing window,
  this call will block until all messages within that window have
  been received.  Any blocking will end upon timeout, if one has been
  set by pn_messenger_timeout.

  If blocking has not been set, this call will stop transmitting
  messages when further transmission would require blocking, or when
  the outgoing queue is empty, or when n messages have been sent.
}



pn_messenger_set_blocking
{
  Enable or disable blocking behavior during calls to
  pn_messenger_send and pn_messenger_recv.
}




pn_messenger_set_certificate
{
  Sets the path that will be used to get the certificate
  that will be used to identify this messenger to its
  peers.  The validity of the path is not checked by
  this function.
}



pn_messenger_set_incoming_window
{
  The size of your incoming window limits the number of messages
  that can be accepted or rejected using trackers.  Messages do
  not enter this window when they have been received (pn_messenger_recv)
  onto you incoming queue.  Messages enter this window only when you
  take them into your application using pn_messenger_get.
  If your incoming window size is N, and you get N+1 messages without
  explicitly accepting or rejecting the oldest message, then it will be
  implicitly accepted when it falls off the edge of the incoming window.
}



pn_messenger_set_outgoing_window
{
  The size of your outgoing window limits the number of messages whose
  status you can check on using a tracker, and pn_messenger_status.
  Messages do not enter this window when they are placed on your outgoing
  queue They enter it only when they have been transmitted to the sender.
  If you requested a tracker for an outgoing message, and if it is still
  within this window, you can find the current delivery status of the
  message using pn_messenger_status.
}



pn_messenger_set_timeout
{
  Set timeout, in milliseconds, that will interrupt blocking calls.
}



pn_messenger_start
{
  Currently a no-op placeholder.
  For future compatibility, do not send or receive messages
  before starting the messenger.
}



pn_messenger_status
{
  Find the current delivery status of the outgoing message
  associated with this tracker, as long as the message is still
  within your outgoing window.
}



pn_messenger_stop
{
  Stops a messenger.  A messenger cannot send or
  receive messages after it is stopped.  The messenger may require
  some time to stop if it is busy, and in that case will return
  PN_IN_PROGRESS.  In that case, call pn_messenger_stopped() to see
  if it has fully stopped.
}



pn_messenger_stopped
{
  If a call to pn_messenger_stop returns a non-zero code,
  use this to determine whether the messenger has stopped.
}



Mime
View raw message