A few of the function names in my doc below are not the proper Ruby
names, but are copied from Python.  Like __new__ and __del__.

I translated them in my head when I was putting text into the Ruby
file -- but failed to translate them in this doc.  

Don't worry -- I'm not going to change any Ruby fn names!






----- Original Message -----


I wanted to show you this in lovely HTML, but all my attempts thus far
(outside of the usual Ruby framework) have created only travesties of
the proper format: diseased and horrible things, lurching through the
stygian depths of my browser like ...  like...

Ah.  Sorry.  Anyway, so --- so, I'm not doing that.
Just settling for practical ASCII.
(It will show up the usual way in the rdoc-generated HTML, once I
check this stuff in.)

This Ruby text is almost identical to the Python text I sent out
a while ago, just a few tweaks attempting to increase perceived
Rubiosity.

There are a few places where the Ruby API lacked some of the other
bindings' (and C code's) interfaces -- those are noted here, but I
left the text in this doc, anticipating that those APIs will show
up shortly.  (Thanks to mcpierce.)

Those places are noted, with the word "NOTE".


=================================================================





-------------------------------------------------------------
class comments
-------------------------------------------------------------
{
  The Messenger class defines a high level interface for
  sending and receiving Messages. Every Messenger contains
  a single logical queue of incoming messages and a single
  logical queue of outgoing messages. These messages in these
  queues may be destined for, or originate from, a variety of
  addresses.
  The messenger interface is single-threaded.  All methods
  except one (interrupt) are intended to be used from within
  the messenger thread.

    Sending & Receiving Messages
    {
      The Messenger class works in conjuction with the Message class. The
      Message class is a mutable holder of message content.

      The put method copies its Message to the outgoing queue, and may
      send queued messages if it can do so without blocking.  The send
      method blocks until it has sent the requested number of messages,
      or until a timeout interrupts the attempt.

      Similarly, the recv method receives messages into the incoming
      queue, and may block as it attempts to receive the requested number
      of messages,  or until timeout is reached. It may receive fewer
      than the requested number.  The get method pops the
      eldest Message off the incoming queue and copies it into the Message
      object that you supply.  It will not block.

      The blocking attribute allows you to turn off blocking behavior entirely,
      in which case send and recv will do whatever they can without
      blocking, and then return.  You can then look at the number
      of incoming and outgoing messages to see how much outstanding work
      still remains.
    }
}





-------------------------------------------------------------
method details
-------------------------------------------------------------
{
  __init__
  {
    Construct a new Messenger with the given name. The name has
    global scope. If a NULL name is supplied, a unique
    name will be chosen.
  }


  __del__
  {
    Destroy the Messenger.  This will close all connections that
    are managed by the Messenger.  Call the stop method before
    destroying the Messenger.
  }


  start
  {
    Currently a no-op placeholder.
    For future compatibility, do not send or recv messages
    before starting the Messenger.
  }


  stop
  {
    Transitions the Messenger to an inactive state. An inactive
    Messenger will not send or receive messages from its internal
    queues. A Messenger should be stopped before being discarded to
    ensure a clean shutdown handshake occurs on any internally managed
    connections.
  }


  subscribe
  {
    Subscribes the Messenger to messages originating from the
    specified source. The source is an address as specified in the
    Messenger introduction with the following addition. If the
    domain portion of the address begins with the '~' character, the
    Messenger will interpret the domain as host/port, bind to it,
    and listen for incoming messages. For example "~0.0.0.0",
    "amqp://~0.0.0.0", and "amqps://~0.0.0.0" will all bind to any
    local interface and listen for incoming messages with the last
    variant only permitting incoming SSL connections.
  }


  put
  {
    Places the content contained in the message onto the outgoing
    queue of the Messenger. This method will never block, however
    it will send any unblocked Messages in the outgoing
    queue immediately and leave any blocked Messages
    remaining in the outgoing queue. The send call may be used to
    block until the outgoing queue is empty. The outgoing property
    may be used to check the depth of the outgoing queue.

    When the content in a given Message object is copied to the outgoing
    message queue, you may then modify or discard the Message object
    without having any impact on the content in the outgoing queue.

    This method returns an outgoing tracker for the Message.  The tracker
    can be used to determine the delivery status of the Message.
  }


  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. (Also works on incoming messages
    that are still within your incoming queue.)
  }


  settle
  {
    Frees a Messenger from tracking the status associated with a given
    tracker. If you don't supply a tracker, all outgoing messages up
    to the most recent will be settled.
  }


  send
  {
    This call will block until the indicated number of messages
    have been sent, or until the operation times out.  If n is -1 this
    call will block until all outgoing messages have been sent. If n is
    0 then this call will send whatever it can without blocking.
  }


  recv
  {
    Receives up to n messages into the incoming queue.  If no value
    for n is supplied, this call will receive as many messages as it
    can buffer internally.  If the Messenger is in blocking mode, this
    call will block until at least one Message is available in the
    incoming queue.
  }


  work
  {
    Sends or receives any outstanding messages queued for a Messenger.
    This will block for the indicated timeout.
    This method may also do I/O work other than sending and receiving
    messages.  For example, closing connections after messenger.stop()
    has been called.
  }


  interrupt
  {
    NOTE -- absent from Ruby.  Jira PROTON-452 filed.

    The Messenger interface is single-threaded.
    This is the only Messenger function intended to be called
    from outside of the Messenger thread.
    Call this from a non-messenger thread to interrupt
    a Messenger that is blocking.
    This will cause any in-progress blocking call to throw
    the Interrupt exception.  If there is no currently blocking
    call, then the next blocking call will be affected, even if it
    is within the same thread that interrupt was called from.
  }


  get
  {
    NOTE -- possible divergence from C API.  Null message input
            should cause popped message to be discarded.
            TODO -- investigate.

    Moves the message from the head of the incoming message queue into
    the supplied message object. Any content in the supplied message
    will be overwritten.
    A tracker for the incoming Message is returned.  The tracker can
    later be used to communicate your acceptance or rejection of the
    Message.
  }


  accept
  {
    Signal the sender that you have acted on the Message
    pointed to by the tracker.  If no tracker is supplied,
    then all messages that have been returned by the get
    method are accepted, except those that have already been
    auto-settled by passing beyond your incoming window size.
  }


  reject
  {
    Rejects the Message indicated by the tracker.  If no tracker
    is supplied, all messages that have been returned by the get
    method are rejected, except those that have already been auto-settled
    by passing beyond your outgoing window size.
  }


  route
  {
    NOTE -- NOT IN RUBY , filed jira PROTON-454


    Adds a routing rule to a Messenger's internal routing table.

    The route procedure may be used to influence how a Messenger will
    internally treat a given address or class of addresses. Every call
    to the route procedure will result in Messenger appending a routing
    rule to its internal routing table.

    Whenever a Message is presented to a Messenger for delivery, it
    will match the address of this message against the set of routing
    rules in order. The first rule to match will be triggered, and
    instead of routing based on the address presented in the message,
    the Messenger will route based on the address supplied in the rule.

    The pattern matching syntax supports two types of matches, a '%'
    will match any character except a '/', and a '*' will match any
    character including a '/'.

    A routing address is specified as a normal AMQP address, however it
    may additionally use substitution variables from the pattern match
    that triggered the rule.

    Any message sent to "foo" will be routed to "amqp://foo.com":

      messenger.route("foo", "amqp://foo.com");

    Any message sent to "foobar" will be routed to
    "amqp://foo.com/bar":

      messenger.route("foobar", "amqp://foo.com/bar");

    Any message sent to bar/<path> will be routed to the corresponding
    path within the amqp://bar.com domain:

      messenger.route("bar/*", "amqp://bar.com/$1");

    Route all messages over TLS:

      messenger.route("amqp:*", "amqps:$1")

    Supply credentials for foo.com:

      messenger.route("amqp://foo.com/*", "amqp://user:passw...@foo.com/$1");

    Supply credentials for all domains:

      messenger.route("amqp://*", "amqp://user:password@$1");

    Route all addresses through a single proxy while preserving the
    original destination:

      messenger.route("amqp://%/*", "amqp://user:password@proxy/$1/$2");

    Route any address through a single broker:

      messenger.route("*", "amqp://user:password@broker/$1");

  }



  rewrite
  {
    NOTE -- NOT IN RUBY , filed jira PROTON-455

    Similar to route(), except that the destination of
    the Message is determined before the message address is rewritten.

    The outgoing address is only rewritten after routing has been
    finalized.  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,
    the receiver will see its outgoing address as "foo".

    The default rewrite rule removes username and password from addresses
    before they are transmitted.
  }

}





-------------------------------------------------------------
property details
-------------------------------------------------------------
{
  name
  {
    The name of the Messenger.
  }


  certificate
  {
    Path to a certificate file for the Messenger. This certificate is
    used when the Messenger accepts or establishes SSL/TLS connections.
    This property must be specified for the Messenger to accept
    incoming SSL/TLS connections and to establish client authenticated
    outgoing SSL/TLS connection. Non client authenticated outgoing SSL/TLS
    connections do not require this property.
  }


  private_key
  {
    Path to a private key file for the Messenger's
    certificate. This property must be specified for the Messenger to
    accept incoming SSL/TLS connections and to establish client
    authenticated outgoing SSL/TLS connection. Non client authenticated
    SSL/TLS connections do not require this property.
  }


  password
  {
    NOTE -- NOT IN RUBY, filed jira PROTON-456

    This property contains the password for the Messenger.private_key
    file, or None if the file is not encrypted.
  }


  trusted_certificates
  {
    A path do a database of trusted certificates for use in verifying the
    peer on an SSL/TLS connection. If this property is None, then the peer
    will not be verified
  }


  timeout
  {
    The timeout property contains the default timeout for blocking
    operations performed by the Messenger.
  }


  blocking
  {
    Enable or disable blocking behavior during message sending
    and receiving.  This affects every blocking call, with the
    exception of work.  Currently, the affected calls are
    send, recv, and stop.
  }


  incoming_window
  {
    The incoming tracking window for the Messenger. The Messenger will
    track the remote status of this many incoming deliveries after they
    have been accepted or rejected. Defaults to zero.

    Messages enter this window only when you take them into your application
    using get.  If your incoming window size is n, and you get n+1 messages
    without explicitly accepting or rejecting the oldest message, then the
    message that passes beyond the edge of the incoming window will be assigned
    the default disposition of its link.
  }


  outgoing_window
  {
    The outgoing tracking window for the Messenger. The Messenger will
    track the remote status of this many outgoing deliveries after calling
    send. Defaults to zero.

    A Message enters this window when you call the put() method with the
    message.  If your outgoing window size is n, and you call put n+1
    times, status information will no longer be available for the
    first message.
  }


  stopped
  {
    Returns true iff a Messenger is in the stopped state.
    This function does not block.
  }


  outgoing
  {
    The outgoing queue depth.
  }


  incoming
  {
    The incoming queue depth.
  }

}




Reply via email to