You are viewing a plain text version of this content. The canonical link for it is here.
Posted to proton@qpid.apache.org by Michael Goulish <mg...@redhat.com> on 2013/11/19 15:12:53 UTC
please review: Ruby Messenger Doc
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:password@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.
}
}
Re: please review: Ruby Messenger Doc
Posted by Michael Goulish <mg...@redhat.com>.
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:password@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.
}
}
Re: please review: Ruby Messenger Doc
Posted by "Darryl L. Pierce" <dp...@redhat.com>.
On Tue, Nov 19, 2013 at 09:12:53AM -0500, Michael Goulish wrote:
> 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...
Can you ping me in IRC? I'd like to see what issues you're having with
generating the HTML documentation and see if we can't solve this.
--
Darryl L. Pierce, Sr. Software Engineer @ Red Hat, Inc.
Delivering value year after year.
Red Hat ranks #1 in value among software vendors.
http://www.redhat.com/promo/vendor/