<!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>More Than Just Bindings — PyZMQ v2.2.0.1 documentation</title>
<link rel="stylesheet" href="_static/default.css" type="text/css" />
<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: '',
VERSION: '2.2.0.1',
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="shortcut icon" href="_static/zeromq.ico"/>
<link rel="top" title="PyZMQ v2.2.0.1 documentation" href="index.html" />
<link rel="next" title="Serializing messages with PyZMQ" href="serialization.html" />
<link rel="prev" title="PyZMQ and Unicode" href="unicode.html" />
</head>
<body>
<div style="background-color: white; text-align: left; padding: 10px 10px 15px 15px">
<a href="index.html"><img src="_static/logo.png" border="0" alt="PyZMQ Documentation"/></a>
</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="serialization.html" title="Serializing messages with PyZMQ"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="unicode.html" title="PyZMQ and Unicode"
accesskey="P">previous</a> |</li>
<li><a href="index.html">home</a>| </li>
<li><a href="search.html">search</a>| </li>
<li><a href="api/index.html">API</a> »</li>
</ul>
</div>
<div class="sphinxsidebar">
<div class="sphinxsidebarwrapper">
<h3><a href="index.html">Table Of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">More Than Just Bindings</a><ul>
<li><a class="reference internal" href="#the-core-as-bindings">The Core as Bindings</a></li>
<li><a class="reference internal" href="#thread-safety">Thread Safety</a></li>
<li><a class="reference internal" href="#socket-options-as-attributes">Socket Options as Attributes</a><ul>
<li><a class="reference internal" href="#default-options-on-the-context">Default Options on the Context</a></li>
</ul>
</li>
<li><a class="reference internal" href="#core-extensions">Core Extensions</a><ul>
<li><a class="reference internal" href="#builtin-serialization">Builtin Serialization</a></li>
<li><a class="reference internal" href="#messagetracker">MessageTracker</a></li>
</ul>
</li>
<li><a class="reference internal" href="#extensions">Extensions</a></li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="unicode.html"
title="previous chapter">PyZMQ and Unicode</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="serialization.html"
title="next chapter">Serializing messages with PyZMQ</a></p>
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="_sources/morethanbindings.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="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body">
<div class="section" id="more-than-just-bindings">
<span id="bindings"></span><h1>More Than Just Bindings<a class="headerlink" href="#more-than-just-bindings" title="Permalink to this headline">¶</a></h1>
<p>PyZMQ is ostensibly the Python bindings for <a class="reference external" href="http://www.zeromq.org">ØMQ</a>, but the project, following
Python’s ‘batteries included’ philosophy, provides more than just Python methods and
objects for calling into the ØMQ C++ library.</p>
<div class="section" id="the-core-as-bindings">
<h2>The Core as Bindings<a class="headerlink" href="#the-core-as-bindings" title="Permalink to this headline">¶</a></h2>
<p>PyZMQ is currently broken up into four subpackages. First, is the Core. <tt class="xref py py-mod docutils literal"><span class="pre">zmq.core</span></tt>
contains the actual bindings for ZeroMQ, and no extended functionality beyond the very
basic. The core modules are split, such that each basic ZeroMQ object (or function, if no
object is associated) is a separate module, e.g. <tt class="xref py py-mod docutils literal"><span class="pre">zmq.core.context</span></tt> contains the
<tt class="xref py py-class docutils literal"><span class="pre">Context</span></tt> object, <a class="reference internal" href="api/generated/zmq.core.poll.html#module-zmq.core.poll" title="zmq.core.poll"><tt class="xref py py-mod docutils literal"><span class="pre">zmq.core.poll</span></tt></a> contains a <a class="reference internal" href="api/generated/zmq.core.poll.html#zmq.core.poll.Poller" title="zmq.core.poll.Poller"><tt class="xref py py-class docutils literal"><span class="pre">Poller</span></tt></a> object, as well
as the <a class="reference internal" href="api/generated/zmq.core.poll.html#zmq.core.poll.select" title="zmq.core.poll.select"><tt class="xref py py-func docutils literal"><span class="pre">select()</span></tt></a> function, etc. ZMQ constants are, for convenience, all kept
together in <tt class="xref py py-mod docutils literal"><span class="pre">zmq.core.constants</span></tt>.</p>
<p>There are two reasons for breaking the core into submodules: <em>recompilation</em> and
<em>derivative projects</em>. The monolithic PyZMQ became quite tedious to have to recompile
everything for a small change to a single object. With separate files, that’s no longer
necessary. The second reason has to do with Cython. PyZMQ is written in Cython, a tool for
efficiently writing C-extensions for Python. By separating out our objects into individual
<cite>pyx</cite> files, each with their declarations in a <cite>pxd</cite> header, other projects can write
extensions in Cython and call directly to ZeroMQ at the C-level without the penalty of
going through our Python objects.</p>
</div>
<div class="section" id="thread-safety">
<h2>Thread Safety<a class="headerlink" href="#thread-safety" title="Permalink to this headline">¶</a></h2>
<p>In ØMQ, Contexts are threadsafe objects, but Sockets are <strong>not</strong>. It is safe to use a
single Context (e.g. via <tt class="xref py py-meth docutils literal"><span class="pre">zmq.Context.instance()</span></tt>) in your entire multithreaded
application, but you should create sockets on a per-thread basis. If you share sockets
across threads, you are likely to encounter uncatchable c-level crashes of your
application unless you use judicious application of <tt class="xref py py-class docutils literal"><span class="pre">threading.Lock</span></tt>, but this
approach is not recommended.</p>
<div class="admonition-see-also admonition seealso">
<p class="first admonition-title">See also</p>
<p class="last">ZeroMQ API <a class="reference external" href="http://api.zeromq.org/2-1:zmq">note on threadsafety</a></p>
</div>
</div>
<div class="section" id="socket-options-as-attributes">
<h2>Socket Options as Attributes<a class="headerlink" href="#socket-options-as-attributes" title="Permalink to this headline">¶</a></h2>
<p class="versionadded">
<span class="versionmodified">New in version 2.1.9.</span></p>
<p>In 0MQ, socket options are set/retrieved with the <tt class="xref py py-meth docutils literal"><span class="pre">set/getsockopt()</span></tt> methods. With the
class-based approach in pyzmq, it would be logical to perform these operations with
simple attribute access, and this has been added in pyzmq 2.1.9. Simply assign to or
request a Socket attribute with the (case-insensitive) name of a sockopt, and it should
behave just as you would expect:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">s</span> <span class="o">=</span> <span class="n">ctx</span><span class="o">.</span><span class="n">socket</span><span class="p">(</span><span class="n">zmq</span><span class="o">.</span><span class="n">DEALER</span><span class="p">)</span>
<span class="n">s</span><span class="o">.</span><span class="n">identity</span> <span class="o">=</span> <span class="n">b</span><span class="s">'dealer'</span>
<span class="n">s</span><span class="o">.</span><span class="n">hwm</span> <span class="o">=</span> <span class="mi">10</span>
<span class="n">s</span><span class="o">.</span><span class="n">events</span>
<span class="c"># 0</span>
<span class="n">s</span><span class="o">.</span><span class="n">fd</span>
<span class="c"># 16</span>
</pre></div>
</div>
<div class="section" id="default-options-on-the-context">
<h3>Default Options on the Context<a class="headerlink" href="#default-options-on-the-context" title="Permalink to this headline">¶</a></h3>
<p class="versionadded">
<span class="versionmodified">New in version 2.1.12.</span></p>
<p>Just like setting socket options as attributes on Sockets, you can do the same on Contexts.
This affects the default options of any <em>new</em> sockets created after the assignment.</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">ctx</span> <span class="o">=</span> <span class="n">zmq</span><span class="o">.</span><span class="n">Context</span><span class="p">()</span>
<span class="n">ctx</span><span class="o">.</span><span class="n">linger</span> <span class="o">=</span> <span class="mi">0</span>
<span class="n">rep</span> <span class="o">=</span> <span class="n">ctx</span><span class="o">.</span><span class="n">socket</span><span class="p">(</span><span class="n">zmq</span><span class="o">.</span><span class="n">REP</span><span class="p">)</span>
<span class="n">req</span> <span class="o">=</span> <span class="n">ctx</span><span class="o">.</span><span class="n">socket</span><span class="p">(</span><span class="n">zmq</span><span class="o">.</span><span class="n">REQ</span><span class="p">)</span>
</pre></div>
</div>
<p>Socket options that do not apply to a socket (e.g. SUBSCRIBE on non-SUB sockets) will
simply be ignored.</p>
</div>
</div>
<div class="section" id="core-extensions">
<h2>Core Extensions<a class="headerlink" href="#core-extensions" title="Permalink to this headline">¶</a></h2>
<p>We have extended the core functionality in two ways that appear inside the <tt class="xref py py-mod docutils literal"><span class="pre">core</span></tt>
bindings, and are not general ØMQ features.</p>
<div class="section" id="builtin-serialization">
<h3>Builtin Serialization<a class="headerlink" href="#builtin-serialization" title="Permalink to this headline">¶</a></h3>
<p>First, we added common serialization with the builtin <tt class="xref py py-mod docutils literal"><span class="pre">json</span></tt> and <tt class="xref py py-mod docutils literal"><span class="pre">pickle</span></tt>
as first-class methods to the <tt class="xref py py-class docutils literal"><span class="pre">Socket</span></tt> class. A socket has the methods
<tt class="xref py py-meth docutils literal"><span class="pre">send_json()</span></tt> and <tt class="xref py py-meth docutils literal"><span class="pre">send_pyobj()</span></tt>, which correspond to sending an
object over the wire after serializing with <tt class="xref py py-mod docutils literal"><span class="pre">json</span></tt> and <tt class="xref py py-mod docutils literal"><span class="pre">pickle</span></tt> respectively,
and any object sent via those methods can be reconstructed with the
<tt class="xref py py-meth docutils literal"><span class="pre">recv_json()</span></tt> and <tt class="xref py py-meth docutils literal"><span class="pre">recv_pyobj()</span></tt> methods. Unicode strings are
other objects that are not unambiguously sendable over the wire, so we include
<tt class="xref py py-meth docutils literal"><span class="pre">send_string()</span></tt> and <tt class="xref py py-meth docutils literal"><span class="pre">recv_string()</span></tt> that simply send bytes
after encoding the message (‘utf-8’ is the default).</p>
<div class="admonition-see-also admonition seealso">
<p class="first admonition-title">See also</p>
<ul class="last simple">
<li><a class="reference internal" href="serialization.html#serialization"><em>Further information</em></a> on serialization in pyzmq.</li>
<li><a class="reference internal" href="unicode.html#unicode"><em>Our Unicode discussion</em></a> for more information on the trials and
tribulations of working with Unicode in a C extension while supporting Python 2 and 3.</li>
</ul>
</div>
</div>
<div class="section" id="messagetracker">
<h3>MessageTracker<a class="headerlink" href="#messagetracker" title="Permalink to this headline">¶</a></h3>
<p>The second extension of basic ØMQ functionality is the <tt class="xref py py-class docutils literal"><span class="pre">MessageTracker</span></tt>. The
MessageTracker is an object used to track when the underlying ZeroMQ is done with a
message buffer. One of the main use cases for ØMQ in Python is the ability to perform
non-copying sends. Thanks to Python’s buffer interface, many objects (including NumPy
arrays) provide the buffer interface, and are thus directly sendable. However, as with any
asynchronous non-copying messaging system like ØMQ or MPI, it can be important to know
when the message has actually been sent, so it is safe again to edit the buffer without
worry of corrupting the message. This is what the MessageTracker is for.</p>
<p>The MessageTracker is a simple object, but there is a penalty to its use. Since by its
very nature, the MessageTracker must involve threadsafe communication (specifically a
builtin <tt class="xref py py-class docutils literal"><span class="pre">Queue</span></tt> object), instantiating a MessageTracker takes a modest
amount of time (10s of µs), so in situations instantiating many small messages, this can
actually dominate performance. As a result, tracking is optional, via the <tt class="docutils literal"><span class="pre">track</span></tt> flag,
which is optionally passed, always defaulting to <tt class="xref docutils literal"><span class="pre">False</span></tt>, in each of the three places
where a Frame object (the pyzmq object for wrapping a segment of a message) is
instantiated: The <tt class="xref py py-class docutils literal"><span class="pre">Frame</span></tt> constructor, and non-copying sends and receives.</p>
<p>A MessageTracker is very simple, and has just one method and one attribute. The property
<tt class="xref py py-attr docutils literal"><span class="pre">MessageTracker.done</span></tt> will be <tt class="xref docutils literal"><span class="pre">True</span></tt> when the Frame(s) being tracked are no
longer in use by ØMQ, and <tt class="xref py py-meth docutils literal"><span class="pre">MessageTracker.wait()</span></tt> will block, waiting for the
Frame(s) to be released.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">A Frame cannot be tracked after it has been instantiated without tracking. If a
Frame is to even have the <em>option</em> of tracking, it must be constructed with
<tt class="docutils literal"><span class="pre">track=True</span></tt>.</p>
</div>
</div>
</div>
<div class="section" id="extensions">
<h2>Extensions<a class="headerlink" href="#extensions" title="Permalink to this headline">¶</a></h2>
<p>So far, PyZMQ includes four extensions to core ØMQ that we found basic enough to be
included in PyZMQ itself:</p>
<ul class="simple">
<li><a class="reference internal" href="logging.html#logging"><em>zmq.log</em></a> : Logging handlers for hooking Python logging up to the
network</li>
<li><a class="reference internal" href="devices.html#devices"><em>zmq.devices</em></a> : Custom devices and objects for running devices in the
background</li>
<li><a class="reference internal" href="eventloop.html#eventloop"><em>zmq.eventloop</em></a> : The <a class="reference external" href="https://github.com/facebook/tornado">Tornado</a> event loop, adapted for use
with ØMQ sockets.</li>
<li><a class="reference internal" href="ssh.html#ssh"><em>zmq.ssh</em></a> : Simple tools for tunneling zeromq connections via ssh.</li>
</ul>
</div>
</div>
</div>
</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"
>index</a></li>
<li class="right" >
<a href="py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="serialization.html" title="Serializing messages with PyZMQ"
>next</a> |</li>
<li class="right" >
<a href="unicode.html" title="PyZMQ and Unicode"
>previous</a> |</li>
<li><a href="index.html">home</a>| </li>
<li><a href="search.html">search</a>| </li>
<li><a href="api/index.html">API</a> »</li>
</ul>
</div>
<div class="footer">
© Copyright 2010-2011, Brian E. Granger & Min Ragan-Kelley.
ØMQ logo © iMatix Corportation, used under the Creative Commons Attribution-Share Alike 3.0 License.
Python logo ™ of the Python Software Foundation, used by Min RK with permission from the Foundation.
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.0.7.
</div>
</body>
</html>
