| <!DOCTYPE html> |
| <html> |
| <head> |
| <meta charset="UTF-8"> |
| <meta name="viewport" content="width=device-width, initial-scale=1.0"> |
| <title> |
| File: README |
| |
| — Qpid Proton Ruby API |
| |
| </title> |
| |
| <link rel="stylesheet" href="css/style.css" type="text/css" /> |
| |
| <link rel="stylesheet" href="css/common.css" type="text/css" /> |
| |
| <script type="text/javascript"> |
| pathId = "README"; |
| relpath = ''; |
| </script> |
| |
| |
| <script type="text/javascript" charset="utf-8" src="js/jquery.js"></script> |
| |
| <script type="text/javascript" charset="utf-8" src="js/app.js"></script> |
| |
| |
| </head> |
| <body> |
| <div class="nav_wrap"> |
| <iframe id="nav" src="file_list.html?1"></iframe> |
| <div id="resizer"></div> |
| </div> |
| |
| <div id="main" tabindex="-1"> |
| <div id="header"> |
| <div id="menu"> |
| |
| <a href="_index.html">Index</a> » |
| <span class="title">File: README</span> |
| |
| </div> |
| |
| <div id="search"> |
| |
| <a class="full_list_link" id="class_list_link" |
| href="class_list.html"> |
| |
| <svg width="24" height="24"> |
| <rect x="0" y="4" width="24" height="4" rx="1" ry="1"></rect> |
| <rect x="0" y="12" width="24" height="4" rx="1" ry="1"></rect> |
| <rect x="0" y="20" width="24" height="4" rx="1" ry="1"></rect> |
| </svg> |
| </a> |
| |
| </div> |
| <div class="clear"></div> |
| </div> |
| |
| <div id="content"><div id='filecontents'> |
| <h1 id="label-Qpid+Proton+AMQP+Library">Qpid Proton AMQP Library</h1> |
| |
| <p>This is a library for sending and receiving AMQP messages. It can be used to build clients and servers.</p> |
| |
| <h2 id="label-Installing">Installing</h2> |
| |
| <p>You can install the latest published Gem with</p> |
| |
| <pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_gem'>gem</span> <span class='id identifier rubyid_install'>install</span> <span class='id identifier rubyid_qpid_proton'>qpid_proton</span> |
| </code></pre> |
| |
| <p><strong>NOTE:</strong> before installing the Gem, you must install the proton-C library.</p> |
| |
| <p>The proton-C library can be installed by the package manager on many platforms,</p> |
| |
| <pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_e'>e</span><span class='period'>.</span><span class='id identifier rubyid_g'>g</span><span class='period'>.</span> <span class='id identifier rubyid_yum'>yum</span> <span class='id identifier rubyid_install'>install</span> <span class='id identifier rubyid_qpid'>qpid</span><span class='op'>-</span><span class='id identifier rubyid_proton'>proton</span><span class='op'>-</span><span class='id identifier rubyid_c'>c</span> <span class='comment'># Fedora < 25, RHEL < 7 dnf install |
| </span><span class='id identifier rubyid_qpid'>qpid</span><span class='op'>-</span><span class='id identifier rubyid_proton'>proton</span><span class='op'>-</span><span class='id identifier rubyid_c'>c</span> <span class='comment'># Fedora >= 25, RHEL >= 7 |
| </span></code></pre> |
| |
| <p>You can also download a source release or the latest development code from <a href="http://qpid.apache.org/proton">qpid.apache.org/proton</a>. To build from source:</p> |
| |
| <pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_cmake'>cmake</span> <span class='op'>-</span><span class='const'>DBUILD_BINDINGS</span><span class='op'>=</span><span class='id identifier rubyid_ruby'>ruby</span> <span class='op'>&&</span> <span class='id identifier rubyid_make'>make</span> |
| </code></pre> |
| |
| <p>This produces a Gem file at:</p> |
| |
| <pre class="code ruby"><code class="ruby"><span class='const'>BUILD_DIR</span><span class='op'>/</span><span class='id identifier rubyid_ruby'>ruby</span><span class='op'>/</span><span class='id identifier rubyid_qpid_proton'>qpid_proton</span><span class='op'>-</span><span class='const'>VERSION</span><span class='period'>.</span><span class='id identifier rubyid_gem'>gem</span> |
| </code></pre> |
| |
| <p>You can install the gem with <tt>gem install</tt></p> |
| |
| <h2 id="label-Overview">Overview</h2> |
| |
| <p><span class='object_link'><a href="Qpid/Proton/Message.html" title="Qpid::Proton::Message (class)">Qpid::Proton::Message</a></span> 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 <span class='object_link'>Hash</span> and <span class='object_link'>Array</span>. The equivalent AMQP encodings can be understood as maps or sequences in any programming langauge with an AMQP library.</p> |
| |
| <p><span class='object_link'><a href="Qpid/Proton/Link.html" title="Qpid::Proton::Link (class)">Qpid::Proton::Link</a></span> allows messages to be transferred to or from a remote AMQP process. The <span class='object_link'><a href="Qpid/Proton/Sender.html" title="Qpid::Proton::Sender (class)">Qpid::Proton::Sender</a></span> subclass sends messages, the <span class='object_link'><a href="Qpid/Proton/Receiver.html" title="Qpid::Proton::Receiver (class)">Qpid::Proton::Receiver</a></span> subclass receives them. Links have a source and target address, as explained below.</p> |
| |
| <p>Links are grouped in a <span class='object_link'><a href="Qpid/Proton/Session.html" title="Qpid::Proton::Session (class)">Qpid::Proton::Session</a></span>. 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.</p> |
| |
| <p>Sessions belong to a <span class='object_link'><a href="Qpid/Proton/Connection.html" title="Qpid::Proton::Connection (class)">Qpid::Proton::Connection</a></span>. If you don't need multiple sessions, a connection will create links directly using a default session.</p> |
| |
| <p>A <span class='object_link'><a href="Qpid/Proton/Transfer.html" title="Qpid::Proton::Transfer (class)">Qpid::Proton::Transfer</a></span> represents the transfer of a message, the <span class='object_link'><a href="Qpid/Proton/Delivery.html" title="Qpid::Proton::Delivery (class)">Qpid::Proton::Delivery</a></span> subclass allows a receiver to accept or reject an incoming message. The <span class='object_link'><a href="Qpid/Proton/Tracker.html" title="Qpid::Proton::Tracker (class)">Qpid::Proton::Tracker</a></span> subclass allows a sender to track the status of a sent message and find out if it was accepted or rejected.</p> |
| |
| <p>A transfer is <em>settled</em> 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.</p> |
| |
| <h2 id="label-Anatomy+of+a+Proton+application">Anatomy of a Proton application</h2> |
| |
| <p><span class='object_link'><a href="Qpid/Proton/Container.html" title="Qpid::Proton::Container (class)">Qpid::Proton::Container</a></span> is the top-level object in a Proton application. A client uses <span class='object_link'><a href="Qpid/Proton/Container.html#connect-instance_method" title="Qpid::Proton::Container#connect (method)">Qpid::Proton::Container#connect</a></span> to establish connections. A server uses <span class='object_link'><a href="Qpid/Proton/Container.html#listen-instance_method" title="Qpid::Proton::Container#listen (method)">Qpid::Proton::Container#listen</a></span> to accept connections.</p> |
| |
| <p>Proton is an event-driven library. You implement one or more <em>handlers</em> which subclass <span class='object_link'><a href="Qpid/Proton/MessagingHandler.html" title="Qpid::Proton::MessagingHandler (class)">MessagingHandler</a></span> and override functions to handle AMQP events, such as <span class='object_link'>#on_message</span>. Each connection is associated with a handler for its events. <span class='object_link'><a href="Qpid/Proton/Container.html#run-instance_method" title="Qpid::Proton::Container#run (method)">Qpid::Proton::Container#run</a></span> polls all connections and listeners and calls the event handling functions on your handlers.</p> |
| |
| <p>A multi-threaded application can call <span class='object_link'><a href="Qpid/Proton/Container.html#run-instance_method" title="Qpid::Proton::Container#run (method)">Qpid::Proton::Container#run</a></span> in more than one thread, the container will use all the <span class='object_link'><a href="Qpid/Proton/Container.html#run-instance_method" title="Qpid::Proton::Container#run (method)">#run</a></span> threads as a thread pool to dispatch events.</p> |
| |
| <h2 id="label-Sources+and+targets">Sources and targets</h2> |
| |
| <p>Every link has two addresses, <em>source</em> and <em>target</em>. The most common pattern for using these addresses is as follows:</p> |
| |
| <p>When a client creates a <span class='object_link'><a href="Qpid/Proton/Receiver.html" title="Qpid::Proton::Receiver (class)">Receiver</a></span> link, it sets the <em>source</em> 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 <span class='object_link'><a href="Qpid/Proton/Sender.html" title="Qpid::Proton::Sender (class)">Sender</a></span> link, it sets the <em>target</em> address. This means “I want to send to this target”.</p> |
| |
| <p>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.</p> |
| |
| <p>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.</p> |
| |
| <p>The server_direct.cpp example shows how to implement a request-response server.</p> |
| |
| <h2 id="label-Settling+a+Message+Transfer">Settling a Message Transfer</h2> |
| |
| <p>A message transfer is <em>settled</em> at one end of a link when that end of the link has finished with the message and forgotten it.</p> |
| |
| <p><em>Pre-settled</em> messages are settled by the sender before sending. This gives _at most once_ reliability(also known as _best effort_, <em>unreliable</em> 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.</p> |
| |
| <p>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 <span class='object_link'><a href="Qpid/Proton/Tracker.html" title="Qpid::Proton::Tracker (class)">Tracker</a></span>. 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 <em>at_least_once</em> reliability.</p> |
| |
| <h2 id="label-Multi-threaded+applications">Multi-threaded applications</h2> |
| |
| <p><span class='object_link'><a href="Qpid/Proton/Container.html#run-instance_method" title="Qpid::Proton::Container#run (method)">Qpid::Proton::Container#run</a></span> can be called by multiple threads concurrently, giving the container a thread-pool to execute handler methods in parallel.</p> |
| |
| <p>Instances of <span class='object_link'><a href="Qpid/Proton/Connection.html" title="Qpid::Proton::Connection (class)">Qpid::Proton::Connection</a></span> and objects associated with it (<span class='object_link'><a href="Qpid/Proton/Session.html" title="Qpid::Proton::Session (class)">Qpid::Proton::Session</a></span>, <span class='object_link'><a href="Qpid/Proton/Sender.html" title="Qpid::Proton::Sender (class)">Qpid::Proton::Sender</a></span>, <span class='object_link'><a href="Qpid/Proton/Receiver.html" title="Qpid::Proton::Receiver (class)">Qpid::Proton::Receiver</a></span>, <span class='object_link'><a href="Qpid/Proton/Delivery.html" title="Qpid::Proton::Delivery (class)">Qpid::Proton::Delivery</a></span>, <span class='object_link'><a href="Qpid/Proton/Tracker.html" title="Qpid::Proton::Tracker (class)">Qpid::Proton::Tracker</a></span>) are not thread-safe and must be used correctly when multiple threads call <span class='object_link'><a href="Qpid/Proton/Container.html#run-instance_method" title="Qpid::Proton::Container#run (method)">Qpid::Proton::Container#run</a></span></p> |
| |
| <p>Calls to <span class='object_link'><a href="Qpid/Proton/MessagingHandler.html" title="Qpid::Proton::MessagingHandler (class)">Qpid::Proton::MessagingHandler</a></span> and <span class='object_link'><a href="Qpid/Proton/Listener/Handler.html" title="Qpid::Proton::Listener::Handler (class)">Qpid::Proton::Listener::Handler</a></span> methods by the <span class='object_link'><a href="Qpid/Proton/Container.html" title="Qpid::Proton::Container (class)">Qpid::Proton::Container</a></span> are automatically serialized for each connection instance.</p> |
| |
| <p>Other threads may have code similarly serialized by adding it to the <span class='object_link'><a href="Qpid/Proton/Connection.html#work_queue-instance_method" title="Qpid::Proton::Connection#work_queue (method)">Qpid::Proton::Connection#work_queue</a></span> for the connection. Each object related to a <span class='object_link'><a href="Qpid/Proton/Connection.html" title="Qpid::Proton::Connection (class)">Qpid::Proton::Connection</a></span> also provides a <code>work_queue</code> method.</p> |
| |
| <p>You also need to use the <span class='object_link'><a href="Qpid/Proton/WorkQueue.html" title="Qpid::Proton::WorkQueue (class)">Qpid::Proton::WorkQueue</a></span> to communicate between a <span class='object_link'><a href="Qpid/Proton/MessagingHandler.html" title="Qpid::Proton::MessagingHandler (class)">Qpid::Proton::MessagingHandler</a></span> method call for one connection instance, and a different <span class='object_link'><a href="Qpid/Proton/Connection.html" title="Qpid::Proton::Connection (class)">Qpid::Proton::Connection</a></span> instance in the same container, as separate connections can be processed in parallel.</p> |
| </div></div> |
| |
| <div id="footer"> |
| Generated on Wed Nov 11 12:57:52 2020 by |
| <a href="http://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a> |
| 0.9.24 (ruby-2.7.2). |
| </div> |
| |
| </div> |
| </body> |
| </html> |
