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.

Methods

connect   connect_io   inspect   listen   listen_io   new   run   running   schedule   stop   to_s   work_queue  

Included Modules

TimeCompare

Classes and Modules

Class Qpid::Proton::Container::ConnectionTask
Class Qpid::Proton::Container::ListenTask
Class Qpid::Proton::Container::SelectWaker
Class Qpid::Proton::Container::StoppedError

Attributes

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

Public Class methods

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.

Public Instance methods

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}

Number of threads in {run} @return [Bool] {run} thread count

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}

[Validate]