/usr/share/doc/python-oslo.messaging/html/server.html is in python-oslo.messaging 1.4.0.0+really+1.3.1-2.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 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 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 | <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Server — oslo.messaging documentation</title>
<link rel="stylesheet" href="_static/nature.css" type="text/css" />
<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
<link rel="stylesheet" href="_static/tweaks.css" type="text/css" />
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: './',
VERSION: '',
COLLAPSE_INDEX: false,
FILE_SUFFIX: '.html',
HAS_SOURCE: true
};
</script>
<script type="text/javascript" src="_static/jquery.js"></script>
<script type="text/javascript" src="_static/underscore.js"></script>
<script type="text/javascript" src="_static/doctools.js"></script>
<link rel="top" title="oslo.messaging documentation" href="index.html" />
<link rel="next" title="RPC Client" href="rpcclient.html" />
<link rel="prev" title="Target" href="target.html" />
</head>
<body>
<div id="header">
<h1 id="logo"><a href="http://www.openstack.org/">OpenStack</a></h1>
<ul id="navigation">
<li><a href="http://www.openstack.org/" title="Go to the Home page" class="link">Home</a></li>
<li><a href="http://www.openstack.org/projects/" title="Go to the OpenStack Projects page">Projects</a></li>
<li><a href="http://www.openstack.org/user-stories/" title="Go to the User Stories page" class="link">User Stories</a></li>
<li><a href="http://www.openstack.org/community/" title="Go to the Community page" class="link">Community</a></li>
<li><a href="http://www.openstack.org/blog/" title="Go to the OpenStack Blog">Blog</a></li>
<li><a href="http://wiki.openstack.org/" title="Go to the OpenStack Wiki">Wiki</a></li>
<li><a href="http://docs.openstack.org/" title="Go to OpenStack Documentation" class="current">Documentation</a></li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body">
<div class="section" id="module-oslo.messaging.rpc.server">
<span id="server"></span><h1>Server<a class="headerlink" href="#module-oslo.messaging.rpc.server" title="Permalink to this headline">¶</a></h1>
<p>An RPC server exposes a number of endpoints, each of which contain a set of
methods which may be invoked remotely by clients over a given transport.</p>
<p>To create an RPC server, you supply a transport, target and a list of
endpoints.</p>
<p>A transport can be obtained simply by calling the get_transport() method:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">transport</span> <span class="o">=</span> <span class="n">messaging</span><span class="o">.</span><span class="n">get_transport</span><span class="p">(</span><span class="n">conf</span><span class="p">)</span>
</pre></div>
</div>
<p>which will load the appropriate transport driver according to the user’s
messaging configuration configuration. See get_transport() for more details.</p>
<p>The target supplied when creating an RPC server expresses the topic, server
name and - optionally - the exchange to listen on. See Target for more details
on these attributes.</p>
<p>Each endpoint object may have a target attribute which may have namespace and
version fields set. By default, we use the ‘null namespace’ and version 1.0.
Incoming method calls will be dispatched to the first endpoint with the
requested method, a matching namespace and a compatible version number.</p>
<p>RPC servers have start(), stop() and wait() messages to begin handling
requests, stop handling requests and wait for all in-process requests to
complete.</p>
<p>An RPC server class is provided for each supported I/O handling framework.
Currently BlockingRPCServer and eventlet.RPCServer are available.</p>
<p>A simple example of an RPC server with multiple endpoints might be:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">oslo.config</span> <span class="kn">import</span> <span class="n">cfg</span>
<span class="kn">from</span> <span class="nn">oslo</span> <span class="kn">import</span> <span class="n">messaging</span>
<span class="k">class</span> <span class="nc">ServerControlEndpoint</span><span class="p">(</span><span class="nb">object</span><span class="p">):</span>
<span class="n">target</span> <span class="o">=</span> <span class="n">messaging</span><span class="o">.</span><span class="n">Target</span><span class="p">(</span><span class="n">namespace</span><span class="o">=</span><span class="s">'control'</span><span class="p">,</span>
<span class="n">version</span><span class="o">=</span><span class="s">'2.0'</span><span class="p">)</span>
<span class="k">def</span> <span class="nf">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">server</span><span class="p">):</span>
<span class="bp">self</span><span class="o">.</span><span class="n">server</span> <span class="o">=</span> <span class="n">server</span>
<span class="k">def</span> <span class="nf">stop</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">ctx</span><span class="p">):</span>
<span class="bp">self</span><span class="o">.</span><span class="n">server</span><span class="o">.</span><span class="n">stop</span><span class="p">()</span>
<span class="k">class</span> <span class="nc">TestEndpoint</span><span class="p">(</span><span class="nb">object</span><span class="p">):</span>
<span class="k">def</span> <span class="nf">test</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">ctx</span><span class="p">,</span> <span class="n">arg</span><span class="p">):</span>
<span class="k">return</span> <span class="n">arg</span>
<span class="n">transport</span> <span class="o">=</span> <span class="n">messaging</span><span class="o">.</span><span class="n">get_transport</span><span class="p">(</span><span class="n">cfg</span><span class="o">.</span><span class="n">CONF</span><span class="p">)</span>
<span class="n">target</span> <span class="o">=</span> <span class="n">messaging</span><span class="o">.</span><span class="n">Target</span><span class="p">(</span><span class="n">topic</span><span class="o">=</span><span class="s">'test'</span><span class="p">,</span> <span class="n">server</span><span class="o">=</span><span class="s">'server1'</span><span class="p">)</span>
<span class="n">endpoints</span> <span class="o">=</span> <span class="p">[</span>
<span class="n">ServerControlEndpoint</span><span class="p">(</span><span class="bp">self</span><span class="p">),</span>
<span class="n">TestEndpoint</span><span class="p">(),</span>
<span class="p">]</span>
<span class="n">server</span> <span class="o">=</span> <span class="n">messaging</span><span class="o">.</span><span class="n">get_rpc_server</span><span class="p">(</span><span class="n">transport</span><span class="p">,</span> <span class="n">target</span><span class="p">,</span> <span class="n">endpoints</span><span class="p">)</span>
<span class="n">server</span><span class="o">.</span><span class="n">start</span><span class="p">()</span>
<span class="n">server</span><span class="o">.</span><span class="n">wait</span><span class="p">()</span>
</pre></div>
</div>
<p>Clients can invoke methods on the server by sending the request to a topic and
it gets sent to one of the servers listening on the topic, or by sending the
request to a specific server listening on the topic, or by sending the request
to all servers listening on the topic (known as fanout). These modes are chosen
via the server and fanout attributes on Target but the mode used is transparent
to the server.</p>
<p>The first parameter to method invocations is always the request context
supplied by the client.</p>
<p>Parameters to the method invocation are primitive types and so must be the
return values from the methods. By supplying a serializer object, a server can
deserialize a request context and arguments from - and serialize return values
to - primitive types.</p>
<dl class="function">
<dt id="oslo.messaging.get_rpc_server">
<tt class="descclassname">oslo.messaging.</tt><tt class="descname">get_rpc_server</tt><big>(</big><em>transport</em>, <em>target</em>, <em>endpoints</em>, <em>executor='blocking'</em>, <em>serializer=None</em><big>)</big><a class="headerlink" href="#oslo.messaging.get_rpc_server" title="Permalink to this definition">¶</a></dt>
<dd><p>Construct an RPC server.</p>
<p>The executor parameter controls how incoming messages will be received and
dispatched. By default, the most simple executor is used - the blocking
executor.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><strong>transport</strong> (<em>Transport</em>) – the messaging transport</li>
<li><strong>target</strong> (<em>Target</em>) – the exchange, topic and server to listen on</li>
<li><strong>endpoints</strong> (<em>list</em>) – a list of endpoint objects</li>
<li><strong>executor</strong> (<em>str</em>) – name of a message executor - e.g. ‘eventlet’, ‘blocking’</li>
<li><strong>serializer</strong> (<em>Serializer</em>) – an optional entity serializer</li>
</ul>
</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="class">
<dt id="oslo.messaging.RPCDispatcher">
<em class="property">class </em><tt class="descclassname">oslo.messaging.</tt><tt class="descname">RPCDispatcher</tt><big>(</big><em>target</em>, <em>endpoints</em>, <em>serializer</em><big>)</big><a class="headerlink" href="#oslo.messaging.RPCDispatcher" title="Permalink to this definition">¶</a></dt>
<dd><p>A message dispatcher which understands RPC messages.</p>
<p>A MessageHandlingServer is constructed by passing a callable dispatcher
which is invoked with context and message dictionaries each time a message
is received.</p>
<p>RPCDispatcher is one such dispatcher which understands the format of RPC
messages. The dispatcher looks at the namespace, version and method values
in the message and matches those against a list of available endpoints.</p>
<p>Endpoints may have a target attribute describing the namespace and version
of the methods exposed by that object. All public methods on an endpoint
object are remotely invokable by clients.</p>
</dd></dl>
<dl class="class">
<dt id="oslo.messaging.MessageHandlingServer">
<em class="property">class </em><tt class="descclassname">oslo.messaging.</tt><tt class="descname">MessageHandlingServer</tt><big>(</big><em>transport</em>, <em>dispatcher</em>, <em>executor='blocking'</em><big>)</big><a class="headerlink" href="#oslo.messaging.MessageHandlingServer" title="Permalink to this definition">¶</a></dt>
<dd><p>Server for handling messages.</p>
<p>Connect a transport to a dispatcher that knows how process the
message using an executor that knows how the app wants to create
new tasks.</p>
<dl class="method">
<dt id="oslo.messaging.MessageHandlingServer.start">
<tt class="descname">start</tt><big>(</big><big>)</big><a class="headerlink" href="#oslo.messaging.MessageHandlingServer.start" title="Permalink to this definition">¶</a></dt>
<dd><p>Start handling incoming messages.</p>
<p>This method causes the server to begin polling the transport for
incoming messages and passing them to the dispatcher. Message
processing will continue until the stop() method is called.</p>
<p>The executor controls how the server integrates with the applications
I/O handling strategy - it may choose to poll for messages in a new
process, thread or co-operatively scheduled coroutine or simply by
registering a callback with an event loop. Similarly, the executor may
choose to dispatch messages in a new thread, coroutine or simply the
current thread. An RPCServer subclass is available for each I/O
strategy supported by the library, so choose the subclass appropriate
for your program.</p>
</dd></dl>
<dl class="method">
<dt id="oslo.messaging.MessageHandlingServer.stop">
<tt class="descname">stop</tt><big>(</big><big>)</big><a class="headerlink" href="#oslo.messaging.MessageHandlingServer.stop" title="Permalink to this definition">¶</a></dt>
<dd><p>Stop handling incoming messages.</p>
<p>Once this method returns, no new incoming messages will be handled by
the server. However, the server may still be in the process of handling
some messages.</p>
</dd></dl>
<dl class="method">
<dt id="oslo.messaging.MessageHandlingServer.wait">
<tt class="descname">wait</tt><big>(</big><big>)</big><a class="headerlink" href="#oslo.messaging.MessageHandlingServer.wait" title="Permalink to this definition">¶</a></dt>
<dd><p>Wait for message processing to complete.</p>
<p>After calling stop(), there may still be some some existing messages
which have not been completely processed. The wait() method blocks
until all message processing has completed.</p>
</dd></dl>
</dd></dl>
<dl class="function">
<dt id="oslo.messaging.expected_exceptions">
<tt class="descclassname">oslo.messaging.</tt><tt class="descname">expected_exceptions</tt><big>(</big><em>*exceptions</em><big>)</big><a class="headerlink" href="#oslo.messaging.expected_exceptions" title="Permalink to this definition">¶</a></dt>
<dd><p>Decorator for RPC endpoint methods that raise expected exceptions.</p>
<p>Marking an endpoint method with this decorator allows the declaration
of expected exceptions that the RPC server should not consider fatal,
and not log as if they were generated in a real error scenario.</p>
<p>Note that this will cause listed exceptions to be wrapped in an
ExpectedException, which is used internally by the RPC sever. The RPC
client will see the original exception type.</p>
</dd></dl>
<dl class="exception">
<dt id="oslo.messaging.ExpectedException">
<em class="property">exception </em><tt class="descclassname">oslo.messaging.</tt><tt class="descname">ExpectedException</tt><a class="headerlink" href="#oslo.messaging.ExpectedException" title="Permalink to this definition">¶</a></dt>
<dd><p>Encapsulates an expected exception raised by an RPC endpoint</p>
<p>Merely instantiating this exception records the current exception
information, which will be passed back to the RPC client without
exceptional logging.</p>
</dd></dl>
<dl class="function">
<dt id="oslo.messaging.get_local_context">
<tt class="descclassname">oslo.messaging.</tt><tt class="descname">get_local_context</tt><big>(</big><em>ctxt</em><big>)</big><a class="headerlink" href="#oslo.messaging.get_local_context" title="Permalink to this definition">¶</a></dt>
<dd><p>Retrieve the RPC endpoint request context for the current thread.</p>
<p>This method allows any code running in the context of a dispatched RPC
endpoint method to retrieve the context for this request.</p>
<p>This is commonly used for logging so that, for example, you can include the
request ID, user and tenant in every message logged from a RPC endpoint
method.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Returns:</th><td class="field-body">the context for the request dispatched in the current thread</td>
</tr>
</tbody>
</table>
</dd></dl>
</div>
</div>
</div>
</div>
<div class="sphinxsidebar">
<div class="sphinxsidebarwrapper">
<h4>Previous topic</h4>
<p class="topless"><a href="target.html"
title="previous chapter">Target</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="rpcclient.html"
title="next chapter">RPC Client</a></p>
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="_sources/server.txt"
rel="nofollow">Show Source</a></li>
</ul>
<div id="searchbox" style="display: none">
<h3>Quick search</h3>
<form class="search" action="search.html" method="get">
<input type="text" name="q" size="18" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
<p class="searchtip" style="font-size: 90%">
Enter search terms or a module, class or function name.
</p>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="rpcclient.html" title="RPC Client"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="target.html" title="Target"
accesskey="P">previous</a> |</li>
<li><a href="index.html">oslo.messaging documentation</a> »</li>
</ul>
</div>
<div class="footer">
© Copyright 2013, OpenStack Foundation.
Last updated on Nov 21, 2014.
Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.2.3.
</div>
</body>
</html>
|