Qpid Proton AMQP Library
This is a library for sending and receiving AMQP messages. It can be used to build clients and servers.
You can install the latest published Gem with
gem install qpid_proton
NOTE: before installing the Gem, you must install the proton-C library.
The proton-C library can be installed by the package manager on many platforms,
e.g. yum install qpid-proton-c # Fedora < 25, RHEL < 7 dnf install qpid-proton-c # Fedora >= 25, RHEL >= 7
You can also download a source release or the latest development code from qpid.apache.org/proton. To build from source:
cmake -DBUILD_BINDINGS=ruby && make
This produces a Gem file at:
You can install the gem with gem install
represents a message that can be sent or received. A message body can be a string or byte sequence encoded any way you choose. However, AMQP also provides standard, interoperable encodings for basic data types like and . The equivalent AMQP encodings can be understood as maps or sequences in any programming langauge with an AMQP library.
allows messages to be transferred to or from a remote AMQP process. The subclass sends messages, the subclass receives them. Links have a source and target address, as explained below.
Links are grouped in a. Messages in the same session are sent sequentially, while those on different sessions can be interleaved. A large message being sent on one session does not block messages being sent on another session.
Sessions belong to a. If you don't need multiple sessions, a connection will create links directly using a default session.
Arepresents the transfer of a message, the subclass allows a receiver to accept or reject an incoming message. The subclass allows a sender to track the status of a sent message and find out if it was accepted or rejected.
A transfer is settled when both ends are done with it. Different settlement methods give different levels of reliability: at-most-once, at-least-once, and exactly-once. See below.
Anatomy of a Proton application
is the top-level object in a Proton application. A client uses to establish connections. A server uses to accept connections.
Proton is an event-driven library. You implement one or more handlers which subclassand override functions to handle AMQP events, such as . Each connection is associated with a handler for its events. polls all connections and listeners and calls the event handling functions on your handlers.
A multi-threaded application can callin more than one thread, the container will use all the threads as a thread pool to dispatch events.
Sources and targets
Every link has two addresses, source and target. The most common pattern for using these addresses is as follows:
When a client creates alink, it sets the source address. This means “I want to receive messages from this source”. This is often referred to as “subscribing” to the source. When a client creates a link, it sets the target address. This means “I want to send to this target”.
In the case of a broker, the source or target usually refers to a queue or topic. In general they can refer to any AMQP-capable node.
In the request-response pattern, a request message carries a reply-to address for the response message. This can be any AMQP address, but it is often useful to create a temporary address for the response message. The client creates a receiver with no source address and the dynamic flag set. The server generates a unique source address for the receiver, which is discarded when the link closes. The client uses this source address as the reply-to when it sends the request, so the response is delivered to the client's receiver.
The server_direct.cpp example shows how to implement a request-response server.
Settling a Message Transfer
A message transfer is settled at one end of a link when that end of the link has finished with the message and forgotten it.
Pre-settled messages are settled by the sender before sending. This gives _at most once_ reliability(also known as _best effort_, unreliable or _fire and forget_) since the sender never knows for sure if the message arrived. If the connection is lost before the message is received by the receiver, the message will not be delivered.
If the sender does not pre-settle a message, then the receiver settles it once it has been processed. The sender is informed of the settlement via the. If the connection is lost before the sender has received notice of settlement, the delivery is considered in-doubt and the sender can re-send it. This ensures it eventually gets delivered (provided the connection and link can be reestablished) but it is possible for multiple copies of the same message are delivered, so the receiver must be aware of that. This is known as at_least_once reliability.
can be called by multiple threads concurrently, giving the container a thread-pool to execute handler methods in parallel.
Instances ofand objects associated with it ( , , , , ) are not thread-safe and must be used correctly when multiple threads call
Calls toand methods by the are automatically serialized for each connection instance.
Other threads may have code similarly serialized by adding it to the
You also need to use theto communicate between a method call for one connection instance, and a different instance in the same container, as separate connections can be processed in parallel.