Google Git
Sign in
apache / qpid-site / 04beb6e78eda47fdfc2fcfc1d2eeb9a270f89a87 / . / content / releases / qpid-proton-0.32.0 / proton / ruby / api / Qpid / Proton / Container.html
blob: c724e5bf2ad993211ae6f942feb7d7912769c3df [file] [log] [blame]
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>
Class: Qpid::Proton::Container
&mdash; 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 = "Qpid::Proton::Container";
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="../../class_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 (C)</a> &raquo;
<span class='title'><span class='object_link'><a href="../../Qpid.html" title="Qpid (module)">Qpid</a></span></span> &raquo; <span class='title'><span class='object_link'><a href="../Proton.html" title="Qpid::Proton (module)">Proton</a></span></span>
&raquo;
<span class="title">Container</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"><h1>Class: Qpid::Proton::Container
</h1>
<div class="box_info">
<dl>
<dt>Inherits:</dt>
<dd>
<span class="inheritName">Object</span>
<ul class="fullTree">
<li>Object</li>
<li class="next">Qpid::Proton::Container</li>
</ul>
<a href="#" class="inheritanceTree">show all</a>
</dd>
</dl>
<dl>
<dt>Defined in:</dt>
<dd>lib/core/container.rb</dd>
</dl>
</div>
<h2>Overview</h2><div class="docstring">
<div class="discussion">
<p>An AMQP container manages a set of <span class='object_link'><a href="Listener.html" title="Qpid::Proton::Listener (class)">Listener</a></span>s and <span class='object_link'><a href="Connection.html" title="Qpid::Proton::Connection (class)">Connection</a></span>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.</p>
<p>One or more threads can call <span class='object_link'><a href="#run-instance_method" title="Qpid::Proton::Container#run (method)">#run</a></span>, events generated by all the listeners and connections will be dispatched in the <span class='object_link'><a href="#run-instance_method" title="Qpid::Proton::Container#run (method)">#run</a></span> threads.</p>
</div>
</div>
<div class="tags">
</div><div id="subclasses">
<h2>Direct Known Subclasses</h2>
<p class="children"><span class='object_link'><a href="Reactor/Container.html" title="Qpid::Proton::Reactor::Container (class)">Reactor::Container</a></span></p>
</div>
<h2>Defined Under Namespace</h2>
<p class="children">
<strong class="classes">Classes:</strong> <span class='object_link'><a href="Container/ConnectionTask.html" title="Qpid::Proton::Container::ConnectionTask (class)">ConnectionTask</a></span>, <span class='object_link'><a href="Container/ListenTask.html" title="Qpid::Proton::Container::ListenTask (class)">ListenTask</a></span>, <span class='object_link'><a href="Container/SelectWaker.html" title="Qpid::Proton::Container::SelectWaker (class)">SelectWaker</a></span>, <span class='object_link'><a href="Container/StoppedError.html" title="Qpid::Proton::Container::StoppedError (class)">StoppedError</a></span>
</p>
<h2>Instance Attribute Summary <small><a href="#" class="summary_toggle">collapse</a></small></h2>
<ul class="summary">
<li class="public ">
<span class="summary_signature">
<a href="#auto_stop-instance_method" title="#auto_stop (instance method)">#<strong>auto_stop</strong> &#x21d2; Bool </a>
</span>
<span class="summary_desc"><div class='inline'>
<p>Auto-stop flag.</p>
</div></span>
</li>
<li class="public ">
<span class="summary_signature">
<a href="#handler-instance_method" title="#handler (instance method)">#<strong>handler</strong> &#x21d2; MessagingHandler </a>
</span>
<span class="note title readonly">readonly</span>
<span class="summary_desc"><div class='inline'>
<p>The container-wide handler.</p>
</div></span>
</li>
<li class="public ">
<span class="summary_signature">
<a href="#id-instance_method" title="#id (instance method)">#<strong>id</strong> &#x21d2; String </a>
</span>
<span class="note title readonly">readonly</span>
<span class="summary_desc"><div class='inline'>
<p>Unique identifier for this container.</p>
</div></span>
</li>
<li class="public ">
<span class="summary_signature">
<a href="#stopped-instance_method" title="#stopped (instance method)">#<strong>stopped</strong> &#x21d2; Bool </a>
</span>
<span class="summary_desc"><div class='inline'>
<p>True if the container has been stopped and can no longer be used.</p>
</div></span>
</li>
</ul>
<h2>
Instance Method Summary
<small><a href="#" class="summary_toggle">collapse</a></small>
</h2>
<ul class="summary">
<li class="public ">
<span class="summary_signature">
<a href="#connect-instance_method" title="#connect (instance method)">#<strong>connect</strong>(url, opts = nil) &#x21d2; Connection </a>
</span>
<span class="summary_desc"><div class='inline'>
<p>Open an AMQP connection.</p>
</div></span>
</li>
<li class="public ">
<span class="summary_signature">
<a href="#connect_io-instance_method" title="#connect_io (instance method)">#<strong>connect_io</strong>(io, opts = nil) </a>
</span>
<span class="summary_desc"><div class='inline'>
<p>Open an AMQP protocol connection on an existing IO object.</p>
</div></span>
</li>
<li class="public ">
<span class="summary_signature">
<a href="#initialize-instance_method" title="#initialize (instance method)">#<strong>initialize</strong>(*args) &#x21d2; Container </a>
</span>
<span class="note title constructor">constructor</span>
<span class="summary_desc"><div class='inline'>
<p>Create a new Container.</p>
</div></span>
</li>
<li class="public ">
<span class="summary_signature">
<a href="#inspect-instance_method" title="#inspect (instance method)">#<strong>inspect</strong> </a>
</span>
<span class="summary_desc"><div class='inline'></div></span>
</li>
<li class="public ">
<span class="summary_signature">
<a href="#listen-instance_method" title="#listen (instance method)">#<strong>listen</strong>(url, handler = Listener::Handler.new) &#x21d2; Listener </a>
</span>
<span class="summary_desc"><div class='inline'>
<p>Listen for incoming AMQP connections.</p>
</div></span>
</li>
<li class="public ">
<span class="summary_signature">
<a href="#listen_io-instance_method" title="#listen_io (instance method)">#<strong>listen_io</strong>(io, handler = Listener::Handler.new) </a>
</span>
<span class="summary_desc"><div class='inline'>
<p>Listen for incoming AMQP connections on an existing server socket.</p>
</div></span>
</li>
<li class="public ">
<span class="summary_signature">
<a href="#run-instance_method" title="#run (instance method)">#<strong>run</strong> </a>
</span>
<span class="summary_desc"><div class='inline'>
<p>Run the container: wait for IO activity, dispatch events to handlers.</p>
</div></span>
</li>
<li class="public ">
<span class="summary_signature">
<a href="#running-instance_method" title="#running (instance method)">#<strong>running</strong> &#x21d2; Bool </a>
</span>
<span class="summary_desc"><div class='inline'>
<p>Number of threads in <span class='object_link'><a href="#run-instance_method" title="Qpid::Proton::Container#run (method)">#run</a></span>.</p>
</div></span>
</li>
<li class="public ">
<span class="summary_signature">
<a href="#stop-instance_method" title="#stop (instance method)">#<strong>stop</strong>(error = nil, panic = nil) </a>
</span>
<span class="summary_desc"><div class='inline'>
<p>Stop the container.</p>
</div></span>
</li>
<li class="public ">
<span class="summary_signature">
<a href="#to_s-instance_method" title="#to_s (instance method)">#<strong>to_s</strong> </a>
</span>
<span class="summary_desc"><div class='inline'></div></span>
</li>
<li class="public ">
<span class="summary_signature">
<a href="#work_queue-instance_method" title="#work_queue (instance method)">#<strong>work_queue</strong> </a>
</span>
<span class="summary_desc"><div class='inline'>
<p>Get the <span class='object_link'><a href="WorkQueue.html" title="Qpid::Proton::WorkQueue (class)">WorkQueue</a></span> that can be used to schedule code to be run by the container.</p>
</div></span>
</li>
</ul>
<div id="constructor_details" class="method_details_list">
<h2>Constructor Details</h2>
<div class="method_details first">
<h3 class="signature first" id="initialize-instance_method">
<span class="overload">#<strong>initialize</strong>(id = nil) &#x21d2; <tt><span class='object_link'><a href="" title="Qpid::Proton::Container (class)">Container</a></span></tt> </span>
<span class="overload">#<strong>initialize</strong>(handler = nil, id = nil) &#x21d2; <tt><span class='object_link'><a href="" title="Qpid::Proton::Container (class)">Container</a></span></tt> </span>
</h3><div class="docstring">
<div class="discussion">
<p>Create a new Container</p>
</div>
</div>
<div class="tags">
<p class="tag_title">Overloads:</p>
<ul class="overload">
<li class="overload_item">
<span class="signature">#<strong>initialize</strong>(id = nil) &#x21d2; <tt><span class='object_link'><a href="" title="Qpid::Proton::Container (class)">Container</a></span></tt> </span>
<div class="docstring">
<div class="discussion">
</div>
</div>
<div class="tags">
<p class="tag_title">Parameters:</p>
<ul class="param">
<li>
<span class='name'>id</span>
<span class='type'>(<tt>String</tt>, <tt>Symbol</tt>)</span>
<em class="default">(defaults to: <tt>nil</tt>)</em>
&mdash;
<div class='inline'>
<p>A unique ID for this container, use random UUID if nil.</p>
</div>
</li>
</ul>
</div>
</li>
<li class="overload_item">
<span class="signature">#<strong>initialize</strong>(handler = nil, id = nil) &#x21d2; <tt><span class='object_link'><a href="" title="Qpid::Proton::Container (class)">Container</a></span></tt> </span>
<div class="docstring">
<div class="discussion">
</div>
</div>
<div class="tags">
<p class="tag_title">Parameters:</p>
<ul class="param">
<li>
<span class='name'>id</span>
<span class='type'>(<tt>String</tt>, <tt>Symbol</tt>)</span>
<em class="default">(defaults to: <tt>nil</tt>)</em>
&mdash;
<div class='inline'>
<p>A unique ID for this container, use random UUID if nil.</p>
</div>
</li>
<li>
<span class='name'>handler</span>
<span class='type'>(<tt><span class='object_link'><a href="MessagingHandler.html" title="Qpid::Proton::MessagingHandler (class)">MessagingHandler</a></span></tt>)</span>
<em class="default">(defaults to: <tt>nil</tt>)</em>
&mdash;
<div class='inline'>
<p>Optional default handler for connections that do not have their own handler (see <span class='object_link'><a href="#connect-instance_method" title="Qpid::Proton::Container#connect (method)">#connect</a></span> and <span class='object_link'><a href="#listen-instance_method" title="Qpid::Proton::Container#listen (method)">#listen</a></span>)</p>
<p><strong>Note</strong>: For multi-threaded code, it is recommended to use a separate handler instance for each connection, as a shared handler may be called concurrently.</p>
</div>
</li>
</ul>
</div>
</li>
</ul>
</div><table class="source_code">
<tr>
<td>
<pre class="lines">
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85</pre>
</td>
<td>
<pre class="code"><span class="info file"># File 'lib/core/container.rb', line 55</span>
<span class='kw'>def</span> <span class='id identifier rubyid_initialize'>initialize</span><span class='lparen'>(</span><span class='op'>*</span><span class='id identifier rubyid_args'>args</span><span class='rparen'>)</span>
<span class='ivar'>@handler</span><span class='comma'>,</span> <span class='ivar'>@id</span> <span class='op'>=</span> <span class='kw'>nil</span>
<span class='kw'>case</span> <span class='id identifier rubyid_args'>args</span><span class='period'>.</span><span class='id identifier rubyid_size'>size</span>
<span class='kw'>when</span> <span class='int'>2</span> <span class='kw'>then</span> <span class='ivar'>@handler</span><span class='comma'>,</span> <span class='ivar'>@id</span> <span class='op'>=</span> <span class='id identifier rubyid_args'>args</span>
<span class='kw'>when</span> <span class='int'>1</span> <span class='kw'>then</span>
<span class='ivar'>@id</span> <span class='op'>=</span> <span class='const'>String</span><span class='period'>.</span><span class='id identifier rubyid_try_convert'>try_convert</span><span class='lparen'>(</span><span class='id identifier rubyid_args'>args</span><span class='lbracket'>[</span><span class='int'>0</span><span class='rbracket'>]</span><span class='rparen'>)</span> <span class='op'>||</span> <span class='lparen'>(</span><span class='id identifier rubyid_args'>args</span><span class='lbracket'>[</span><span class='int'>0</span><span class='rbracket'>]</span><span class='period'>.</span><span class='id identifier rubyid_to_s'>to_s</span> <span class='kw'>if</span> <span class='id identifier rubyid_args'>args</span><span class='lbracket'>[</span><span class='int'>0</span><span class='rbracket'>]</span><span class='period'>.</span><span class='id identifier rubyid_is_a?'>is_a?</span> <span class='const'>Symbol</span><span class='rparen'>)</span>
<span class='ivar'>@handler</span> <span class='op'>=</span> <span class='id identifier rubyid_args'>args</span><span class='lbracket'>[</span><span class='int'>0</span><span class='rbracket'>]</span> <span class='kw'>unless</span> <span class='ivar'>@id</span>
<span class='kw'>when</span> <span class='int'>0</span> <span class='kw'>then</span>
<span class='kw'>else</span> <span class='id identifier rubyid_raise'>raise</span> <span class='const'><span class='object_link'><a href="ArgumentError.html" title="Qpid::Proton::ArgumentError (class)">ArgumentError</a></span></span><span class='comma'>,</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>wrong number of arguments (given </span><span class='embexpr_beg'>#{</span><span class='id identifier rubyid_args'>args</span><span class='period'>.</span><span class='id identifier rubyid_size'>size</span><span class='embexpr_end'>}</span><span class='tstring_content'>, expected 0..2</span><span class='tstring_end'>&quot;</span></span>
<span class='kw'>end</span> <span class='comment'># Use an empty messaging adapter to give default behaviour if there&#39;s no global handler.
</span>
<span class='ivar'>@adapter</span> <span class='op'>=</span> <span class='const'><span class='object_link'><a href="Handler.html" title="Qpid::Proton::Handler (module)">Handler</a></span></span><span class='op'>::</span><span class='const'><span class='object_link'><a href="Handler/Adapter.html" title="Qpid::Proton::Handler::Adapter (class)">Adapter</a></span></span><span class='period'>.</span><span class='id identifier rubyid_adapt'><span class='object_link'><a href="Handler/Adapter.html#adapt-class_method" title="Qpid::Proton::Handler::Adapter.adapt (method)">adapt</a></span></span><span class='lparen'>(</span><span class='ivar'>@handler</span><span class='rparen'>)</span> <span class='op'>||</span> <span class='const'><span class='object_link'><a href="Handler.html" title="Qpid::Proton::Handler (module)">Handler</a></span></span><span class='op'>::</span><span class='const'><span class='object_link'><a href="Handler/MessagingAdapter.html" title="Qpid::Proton::Handler::MessagingAdapter (class)">MessagingAdapter</a></span></span><span class='period'>.</span><span class='id identifier rubyid_new'><span class='object_link'><a href="Handler/Adapter.html#initialize-instance_method" title="Qpid::Proton::Handler::Adapter#initialize (method)">new</a></span></span><span class='lparen'>(</span><span class='kw'>nil</span><span class='rparen'>)</span>
<span class='ivar'>@id</span> <span class='op'>=</span> <span class='lparen'>(</span><span class='ivar'>@id</span> <span class='op'>||</span> <span class='const'>SecureRandom</span><span class='period'>.</span><span class='id identifier rubyid_uuid'>uuid</span><span class='rparen'>)</span><span class='period'>.</span><span class='id identifier rubyid_freeze'>freeze</span>
<span class='comment'># Threading and implementation notes: see comment on #run_one
</span> <span class='ivar'>@work</span> <span class='op'>=</span> <span class='const'>Queue</span><span class='period'>.</span><span class='id identifier rubyid_new'>new</span>
<span class='ivar'>@work</span> <span class='op'>&lt;&lt;</span> <span class='symbol'>:start</span>
<span class='ivar'>@work</span> <span class='op'>&lt;&lt;</span> <span class='symbol'>:select</span>
<span class='ivar'>@wake</span> <span class='op'>=</span> <span class='const'><span class='object_link'><a href="Container/SelectWaker.html" title="Qpid::Proton::Container::SelectWaker (class)">SelectWaker</a></span></span><span class='period'>.</span><span class='id identifier rubyid_new'><span class='object_link'><a href="Container/SelectWaker.html#initialize-instance_method" title="Qpid::Proton::Container::SelectWaker#initialize (method)">new</a></span></span> <span class='comment'># Wakes #run thread in IO.select
</span> <span class='ivar'>@auto_stop</span> <span class='op'>=</span> <span class='kw'>true</span> <span class='comment'># Stop when @active drops to 0
</span> <span class='ivar'>@work_queue</span> <span class='op'>=</span> <span class='const'><span class='object_link'><a href="WorkQueue.html" title="Qpid::Proton::WorkQueue (class)">WorkQueue</a></span></span><span class='period'>.</span><span class='id identifier rubyid_new'>new</span><span class='lparen'>(</span><span class='kw'>self</span><span class='rparen'>)</span> <span class='comment'># work scheduled by other threads for :select context
</span>
<span class='comment'># Following instance variables protected by lock
</span> <span class='ivar'>@lock</span> <span class='op'>=</span> <span class='const'>Mutex</span><span class='period'>.</span><span class='id identifier rubyid_new'>new</span>
<span class='ivar'>@active</span> <span class='op'>=</span> <span class='int'>0</span> <span class='comment'># All active tasks, in @selectable, @work or being processed
</span> <span class='ivar'>@selectable</span> <span class='op'>=</span> <span class='const'>Set</span><span class='period'>.</span><span class='id identifier rubyid_new'>new</span> <span class='comment'># Tasks ready to block in IO.select
</span> <span class='ivar'>@running</span> <span class='op'>=</span> <span class='int'>0</span> <span class='comment'># Count of #run threads
</span> <span class='ivar'>@stopped</span> <span class='op'>=</span> <span class='kw'>false</span> <span class='comment'># #stop called
</span> <span class='ivar'>@stop_err</span> <span class='op'>=</span> <span class='kw'>nil</span> <span class='comment'># Optional error to pass to tasks, from #stop
</span> <span class='ivar'>@panic</span> <span class='op'>=</span> <span class='kw'>nil</span> <span class='comment'># Exception caught in a run thread, to be raised by all run threads
</span><span class='kw'>end</span></pre>
</td>
</tr>
</table>
</div>
</div>
<div id="instance_attr_details" class="attr_details">
<h2>Instance Attribute Details</h2>
<span id="auto_stop=-instance_method"></span>
<div class="method_details first">
<h3 class="signature first" id="auto_stop-instance_method">
#<strong>auto_stop</strong> &#x21d2; <tt>Bool</tt>
</h3><div class="docstring">
<div class="discussion">
<p>Auto-stop flag.</p>
<p>True (the default) means that the container will stop automatically, as if <span class='object_link'><a href="#stop-instance_method" title="Qpid::Proton::Container#stop (method)">#stop</a></span> had been called, when the last listener or connection closes.</p>
<p>False means <span class='object_link'><a href="#run-instance_method" title="Qpid::Proton::Container#run (method)">#run</a></span> will not return unless <span class='object_link'><a href="#stop-instance_method" title="Qpid::Proton::Container#stop (method)">#stop</a></span> is called.</p>
</div>
</div>
<div class="tags">
<p class="tag_title">Returns:</p>
<ul class="return">
<li>
<span class='type'>(<tt>Bool</tt>)</span>
&mdash;
<div class='inline'>
<p>auto-stop state</p>
</div>
</li>
</ul>
</div><table class="source_code">
<tr>
<td>
<pre class="lines">
104
105
106</pre>
</td>
<td>
<pre class="code"><span class="info file"># File 'lib/core/container.rb', line 104</span>
<span class='kw'>def</span> <span class='id identifier rubyid_auto_stop'>auto_stop</span>
<span class='ivar'>@auto_stop</span>
<span class='kw'>end</span></pre>
</td>
</tr>
</table>
</div>
<span id=""></span>
<div class="method_details ">
<h3 class="signature " id="handler-instance_method">
#<strong>handler</strong> &#x21d2; <tt><span class='object_link'><a href="MessagingHandler.html" title="Qpid::Proton::MessagingHandler (class)">MessagingHandler</a></span></tt> <span class="extras">(readonly)</span>
</h3><div class="docstring">
<div class="discussion">
<p>Returns The container-wide handler.</p>
</div>
</div>
<div class="tags">
<p class="tag_title">Returns:</p>
<ul class="return">
<li>
<span class='type'>(<tt><span class='object_link'><a href="MessagingHandler.html" title="Qpid::Proton::MessagingHandler (class)">MessagingHandler</a></span></tt>)</span>
&mdash;
<div class='inline'>
<p>The container-wide handler</p>
</div>
</li>
</ul>
</div><table class="source_code">
<tr>
<td>
<pre class="lines">
88
89
90</pre>
</td>
<td>
<pre class="code"><span class="info file"># File 'lib/core/container.rb', line 88</span>
<span class='kw'>def</span> <span class='id identifier rubyid_handler'>handler</span>
<span class='ivar'>@handler</span>
<span class='kw'>end</span></pre>
</td>
</tr>
</table>
</div>
<span id=""></span>
<div class="method_details ">
<h3 class="signature " id="id-instance_method">
#<strong>id</strong> &#x21d2; <tt>String</tt> <span class="extras">(readonly)</span>
</h3><div class="docstring">
<div class="discussion">
<p>Returns unique identifier for this container.</p>
</div>
</div>
<div class="tags">
<p class="tag_title">Returns:</p>
<ul class="return">
<li>
<span class='type'>(<tt>String</tt>)</span>
&mdash;
<div class='inline'>
<p>unique identifier for this container</p>
</div>
</li>
</ul>
</div><table class="source_code">
<tr>
<td>
<pre class="lines">
91
92
93</pre>
</td>
<td>
<pre class="code"><span class="info file"># File 'lib/core/container.rb', line 91</span>
<span class='kw'>def</span> <span class='id identifier rubyid_id'>id</span>
<span class='ivar'>@id</span>
<span class='kw'>end</span></pre>
</td>
</tr>
</table>
</div>
<span id="stopped=-instance_method"></span>
<div class="method_details ">
<h3 class="signature " id="stopped-instance_method">
#<strong>stopped</strong> &#x21d2; <tt>Bool</tt>
</h3><div class="docstring">
<div class="discussion">
<p>True if the container has been stopped and can no longer be used.</p>
</div>
</div>
<div class="tags">
<p class="tag_title">Returns:</p>
<ul class="return">
<li>
<span class='type'>(<tt>Bool</tt>)</span>
&mdash;
<div class='inline'>
<p>stopped state</p>
</div>
</li>
</ul>
</div><table class="source_code">
<tr>
<td>
<pre class="lines">
108
109
110</pre>
</td>
<td>
<pre class="code"><span class="info file"># File 'lib/core/container.rb', line 108</span>
<span class='kw'>def</span> <span class='id identifier rubyid_stopped'>stopped</span>
<span class='ivar'>@stopped</span>
<span class='kw'>end</span></pre>
</td>
</tr>
</table>
</div>
</div>
<div id="instance_method_details" class="method_details_list">
<h2>Instance Method Details</h2>
<div class="method_details first">
<h3 class="signature first" id="connect-instance_method">
#<strong>connect</strong>(url, opts = nil) &#x21d2; <tt><span class='object_link'><a href="Connection.html" title="Qpid::Proton::Connection (class)">Connection</a></span></tt>
</h3><div class="docstring">
<div class="discussion">
<p>Open an AMQP connection.</p>
<p>url.scheme must be “amqp” or “amqps”, url.scheme.nil? is treated as “amqp” url.user, url.password are used as defaults if <a href=":user">opts</a>, <a href=":password">opts</a> are nil</p>
</div>
</div>
<div class="tags">
<p class="tag_title">Parameters:</p>
<ul class="param">
<li>
<span class='name'>url</span>
<span class='type'>(<tt>String</tt>, <tt><span class='object_link'>URI</span></tt>)</span>
&mdash;
<div class='inline'>
<p>Open a TCPSocket to url.host, url.port.</p>
</div>
</li>
</ul>
<p class="tag_title">Options Hash (<tt>opts</tt>):</p>
<ul class="option">
<li>
<span class="name">:handler</span>
<span class="type">(<tt><span class='object_link'><a href="MessagingHandler.html" title="Qpid::Proton::MessagingHandler (class)">MessagingHandler</a></span></tt>)</span>
<span class="default">
</span>
&mdash; <div class='inline'>
<p>handler for events related to this connection.</p>
</div>
</li>
<li>
<span class="name">:user</span>
<span class="type">(<tt>String</tt>)</span>
<span class="default">
</span>
&mdash; <div class='inline'>
<p>User name for authentication</p>
</div>
</li>
<li>
<span class="name">:password</span>
<span class="type">(<tt>String</tt>)</span>
<span class="default">
</span>
&mdash; <div class='inline'>
<p>Authentication secret</p>
</div>
</li>
<li>
<span class="name">:virtual_host</span>
<span class="type">(<tt>String</tt>)</span>
<span class="default">
</span>
&mdash; <div class='inline'>
<p>Virtual host name</p>
</div>
</li>
<li>
<span class="name">:container_id</span>
<span class="type">(<tt>String</tt>)</span>
<span class="default">
&mdash; default:
<tt>provided by {Container}</tt>
</span>
&mdash; <div class='inline'>
<p>override advertised container-id</p>
</div>
</li>
<li>
<span class="name">:properties</span>
<span class="type">(<tt><span class='object_link'>Hash</span>&lt;Symbol=&gt;Object&gt;</tt>)</span>
<span class="default">
</span>
&mdash; <div class='inline'>
<p>Application-defined properties</p>
</div>
</li>
<li>
<span class="name">:offered_capabilities</span>
<span class="type">(<tt><span class='object_link'>Array</span>&lt;Symbol&gt;</tt>)</span>
<span class="default">
</span>
&mdash; <div class='inline'>
<p>Extensions the endpoint supports</p>
</div>
</li>
<li>
<span class="name">:desired_capabilities</span>
<span class="type">(<tt><span class='object_link'>Array</span>&lt;Symbol&gt;</tt>)</span>
<span class="default">
</span>
&mdash; <div class='inline'>
<p>Extensions the endpoint can use</p>
</div>
</li>
<li>
<span class="name">:idle_timeout</span>
<span class="type">(<tt>Numeric</tt>)</span>
<span class="default">
</span>
&mdash; <div class='inline'>
<p>Seconds before closing an idle connection</p>
</div>
</li>
<li>
<span class="name">:max_sessions</span>
<span class="type">(<tt>Integer</tt>)</span>
<span class="default">
</span>
&mdash; <div class='inline'>
<p>Limit the number of active sessions</p>
</div>
</li>
<li>
<span class="name">:max_frame_size</span>
<span class="type">(<tt>Integer</tt>)</span>
<span class="default">
</span>
&mdash; <div class='inline'>
<p>Limit the size of AMQP frames</p>
</div>
</li>
<li>
<span class="name">:sasl_enabled</span>
<span class="type">(<tt>Boolean</tt>)</span>
<span class="default">
&mdash; default:
<tt>false</tt>
</span>
&mdash; <div class='inline'>
<p>Enable or disable SASL.</p>
</div>
</li>
<li>
<span class="name">:sasl_allow_insecure_mechs</span>
<span class="type">(<tt>Boolean</tt>)</span>
<span class="default">
&mdash; default:
<tt>false</tt>
</span>
&mdash; <div class='inline'>
<p>Allow mechanisms that send secrets in cleartext</p>
</div>
</li>
<li>
<span class="name">:sasl_allowed_mechs</span>
<span class="type">(<tt>String</tt>)</span>
<span class="default">
</span>
&mdash; <div class='inline'>
<p>Specify the SASL mechanisms allowed for this connection. The value is a space-separated list of mechanism names. The mechanisms allowed by default are determined by your SASL library and system configuration, with two exceptions: GSSAPI and GSS-SPNEGO are disabled by default. To enable them, you must explicitly add them using this option. Clients must set the allowed mechanisms before the the outgoing connection is attempted. Servers must set them before the listening connection is setup.</p>
</div>
</li>
<li>
<span class="name">:ssl_domain</span>
<span class="type">(<tt><span class='object_link'><a href="SSLDomain.html" title="Qpid::Proton::SSLDomain (class)">SSLDomain</a></span></tt>)</span>
<span class="default">
</span>
&mdash; <div class='inline'>
<p>SSL configuration domain.</p>
</div>
</li>
</ul>
<p class="tag_title">Returns:</p>
<ul class="return">
<li>
<span class='type'>(<tt><span class='object_link'><a href="Connection.html" title="Qpid::Proton::Connection (class)">Connection</a></span></tt>)</span>
&mdash;
<div class='inline'>
<p>The new AMQP connection</p>
</div>
</li>
</ul>
</div><table class="source_code">
<tr>
<td>
<pre class="lines">
121
122
123
124
125
126
127
128
129
130
131</pre>
</td>
<td>
<pre class="code"><span class="info file"># File 'lib/core/container.rb', line 121</span>
<span class='kw'>def</span> <span class='id identifier rubyid_connect'>connect</span><span class='lparen'>(</span><span class='id identifier rubyid_url'>url</span><span class='comma'>,</span> <span class='id identifier rubyid_opts'>opts</span><span class='op'>=</span><span class='kw'>nil</span><span class='rparen'>)</span>
<span class='id identifier rubyid_not_stopped'>not_stopped</span>
<span class='id identifier rubyid_url'>url</span> <span class='op'>=</span> <span class='const'><span class='object_link'><a href="../../Qpid.html" title="Qpid (module)">Qpid</a></span></span><span class='op'>::</span><span class='const'><span class='object_link'><a href="../Proton.html" title="Qpid::Proton (module)">Proton</a></span></span><span class='op'>::</span><span class='id identifier rubyid_uri'><span class='object_link'><a href="../Proton.html#uri-class_method" title="Qpid::Proton.uri (method)">uri</a></span></span> <span class='id identifier rubyid_url'>url</span>
<span class='id identifier rubyid_opts'>opts</span> <span class='op'>||=</span> <span class='lbrace'>{</span><span class='rbrace'>}</span>
<span class='kw'>if</span> <span class='id identifier rubyid_url'>url</span><span class='period'>.</span><span class='id identifier rubyid_user'>user</span> <span class='op'>||</span> <span class='id identifier rubyid_url'>url</span><span class='period'>.</span><span class='id identifier rubyid_password'>password</span>
<span class='id identifier rubyid_opts'>opts</span><span class='lbracket'>[</span><span class='symbol'>:user</span><span class='rbracket'>]</span> <span class='op'>||=</span> <span class='id identifier rubyid_url'>url</span><span class='period'>.</span><span class='id identifier rubyid_user'>user</span>
<span class='id identifier rubyid_opts'>opts</span><span class='lbracket'>[</span><span class='symbol'>:password</span><span class='rbracket'>]</span> <span class='op'>||=</span> <span class='id identifier rubyid_url'>url</span><span class='period'>.</span><span class='id identifier rubyid_password'>password</span>
<span class='kw'>end</span>
<span class='id identifier rubyid_opts'>opts</span><span class='lbracket'>[</span><span class='symbol'>:ssl_domain</span><span class='rbracket'>]</span> <span class='op'>||=</span> <span class='const'><span class='object_link'><a href="SSLDomain.html" title="Qpid::Proton::SSLDomain (class)">SSLDomain</a></span></span><span class='period'>.</span><span class='id identifier rubyid_new'>new</span><span class='lparen'>(</span><span class='const'><span class='object_link'><a href="SSLDomain.html" title="Qpid::Proton::SSLDomain (class)">SSLDomain</a></span></span><span class='op'>::</span><span class='const'>MODE_CLIENT</span><span class='rparen'>)</span> <span class='kw'>if</span> <span class='id identifier rubyid_url'>url</span><span class='period'>.</span><span class='id identifier rubyid_scheme'>scheme</span> <span class='op'>==</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>amqps</span><span class='tstring_end'>&quot;</span></span>
<span class='id identifier rubyid_connect_io'>connect_io</span><span class='lparen'>(</span><span class='const'>TCPSocket</span><span class='period'>.</span><span class='id identifier rubyid_new'>new</span><span class='lparen'>(</span><span class='id identifier rubyid_url'>url</span><span class='period'>.</span><span class='id identifier rubyid_host'>host</span><span class='comma'>,</span> <span class='id identifier rubyid_url'>url</span><span class='period'>.</span><span class='id identifier rubyid_port'>port</span><span class='rparen'>)</span><span class='comma'>,</span> <span class='id identifier rubyid_opts'>opts</span><span class='rparen'>)</span>
<span class='kw'>end</span></pre>
</td>
</tr>
</table>
</div>
<div class="method_details ">
<h3 class="signature " id="connect_io-instance_method">
#<strong>connect_io</strong>(io, opts = nil)
</h3><div class="docstring">
<div class="discussion">
<p>Open an AMQP protocol connection on an existing IO object</p>
</div>
</div>
<div class="tags">
<p class="tag_title">Parameters:</p>
<ul class="param">
<li>
<span class='name'>io</span>
<span class='type'>(<tt>IO</tt>)</span>
&mdash;
<div class='inline'>
<p>An existing IO object, e.g. a TCPSocket</p>
</div>
</li>
</ul>
<p class="tag_title">Options Hash (<tt>opts</tt>):</p>
<ul class="option">
<li>
<span class="name">:handler</span>
<span class="type">(<tt><span class='object_link'><a href="MessagingHandler.html" title="Qpid::Proton::MessagingHandler (class)">MessagingHandler</a></span></tt>)</span>
<span class="default">
</span>
&mdash; <div class='inline'>
<p>handler for events related to this connection.</p>
</div>
</li>
<li>
<span class="name">:user</span>
<span class="type">(<tt>String</tt>)</span>
<span class="default">
</span>
&mdash; <div class='inline'>
<p>User name for authentication</p>
</div>
</li>
<li>
<span class="name">:password</span>
<span class="type">(<tt>String</tt>)</span>
<span class="default">
</span>
&mdash; <div class='inline'>
<p>Authentication secret</p>
</div>
</li>
<li>
<span class="name">:virtual_host</span>
<span class="type">(<tt>String</tt>)</span>
<span class="default">
</span>
&mdash; <div class='inline'>
<p>Virtual host name</p>
</div>
</li>
<li>
<span class="name">:container_id</span>
<span class="type">(<tt>String</tt>)</span>
<span class="default">
&mdash; default:
<tt>provided by {Container}</tt>
</span>
&mdash; <div class='inline'>
<p>override advertised container-id</p>
</div>
</li>
<li>
<span class="name">:properties</span>
<span class="type">(<tt><span class='object_link'>Hash</span>&lt;Symbol=&gt;Object&gt;</tt>)</span>
<span class="default">
</span>
&mdash; <div class='inline'>
<p>Application-defined properties</p>
</div>
</li>
<li>
<span class="name">:offered_capabilities</span>
<span class="type">(<tt><span class='object_link'>Array</span>&lt;Symbol&gt;</tt>)</span>
<span class="default">
</span>
&mdash; <div class='inline'>
<p>Extensions the endpoint supports</p>
</div>
</li>
<li>
<span class="name">:desired_capabilities</span>
<span class="type">(<tt><span class='object_link'>Array</span>&lt;Symbol&gt;</tt>)</span>
<span class="default">
</span>
&mdash; <div class='inline'>
<p>Extensions the endpoint can use</p>
</div>
</li>
<li>
<span class="name">:idle_timeout</span>
<span class="type">(<tt>Numeric</tt>)</span>
<span class="default">
</span>
&mdash; <div class='inline'>
<p>Seconds before closing an idle connection</p>
</div>
</li>
<li>
<span class="name">:max_sessions</span>
<span class="type">(<tt>Integer</tt>)</span>
<span class="default">
</span>
&mdash; <div class='inline'>
<p>Limit the number of active sessions</p>
</div>
</li>
<li>
<span class="name">:max_frame_size</span>
<span class="type">(<tt>Integer</tt>)</span>
<span class="default">
</span>
&mdash; <div class='inline'>
<p>Limit the size of AMQP frames</p>
</div>
</li>
<li>
<span class="name">:sasl_enabled</span>
<span class="type">(<tt>Boolean</tt>)</span>
<span class="default">
&mdash; default:
<tt>false</tt>
</span>
&mdash; <div class='inline'>
<p>Enable or disable SASL.</p>
</div>
</li>
<li>
<span class="name">:sasl_allow_insecure_mechs</span>
<span class="type">(<tt>Boolean</tt>)</span>
<span class="default">
&mdash; default:
<tt>false</tt>
</span>
&mdash; <div class='inline'>
<p>Allow mechanisms that send secrets in cleartext</p>
</div>
</li>
<li>
<span class="name">:sasl_allowed_mechs</span>
<span class="type">(<tt>String</tt>)</span>
<span class="default">
</span>
&mdash; <div class='inline'>
<p>Specify the SASL mechanisms allowed for this connection. The value is a space-separated list of mechanism names. The mechanisms allowed by default are determined by your SASL library and system configuration, with two exceptions: GSSAPI and GSS-SPNEGO are disabled by default. To enable them, you must explicitly add them using this option. Clients must set the allowed mechanisms before the the outgoing connection is attempted. Servers must set them before the listening connection is setup.</p>
</div>
</li>
<li>
<span class="name">:ssl_domain</span>
<span class="type">(<tt><span class='object_link'><a href="SSLDomain.html" title="Qpid::Proton::SSLDomain (class)">SSLDomain</a></span></tt>)</span>
<span class="default">
</span>
&mdash; <div class='inline'>
<p>SSL configuration domain.</p>
</div>
</li>
</ul>
</div><table class="source_code">
<tr>
<td>
<pre class="lines">
136
137
138
139
140
141
142</pre>
</td>
<td>
<pre class="code"><span class="info file"># File 'lib/core/container.rb', line 136</span>
<span class='kw'>def</span> <span class='id identifier rubyid_connect_io'>connect_io</span><span class='lparen'>(</span><span class='id identifier rubyid_io'>io</span><span class='comma'>,</span> <span class='id identifier rubyid_opts'>opts</span><span class='op'>=</span><span class='kw'>nil</span><span class='rparen'>)</span>
<span class='id identifier rubyid_not_stopped'>not_stopped</span>
<span class='id identifier rubyid_cd'>cd</span> <span class='op'>=</span> <span class='id identifier rubyid_connection_driver'>connection_driver</span><span class='lparen'>(</span><span class='id identifier rubyid_io'>io</span><span class='comma'>,</span> <span class='id identifier rubyid_opts'>opts</span><span class='rparen'>)</span>
<span class='id identifier rubyid_cd'>cd</span><span class='period'>.</span><span class='id identifier rubyid_connection'>connection</span><span class='period'>.</span><span class='id identifier rubyid_open'>open</span><span class='lparen'>(</span><span class='rparen'>)</span>
<span class='id identifier rubyid_add'>add</span><span class='lparen'>(</span><span class='id identifier rubyid_cd'>cd</span><span class='rparen'>)</span>
<span class='id identifier rubyid_cd'>cd</span><span class='period'>.</span><span class='id identifier rubyid_connection'>connection</span>
<span class='kw'>end</span></pre>
</td>
</tr>
</table>
</div>
<div class="method_details ">
<h3 class="signature " id="inspect-instance_method">
#<strong>inspect</strong>
</h3><div class="docstring">
<div class="discussion">
</div>
</div>
<div class="tags">
</div><table class="source_code">
<tr>
<td>
<pre class="lines">
94</pre>
</td>
<td>
<pre class="code"><span class="info file"># File 'lib/core/container.rb', line 94</span>
<span class='kw'>def</span> <span class='id identifier rubyid_inspect'>inspect</span><span class='lparen'>(</span><span class='rparen'>)</span> <span class='id identifier rubyid_to_s'>to_s</span><span class='semicolon'>;</span> <span class='kw'>end</span></pre>
</td>
</tr>
</table>
</div>
<div class="method_details ">
<h3 class="signature " id="listen-instance_method">
#<strong>listen</strong>(url, handler = Listener::Handler.new) &#x21d2; <tt><span class='object_link'><a href="Listener.html" title="Qpid::Proton::Listener (class)">Listener</a></span></tt>
</h3><div class="docstring">
<div class="discussion">
<p>Listen for incoming AMQP connections</p>
<p>with events for this listener and can generate a new set of options for each one.</p>
</div>
</div>
<div class="tags">
<p class="tag_title">Parameters:</p>
<ul class="param">
<li>
<span class='name'>url</span>
<span class='type'>(<tt>String</tt>, <tt><span class='object_link'>URI</span></tt>)</span>
&mdash;
<div class='inline'>
<p>Listen on host:port of the AMQP URL</p>
</div>
</li>
<li>
<span class='name'>handler</span>
<span class='type'>(<tt><span class='object_link'><a href="Listener/Handler.html" title="Qpid::Proton::Listener::Handler (class)">Listener::Handler</a></span></tt>)</span>
<em class="default">(defaults to: <tt>Listener::Handler.new</tt>)</em>
&mdash;
<div class='inline'>
<p>A <span class='object_link'><a href="Listener/Handler.html" title="Qpid::Proton::Listener::Handler (class)">Listener::Handler</a></span> object that will be called</p>
</div>
</li>
</ul>
<p class="tag_title">Returns:</p>
<ul class="return">
<li>
<span class='type'>(<tt><span class='object_link'><a href="Listener.html" title="Qpid::Proton::Listener (class)">Listener</a></span></tt>)</span>
&mdash;
<div class='inline'>
<p>The AMQP listener.</p>
</div>
</li>
</ul>
</div><table class="source_code">
<tr>
<td>
<pre class="lines">
151
152
153
154
155
156</pre>
</td>
<td>
<pre class="code"><span class="info file"># File 'lib/core/container.rb', line 151</span>
<span class='kw'>def</span> <span class='id identifier rubyid_listen'>listen</span><span class='lparen'>(</span><span class='id identifier rubyid_url'>url</span><span class='comma'>,</span> <span class='id identifier rubyid_handler'>handler</span><span class='op'>=</span><span class='const'>Listener</span><span class='op'>::</span><span class='const'>Handler</span><span class='period'>.</span><span class='id identifier rubyid_new'>new</span><span class='rparen'>)</span>
<span class='id identifier rubyid_not_stopped'>not_stopped</span>
<span class='id identifier rubyid_url'>url</span> <span class='op'>=</span> <span class='const'><span class='object_link'><a href="../../Qpid.html" title="Qpid (module)">Qpid</a></span></span><span class='op'>::</span><span class='const'><span class='object_link'><a href="../Proton.html" title="Qpid::Proton (module)">Proton</a></span></span><span class='op'>::</span><span class='id identifier rubyid_uri'><span class='object_link'><a href="../Proton.html#uri-class_method" title="Qpid::Proton.uri (method)">uri</a></span></span> <span class='id identifier rubyid_url'>url</span> <span class='comment'># TODO aconway 2017-11-01: amqps, SSL
</span>
<span class='id identifier rubyid_listen_io'>listen_io</span><span class='lparen'>(</span><span class='const'>TCPServer</span><span class='period'>.</span><span class='id identifier rubyid_new'>new</span><span class='lparen'>(</span><span class='id identifier rubyid_url'>url</span><span class='period'>.</span><span class='id identifier rubyid_host'>host</span><span class='comma'>,</span> <span class='id identifier rubyid_url'>url</span><span class='period'>.</span><span class='id identifier rubyid_port'>port</span><span class='rparen'>)</span><span class='comma'>,</span> <span class='id identifier rubyid_handler'>handler</span><span class='rparen'>)</span>
<span class='kw'>end</span></pre>
</td>
</tr>
</table>
</div>
<div class="method_details ">
<h3 class="signature " id="listen_io-instance_method">
#<strong>listen_io</strong>(io, handler = Listener::Handler.new)
</h3><div class="docstring">
<div class="discussion">
<p>Listen for incoming AMQP connections on an existing server socket.</p>
</div>
</div>
<div class="tags">
<p class="tag_title">Parameters:</p>
<ul class="param">
<li>
<span class='name'>io</span>
<span class='type'></span>
&mdash;
<div class='inline'>
<p>A server socket, for example a TCPServer</p>
</div>
</li>
<li>
<span class='name'>handler</span>
<span class='type'>(<tt><span class='object_link'><a href="Listener/Handler.html" title="Qpid::Proton::Listener::Handler (class)">Listener::Handler</a></span></tt>)</span>
<em class="default">(defaults to: <tt>Listener::Handler.new</tt>)</em>
&mdash;
<div class='inline'>
<p>Handler for events from this listener</p>
</div>
</li>
</ul>
</div><table class="source_code">
<tr>
<td>
<pre class="lines">
162
163
164
165
166
167</pre>
</td>
<td>
<pre class="code"><span class="info file"># File 'lib/core/container.rb', line 162</span>
<span class='kw'>def</span> <span class='id identifier rubyid_listen_io'>listen_io</span><span class='lparen'>(</span><span class='id identifier rubyid_io'>io</span><span class='comma'>,</span> <span class='id identifier rubyid_handler'>handler</span><span class='op'>=</span><span class='const'>Listener</span><span class='op'>::</span><span class='const'>Handler</span><span class='period'>.</span><span class='id identifier rubyid_new'>new</span><span class='rparen'>)</span>
<span class='id identifier rubyid_not_stopped'>not_stopped</span>
<span class='id identifier rubyid_l'>l</span> <span class='op'>=</span> <span class='const'><span class='object_link'><a href="Container/ListenTask.html" title="Qpid::Proton::Container::ListenTask (class)">ListenTask</a></span></span><span class='period'>.</span><span class='id identifier rubyid_new'><span class='object_link'><a href="Container/ListenTask.html#initialize-instance_method" title="Qpid::Proton::Container::ListenTask#initialize (method)">new</a></span></span><span class='lparen'>(</span><span class='id identifier rubyid_io'>io</span><span class='comma'>,</span> <span class='id identifier rubyid_handler'>handler</span><span class='comma'>,</span> <span class='kw'>self</span><span class='rparen'>)</span>
<span class='id identifier rubyid_add'>add</span><span class='lparen'>(</span><span class='id identifier rubyid_l'>l</span><span class='rparen'>)</span>
<span class='id identifier rubyid_l'>l</span><span class='period'>.</span><span class='id identifier rubyid_listener'>listener</span>
<span class='kw'>end</span></pre>
</td>
</tr>
</table>
</div>
<div class="method_details ">
<h3 class="signature " id="run-instance_method">
#<strong>run</strong>
</h3><div class="docstring">
<div class="discussion">
<p class="note returns_void">This method returns an undefined value.</p>
<p>Run the container: wait for IO activity, dispatch events to handlers.</p>
<p><strong>Multi-threaading</strong> : More than one thread can call <span class='object_link'><a href="#run-instance_method" title="Qpid::Proton::Container#run (method)">#run</a></span> concurrently, the container will use all <span class='object_link'><a href="#run-instance_method" title="Qpid::Proton::Container#run (method)">#run</a></span> threads as a thread pool. Calls to <span class='object_link'><a href="MessagingHandler.html" title="Qpid::Proton::MessagingHandler (class)">MessagingHandler</a></span> or <span class='object_link'><a href="Listener/Handler.html" title="Qpid::Proton::Listener::Handler (class)">Listener::Handler</a></span> methods are serialized for each connection or listener. See <span class='object_link'><a href="WorkQueue.html" title="Qpid::Proton::WorkQueue (class)">WorkQueue</a></span> for coordinating with other threads.</p>
<p><strong>Exceptions</strong>: If any handler method raises an exception it will stop the container, and the exception will be raised by all calls to <span class='object_link'><a href="#run-instance_method" title="Qpid::Proton::Container#run (method)">#run</a></span>. 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.</p>
</div>
</div>
<div class="tags">
<p class="tag_title">Raises:</p>
<ul class="raise">
<li>
<span class='type'>(<tt><span class='object_link'><a href="Container/StoppedError.html" title="Qpid::Proton::Container::StoppedError (class)">StoppedError</a></span></tt>)</span>
&mdash;
<div class='inline'>
<p>If the container has already been stopped when <span class='object_link'><a href="#run-instance_method" title="Qpid::Proton::Container#run (method)">#run</a></span> was called.</p>
</div>
</li>
<li>
<span class='type'>(<tt>Exception</tt>)</span>
&mdash;
<div class='inline'>
<p>If any <span class='object_link'><a href="MessagingHandler.html" title="Qpid::Proton::MessagingHandler (class)">MessagingHandler</a></span> or <span class='object_link'><a href="Listener/Handler.html" title="Qpid::Proton::Listener::Handler (class)">Listener::Handler</a></span> managed by the container raises an exception, that exception will be raised by <span class='object_link'><a href="#run-instance_method" title="Qpid::Proton::Container#run (method)">#run</a></span></p>
</div>
</li>
</ul>
</div><table class="source_code">
<tr>
<td>
<pre class="lines">
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209</pre>
</td>
<td>
<pre class="code"><span class="info file"># File 'lib/core/container.rb', line 191</span>
<span class='kw'>def</span> <span class='id identifier rubyid_run'>run</span>
<span class='ivar'>@lock</span><span class='period'>.</span><span class='id identifier rubyid_synchronize'>synchronize</span> <span class='kw'>do</span>
<span class='ivar'>@running</span> <span class='op'>+=</span> <span class='int'>1</span> <span class='comment'># Note: ensure clause below will decrement @running
</span> <span class='id identifier rubyid_raise'>raise</span> <span class='const'><span class='object_link'><a href="Container/StoppedError.html" title="Qpid::Proton::Container::StoppedError (class)">StoppedError</a></span></span> <span class='kw'>if</span> <span class='ivar'>@stopped</span>
<span class='kw'>end</span>
<span class='kw'>while</span> <span class='id identifier rubyid_task'>task</span> <span class='op'>=</span> <span class='ivar'>@work</span><span class='period'>.</span><span class='id identifier rubyid_pop'>pop</span>
<span class='id identifier rubyid_run_one'>run_one</span><span class='lparen'>(</span><span class='id identifier rubyid_task'>task</span><span class='comma'>,</span> <span class='const'>Time</span><span class='period'>.</span><span class='id identifier rubyid_now'>now</span><span class='rparen'>)</span>
<span class='kw'>end</span>
<span class='ivar'>@lock</span><span class='period'>.</span><span class='id identifier rubyid_synchronize'>synchronize</span> <span class='lbrace'>{</span> <span class='id identifier rubyid_raise'>raise</span> <span class='ivar'>@panic</span> <span class='kw'>if</span> <span class='ivar'>@panic</span> <span class='rbrace'>}</span>
<span class='kw'>ensure</span>
<span class='ivar'>@lock</span><span class='period'>.</span><span class='id identifier rubyid_synchronize'>synchronize</span> <span class='kw'>do</span>
<span class='kw'>if</span> <span class='lparen'>(</span><span class='ivar'>@running</span> <span class='op'>-=</span> <span class='int'>1</span><span class='rparen'>)</span> <span class='op'>&gt;</span> <span class='int'>0</span>
<span class='id identifier rubyid_work_wake'>work_wake</span> <span class='kw'>nil</span> <span class='comment'># Signal the next thread
</span> <span class='kw'>else</span>
<span class='comment'># This is the last thread, no need to do maybe_panic around this final handler call.
</span> <span class='ivar'>@adapter</span><span class='period'>.</span><span class='id identifier rubyid_on_container_stop'>on_container_stop</span><span class='lparen'>(</span><span class='kw'>self</span><span class='rparen'>)</span> <span class='kw'>if</span> <span class='ivar'>@adapter</span><span class='period'>.</span><span class='id identifier rubyid_respond_to?'>respond_to?</span> <span class='symbol'>:on_container_stop</span>
<span class='kw'>end</span>
<span class='kw'>end</span>
<span class='kw'>end</span></pre>
</td>
</tr>
</table>
</div>
<div class="method_details ">
<h3 class="signature " id="running-instance_method">
#<strong>running</strong> &#x21d2; <tt>Bool</tt>
</h3><div class="docstring">
<div class="discussion">
<p>Number of threads in <span class='object_link'><a href="#run-instance_method" title="Qpid::Proton::Container#run (method)">#run</a></span></p>
</div>
</div>
<div class="tags">
<p class="tag_title">Returns:</p>
<ul class="return">
<li>
<span class='type'>(<tt>Bool</tt>)</span>
&mdash;
<div class='inline'>
<p><span class='object_link'><a href="#run-instance_method" title="Qpid::Proton::Container#run (method)">#run</a></span> thread count</p>
</div>
</li>
</ul>
</div><table class="source_code">
<tr>
<td>
<pre class="lines">
112</pre>
</td>
<td>
<pre class="code"><span class="info file"># File 'lib/core/container.rb', line 112</span>
<span class='kw'>def</span> <span class='id identifier rubyid_running'>running</span><span class='lparen'>(</span><span class='rparen'>)</span> <span class='ivar'>@lock</span><span class='period'>.</span><span class='id identifier rubyid_synchronize'>synchronize</span> <span class='lbrace'>{</span> <span class='ivar'>@running</span> <span class='rbrace'>}</span><span class='semicolon'>;</span> <span class='kw'>end</span></pre>
</td>
</tr>
</table>
</div>
<div class="method_details ">
<h3 class="signature " id="stop-instance_method">
#<strong>stop</strong>(error = nil, panic = nil)
</h3><div class="docstring">
<div class="discussion">
<p>Stop the container.</p>
<p>Close all listeners and abort all connections without doing AMQP protocol close.</p>
<p><span class='object_link'><a href="#stop-instance_method" title="Qpid::Proton::Container#stop (method)">#stop</a></span> returns immediately, calls to <span class='object_link'><a href="#run-instance_method" title="Qpid::Proton::Container#run (method)">#run</a></span> will return when all activity is finished.</p>
<p>The container can no longer be used, using a stopped container raises <span class='object_link'><a href="Container/StoppedError.html" title="Qpid::Proton::Container::StoppedError (class)">StoppedError</a></span>. Create a new container if you want to resume activity.</p>
</div>
</div>
<div class="tags">
<p class="tag_title">Parameters:</p>
<ul class="param">
<li>
<span class='name'>error</span>
<span class='type'>(<tt><span class='object_link'><a href="Condition.html" title="Qpid::Proton::Condition (class)">Condition</a></span></tt>)</span>
<em class="default">(defaults to: <tt>nil</tt>)</em>
&mdash;
<div class='inline'>
<p>Optional error condition passed to <span class='object_link'>MessagingHandler#on_transport_error</span> for each connection and Listener::Handler::on_error for each listener.</p>
</div>
</li>
<li>
<span class='name'>panic</span>
<span class='type'>(<tt>Exception</tt>)</span>
<em class="default">(defaults to: <tt>nil</tt>)</em>
&mdash;
<div class='inline'>
<p>Optional exception to raise from all calls to run()</p>
</div>
</li>
</ul>
</div><table class="source_code">
<tr>
<td>
<pre class="lines">
227
228
229
230
231
232
233
234
235
236
237
238
239
240</pre>
</td>
<td>
<pre class="code"><span class="info file"># File 'lib/core/container.rb', line 227</span>
<span class='kw'>def</span> <span class='id identifier rubyid_stop'>stop</span><span class='lparen'>(</span><span class='id identifier rubyid_error'>error</span><span class='op'>=</span><span class='kw'>nil</span><span class='comma'>,</span> <span class='id identifier rubyid_panic'>panic</span><span class='op'>=</span><span class='kw'>nil</span><span class='rparen'>)</span>
<span class='ivar'>@lock</span><span class='period'>.</span><span class='id identifier rubyid_synchronize'>synchronize</span> <span class='kw'>do</span>
<span class='kw'>return</span> <span class='kw'>if</span> <span class='ivar'>@stopped</span>
<span class='ivar'>@stop_err</span> <span class='op'>=</span> <span class='const'><span class='object_link'><a href="Condition.html" title="Qpid::Proton::Condition (class)">Condition</a></span></span><span class='period'>.</span><span class='id identifier rubyid_convert'><span class='object_link'><a href="Condition.html#convert-class_method" title="Qpid::Proton::Condition.convert (method)">convert</a></span></span><span class='lparen'>(</span><span class='id identifier rubyid_error'>error</span><span class='rparen'>)</span>
<span class='ivar'>@panic</span> <span class='op'>=</span> <span class='id identifier rubyid_panic'>panic</span>
<span class='ivar'>@stopped</span> <span class='op'>=</span> <span class='kw'>true</span>
<span class='id identifier rubyid_check_stop_lh'>check_stop_lh</span> <span class='comment'># NOTE: @stopped =&gt;
</span> <span class='comment'># - no new run threads can join
</span> <span class='comment'># - no more select calls after next wakeup
</span> <span class='comment'># - once @active == 0, all threads will be stopped with nil
</span>
<span class='kw'>end</span>
<span class='id identifier rubyid_wake'>wake</span>
<span class='kw'>end</span></pre>
</td>
</tr>
</table>
</div>
<div class="method_details ">
<h3 class="signature " id="to_s-instance_method">
#<strong>to_s</strong>
</h3><div class="docstring">
<div class="discussion">
</div>
</div>
<div class="tags">
</div><table class="source_code">
<tr>
<td>
<pre class="lines">
93</pre>
</td>
<td>
<pre class="code"><span class="info file"># File 'lib/core/container.rb', line 93</span>
<span class='kw'>def</span> <span class='id identifier rubyid_to_s'>to_s</span><span class='lparen'>(</span><span class='rparen'>)</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>#&lt;</span><span class='embexpr_beg'>#{</span><span class='kw'>self</span><span class='period'>.</span><span class='id identifier rubyid_class'>class</span><span class='embexpr_end'>}</span><span class='tstring_content'> id=</span><span class='embexpr_beg'>#{</span><span class='id identifier rubyid_id'>id</span><span class='period'>.</span><span class='id identifier rubyid_inspect'>inspect</span><span class='embexpr_end'>}</span><span class='tstring_content'>&gt;</span><span class='tstring_end'>&quot;</span></span><span class='semicolon'>;</span> <span class='kw'>end</span></pre>
</td>
</tr>
</table>
</div>
<div class="method_details ">
<h3 class="signature " id="work_queue-instance_method">
#<strong>work_queue</strong>
</h3><div class="docstring">
<div class="discussion">
<p>Get the <span class='object_link'><a href="WorkQueue.html" title="Qpid::Proton::WorkQueue (class)">WorkQueue</a></span> that can be used to schedule code to be run by the container.</p>
<p>Note: to run code that affects a <span class='object_link'><a href="Connection.html" title="Qpid::Proton::Connection (class)">Qpid::Proton::Connection</a></span> or it&#39;s associated objects, use <span class='object_link'><a href="Connection.html#work_queue-instance_method" title="Qpid::Proton::Connection#work_queue (method)">Qpid::Proton::Connection#work_queue</a></span></p>
</div>
</div>
<div class="tags">
</div><table class="source_code">
<tr>
<td>
<pre class="lines">
246</pre>
</td>
<td>
<pre class="code"><span class="info file"># File 'lib/core/container.rb', line 246</span>
<span class='kw'>def</span> <span class='id identifier rubyid_work_queue'>work_queue</span><span class='lparen'>(</span><span class='rparen'>)</span> <span class='ivar'>@work_queue</span><span class='semicolon'>;</span> <span class='kw'>end</span></pre>
</td>
</tr>
</table>
</div>
</div>
</div>
<div id="footer">
Generated on Wed Nov 11 12:57:53 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>