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
