Class | Qpid::Proton::Container |
In: |
lib/core/container.rb
|
Parent: | Object |
An AMQP container manages a set of {Listener}s and {Connection}s which contain {Sender} and {Receiver} links to transfer messages. Usually, each AMQP client or server process has a single container for all of its connections and links.
One or more threads can call {run}, events generated by all the listeners and connections will be dispatched in the {run} threads.
auto_stop | [RW] |
Auto-stop flag.
True (the default) means that the container will stop automatically, as if {stop} had been called, when the last listener or connection closes. False means {run} will not return unless {stop} is called. @return [Bool] auto-stop state |
handler | [R] | @return [MessagingHandler] The container-wide handler |
id | [R] | @return [String] unique identifier for this container |
stopped | [RW] | True if the container has been stopped and can no longer be used. @return [Bool] stopped state |
Create a new Container @overload initialize(id=nil)
@param id [String,Symbol] A unique ID for this container, use random UUID if nil.
@overload initialize(handler=nil, id=nil)
@param id [String,Symbol] A unique ID for this container, use random UUID if nil. @param handler [MessagingHandler] Optional default handler for connections that do not have their own handler (see {#connect} and {#listen}) *Note*: For multi-threaded code, it is recommended to use a separate handler instance for each connection, as a shared handler may be called concurrently.
Open an AMQP connection.
@param url [String, URI] Open a {TCPSocket} to url.host, url.port. url.scheme must be "amqp" or "amqps", url.scheme.nil? is treated as "amqp" url.user, url.password are used as defaults if opts[:user], opts[:password] are nil @option (see Connection#open) @return [Connection] The new AMQP connection
Open an AMQP protocol connection on an existing {IO} object @param io [IO] An existing {IO} object, e.g. a {TCPSocket} @option (see Connection#open)
Listen for incoming AMQP connections
@param url [String,URI] Listen on host:port of the AMQP URL @param handler [Listener::Handler] A {Listener::Handler} object that will be called with events for this listener and can generate a new set of options for each one. @return [Listener] The AMQP listener.
Listen for incoming AMQP connections on an existing server socket. @param io A server socket, for example a {TCPServer} @param handler [Listener::Handler] Handler for events from this listener
Run the container: wait for IO activity, dispatch events to handlers.
*Multi-threaading* : More than one thread can call {run} concurrently, the container will use all {run} threads as a thread pool. Calls to {MessagingHandler} or {Listener::Handler} methods are serialized for each connection or listener. See {WorkQueue} for coordinating with other threads.
Exceptions: If any handler method raises an exception it will stop the container, and the exception will be raised by all calls to {run}. For single threaded code this is often desirable. Multi-threaded server applications should normally rescue exceptions in the handler and deal with them in another way: logging, closing the connection with an error condition, signalling another thread etc.
@return [void] Returns when the container stops, see {stop} and {auto_stop}
@raise [StoppedError] If the container has already been stopped when {run} was called.
@raise [Exception] If any {MessagingHandler} or {Listener::Handler} managed by
the container raises an exception, that exception will be raised by {#run}
Stop the container.
Close all listeners and abort all connections without doing AMQP protocol close.
{stop} returns immediately, calls to {run} will return when all activity is finished.
The container can no longer be used, using a stopped container raises {StoppedError}. Create a new container if you want to resume activity.
@param error [Condition] Optional error condition passed to
{MessagingHandler#on_transport_error} for each connection and {Listener::Handler::on_error} for each listener.
@param panic [Exception] Optional exception to raise from all calls to run()
Get the {WorkQueue} that can be used to schedule code to be run by the container.
Note: to run code that affects a {Connection} or it‘s associated objects, use {Connection#work_queue}