<!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>Messaging for Parallel Computing — IPython 2.3.0 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.3.0',
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="IPython 2.3.0 documentation" href="../index.html" />
<link rel="up" title="IPython developer’s guide" href="index.html" />
<link rel="next" title="Connection Diagrams of The IPython ZMQ Cluster" href="parallel_connections.html" />
<link rel="prev" title="Messaging in IPython" href="messaging.html" />
</head>
<body>
<div style="background-color: white; text-align: left; padding: 10px 10px 15px 15px">
<a href="http://ipython.org/"><img src="../_static/logo.png" border="0" alt="IPython 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="parallel_connections.html" title="Connection Diagrams of The IPython ZMQ Cluster"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="messaging.html" title="Messaging in IPython"
accesskey="P">previous</a> |</li>
<li><a href="http://ipython.org">home</a>| </li>
<li><a href="../search.html">search</a>| </li>
<li><a href="../index.html">documentation </a> »</li>
<li><a href="index.html" accesskey="U">IPython developer’s guide</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="#">Messaging for Parallel Computing</a><ul>
<li><a class="reference internal" href="#the-controller">The Controller</a></li>
<li><a class="reference internal" href="#the-hub">The Hub</a><ul>
<li><a class="reference internal" href="#registration-router">Registration (<tt class="docutils literal"><span class="pre">ROUTER</span></tt>)</a></li>
<li><a class="reference internal" href="#heartbeat">Heartbeat</a></li>
<li><a class="reference internal" href="#notification-pub">Notification (<tt class="docutils literal"><span class="pre">PUB</span></tt>)</a></li>
<li><a class="reference internal" href="#client-queries-router">Client Queries (<tt class="docutils literal"><span class="pre">ROUTER</span></tt>)</a></li>
</ul>
</li>
<li><a class="reference internal" href="#schedulers">Schedulers</a><ul>
<li><a class="reference internal" href="#apply"><tt class="docutils literal"><span class="pre">apply()</span></tt></a></li>
</ul>
</li>
<li><a class="reference internal" href="#control-messages">Control Messages</a></li>
<li><a class="reference internal" href="#implementation">Implementation</a><ul>
<li><a class="reference internal" href="#split-sends">Split Sends</a></li>
</ul>
</li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="messaging.html"
title="previous chapter">Messaging in IPython</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="parallel_connections.html"
title="next chapter">Connection Diagrams of The IPython ZMQ Cluster</a></p>
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="../_sources/development/parallel_messages.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" />
<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="messaging-for-parallel-computing">
<span id="parallel-messages"></span><h1>Messaging for Parallel Computing<a class="headerlink" href="#messaging-for-parallel-computing" title="Permalink to this headline">¶</a></h1>
<p>This is an extension of the <a class="reference internal" href="messaging.html#messaging"><em>messaging</em></a> doc. Diagrams of the connections
can be found in the <a class="reference internal" href="parallel_connections.html#parallel-connections"><em>parallel connections</em></a> doc.</p>
<p>ZMQ messaging is also used in the parallel computing IPython system. All messages to/from
kernels remain the same as the single kernel model, and are forwarded through a ZMQ Queue
device. The controller receives all messages and replies in these channels, and saves
results for future use.</p>
<div class="section" id="the-controller">
<h2>The Controller<a class="headerlink" href="#the-controller" title="Permalink to this headline">¶</a></h2>
<p>The controller is the central collection of processes in the IPython parallel computing
model. It has two major components:</p>
<blockquote>
<div><ul class="simple">
<li>The Hub</li>
<li>A collection of Schedulers</li>
</ul>
</div></blockquote>
</div>
<div class="section" id="the-hub">
<h2>The Hub<a class="headerlink" href="#the-hub" title="Permalink to this headline">¶</a></h2>
<p>The Hub is the central process for monitoring the state of the engines, and all task
requests and results. It has no role in execution and does no relay of messages, so
large blocking requests or database actions in the Hub do not have the ability to impede
job submission and results.</p>
<div class="section" id="registration-router">
<h3>Registration (<tt class="docutils literal"><span class="pre">ROUTER</span></tt>)<a class="headerlink" href="#registration-router" title="Permalink to this headline">¶</a></h3>
<p>The first function of the Hub is to facilitate and monitor connections of clients
and engines. Both client and engine registration are handled by the same socket, so only
one ip/port pair is needed to connect any number of connections and clients.</p>
<p>Engines register with the <tt class="docutils literal"><span class="pre">zmq.IDENTITY</span></tt> of their two <tt class="docutils literal"><span class="pre">DEALER</span></tt> sockets, one for the
queue, which receives execute requests, and one for the heartbeat, which is used to
monitor the survival of the Engine process.</p>
<p>Message type: <tt class="docutils literal"><span class="pre">registration_request</span></tt>:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">content</span> <span class="o">=</span> <span class="p">{</span>
<span class="s">'uuid'</span> <span class="p">:</span> <span class="s">'abcd-1234-...'</span><span class="p">,</span> <span class="c"># the zmq.IDENTITY of the engine's sockets</span>
<span class="p">}</span>
</pre></div>
</div>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">these are always the same, at least for now.</p>
</div>
<p>The Controller replies to an Engine’s registration request with the engine’s integer ID,
and all the remaining connection information for connecting the heartbeat process, and
kernel queue socket(s). The message status will be an error if the Engine requests IDs that
already in use.</p>
<p>Message type: <tt class="docutils literal"><span class="pre">registration_reply</span></tt>:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">content</span> <span class="o">=</span> <span class="p">{</span>
<span class="s">'status'</span> <span class="p">:</span> <span class="s">'ok'</span><span class="p">,</span> <span class="c"># or 'error'</span>
<span class="c"># if ok:</span>
<span class="s">'id'</span> <span class="p">:</span> <span class="mi">0</span><span class="p">,</span> <span class="c"># int, the engine id</span>
<span class="p">}</span>
</pre></div>
</div>
<p>Clients use the same socket as engines to start their connections. Connection requests
from clients need no information:</p>
<p>Message type: <tt class="docutils literal"><span class="pre">connection_request</span></tt>:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">content</span> <span class="o">=</span> <span class="p">{}</span>
</pre></div>
</div>
<p>The reply to a Client registration request contains the connection information for the
multiplexer and load balanced queues, as well as the address for direct hub
queries. If any of these addresses is <cite>None</cite>, that functionality is not available.</p>
<p>Message type: <tt class="docutils literal"><span class="pre">connection_reply</span></tt>:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">content</span> <span class="o">=</span> <span class="p">{</span>
<span class="s">'status'</span> <span class="p">:</span> <span class="s">'ok'</span><span class="p">,</span> <span class="c"># or 'error'</span>
<span class="p">}</span>
</pre></div>
</div>
</div>
<div class="section" id="heartbeat">
<h3>Heartbeat<a class="headerlink" href="#heartbeat" title="Permalink to this headline">¶</a></h3>
<p>The hub uses a heartbeat system to monitor engines, and track when they become
unresponsive. As described in <a class="reference internal" href="messaging.html#messaging"><em>messaging</em></a>, and shown in <a class="reference internal" href="parallel_connections.html#parallel-connections"><em>connections</em></a>.</p>
</div>
<div class="section" id="notification-pub">
<h3>Notification (<tt class="docutils literal"><span class="pre">PUB</span></tt>)<a class="headerlink" href="#notification-pub" title="Permalink to this headline">¶</a></h3>
<p>The hub publishes all engine registration/unregistration events on a <tt class="docutils literal"><span class="pre">PUB</span></tt> socket.
This allows clients to have up-to-date engine ID sets without polling. Registration
notifications contain both the integer engine ID and the queue ID, which is necessary for
sending messages via the Multiplexer Queue and Control Queues.</p>
<p>Message type: <tt class="docutils literal"><span class="pre">registration_notification</span></tt>:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">content</span> <span class="o">=</span> <span class="p">{</span>
<span class="s">'id'</span> <span class="p">:</span> <span class="mi">0</span><span class="p">,</span> <span class="c"># engine ID that has been registered</span>
<span class="s">'uuid'</span> <span class="p">:</span> <span class="s">'engine_id'</span> <span class="c"># the IDENT for the engine's sockets</span>
<span class="p">}</span>
</pre></div>
</div>
<p>Message type : <tt class="docutils literal"><span class="pre">unregistration_notification</span></tt>:</p>
<div class="highlight-python"><div class="highlight"><pre>content = {
'id' : 0 # engine ID that has been unregistered
'uuid' : 'engine_id' # the IDENT for the engine's sockets
}
</pre></div>
</div>
</div>
<div class="section" id="client-queries-router">
<h3>Client Queries (<tt class="docutils literal"><span class="pre">ROUTER</span></tt>)<a class="headerlink" href="#client-queries-router" title="Permalink to this headline">¶</a></h3>
<p>The hub monitors and logs all queue traffic, so that clients can retrieve past
results or monitor pending tasks. This information may reside in-memory on the Hub, or
on disk in a database (SQLite and MongoDB are currently supported). These requests are
handled by the same socket as registration.</p>
<p><tt class="xref py py-func docutils literal"><span class="pre">queue_request()</span></tt> requests can specify multiple engines to query via the <cite>targets</cite>
element. A verbose flag can be passed, to determine whether the result should be the list
of <cite>msg_ids</cite> in the queue or simply the length of each list.</p>
<p>Message type: <tt class="docutils literal"><span class="pre">queue_request</span></tt>:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">content</span> <span class="o">=</span> <span class="p">{</span>
<span class="s">'verbose'</span> <span class="p">:</span> <span class="bp">True</span><span class="p">,</span> <span class="c"># whether return should be lists themselves or just lens</span>
<span class="s">'targets'</span> <span class="p">:</span> <span class="p">[</span><span class="mi">0</span><span class="p">,</span><span class="mi">3</span><span class="p">,</span><span class="mi">1</span><span class="p">]</span> <span class="c"># list of ints</span>
<span class="p">}</span>
</pre></div>
</div>
<p>The content of a reply to a <tt class="xref py py-func docutils literal"><span class="pre">queue_request()</span></tt> request is a dict, keyed by the engine
IDs. Note that they will be the string representation of the integer keys, since JSON
cannot handle number keys. The three keys of each dict are:</p>
<div class="highlight-python"><div class="highlight"><pre>'completed' : messages submitted via any queue that ran on the engine
'queue' : jobs submitted via MUX queue, whose results have not been received
'tasks' : tasks that are known to have been submitted to the engine, but
have not completed. Note that with the pure zmq scheduler, this will
always be 0/[].
</pre></div>
</div>
<p>Message type: <tt class="docutils literal"><span class="pre">queue_reply</span></tt>:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">content</span> <span class="o">=</span> <span class="p">{</span>
<span class="s">'status'</span> <span class="p">:</span> <span class="s">'ok'</span><span class="p">,</span> <span class="c"># or 'error'</span>
<span class="c"># if verbose=False:</span>
<span class="s">'0'</span> <span class="p">:</span> <span class="p">{</span><span class="s">'completed'</span> <span class="p">:</span> <span class="mi">1</span><span class="p">,</span> <span class="s">'queue'</span> <span class="p">:</span> <span class="mi">7</span><span class="p">,</span> <span class="s">'tasks'</span> <span class="p">:</span> <span class="mi">0</span><span class="p">},</span>
<span class="c"># if verbose=True:</span>
<span class="s">'1'</span> <span class="p">:</span> <span class="p">{</span><span class="s">'completed'</span> <span class="p">:</span> <span class="p">[</span><span class="s">'abcd-...'</span><span class="p">,</span><span class="s">'1234-...'</span><span class="p">],</span> <span class="s">'queue'</span> <span class="p">:</span> <span class="p">[</span><span class="s">'58008-'</span><span class="p">],</span> <span class="s">'tasks'</span> <span class="p">:</span> <span class="p">[]},</span>
<span class="p">}</span>
</pre></div>
</div>
<p>Clients can request individual results directly from the hub. This is primarily for
gathering results of executions not submitted by the requesting client, as the client
will have all its own results already. Requests are made by msg_id, and can contain one or
more msg_id. An additional boolean key ‘statusonly’ can be used to not request the
results, but simply poll the status of the jobs.</p>
<p>Message type: <tt class="docutils literal"><span class="pre">result_request</span></tt>:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">content</span> <span class="o">=</span> <span class="p">{</span>
<span class="s">'msg_ids'</span> <span class="p">:</span> <span class="p">[</span><span class="s">'uuid'</span><span class="p">,</span><span class="s">'...'</span><span class="p">],</span> <span class="c"># list of strs</span>
<span class="s">'targets'</span> <span class="p">:</span> <span class="p">[</span><span class="mi">1</span><span class="p">,</span><span class="mi">2</span><span class="p">,</span><span class="mi">3</span><span class="p">],</span> <span class="c"># list of int ids or uuids</span>
<span class="s">'statusonly'</span> <span class="p">:</span> <span class="bp">False</span><span class="p">,</span> <span class="c"># bool</span>
<span class="p">}</span>
</pre></div>
</div>
<p>The <tt class="xref py py-func docutils literal"><span class="pre">result_request()</span></tt> reply contains the content objects of the actual execution
reply messages. If <cite>statusonly=True</cite>, then there will be only the ‘pending’ and
‘completed’ lists.</p>
<p>Message type: <tt class="docutils literal"><span class="pre">result_reply</span></tt>:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">content</span> <span class="o">=</span> <span class="p">{</span>
<span class="s">'status'</span> <span class="p">:</span> <span class="s">'ok'</span><span class="p">,</span> <span class="c"># else error</span>
<span class="c"># if ok:</span>
<span class="s">'acbd-...'</span> <span class="p">:</span> <span class="n">msg</span><span class="p">,</span> <span class="c"># the content dict is keyed by msg_ids,</span>
<span class="c"># values are the result messages</span>
<span class="c"># there will be none of these if `statusonly=True`</span>
<span class="s">'pending'</span> <span class="p">:</span> <span class="p">[</span><span class="s">'msg_id'</span><span class="p">,</span><span class="s">'...'</span><span class="p">],</span> <span class="c"># msg_ids still pending</span>
<span class="s">'completed'</span> <span class="p">:</span> <span class="p">[</span><span class="s">'msg_id'</span><span class="p">,</span><span class="s">'...'</span><span class="p">],</span> <span class="c"># list of completed msg_ids</span>
<span class="p">}</span>
<span class="n">buffers</span> <span class="o">=</span> <span class="p">[</span><span class="s">'bufs'</span><span class="p">,</span><span class="s">'...'</span><span class="p">]</span> <span class="c"># the buffers that contained the results of the objects.</span>
<span class="c"># this will be empty if no messages are complete, or if</span>
<span class="c"># statusonly is True.</span>
</pre></div>
</div>
<p>For memory management purposes, Clients can also instruct the hub to forget the
results of messages. This can be done by message ID or engine ID. Individual messages are
dropped by msg_id, and all messages completed on an engine are dropped by engine ID. This
may no longer be necessary with the mongodb-based message logging backend.</p>
<p>If the msg_ids element is the string <tt class="docutils literal"><span class="pre">'all'</span></tt> instead of a list, then all completed
results are forgotten.</p>
<p>Message type: <tt class="docutils literal"><span class="pre">purge_request</span></tt>:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">content</span> <span class="o">=</span> <span class="p">{</span>
<span class="s">'msg_ids'</span> <span class="p">:</span> <span class="p">[</span><span class="s">'id1'</span><span class="p">,</span> <span class="s">'id2'</span><span class="p">,</span><span class="o">...</span><span class="p">],</span> <span class="c"># list of msg_ids or 'all'</span>
<span class="s">'engine_ids'</span> <span class="p">:</span> <span class="p">[</span><span class="mi">0</span><span class="p">,</span><span class="mi">2</span><span class="p">,</span><span class="mi">4</span><span class="p">]</span> <span class="c"># list of engine IDs</span>
<span class="p">}</span>
</pre></div>
</div>
<p>The reply to a purge request is simply the status ‘ok’ if the request succeeded, or an
explanation of why it failed, such as requesting the purge of a nonexistent or pending
message.</p>
<p>Message type: <tt class="docutils literal"><span class="pre">purge_reply</span></tt>:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">content</span> <span class="o">=</span> <span class="p">{</span>
<span class="s">'status'</span> <span class="p">:</span> <span class="s">'ok'</span><span class="p">,</span> <span class="c"># or 'error'</span>
<span class="p">}</span>
</pre></div>
</div>
</div>
</div>
<div class="section" id="schedulers">
<h2>Schedulers<a class="headerlink" href="#schedulers" title="Permalink to this headline">¶</a></h2>
<p>There are three basic schedulers:</p>
<blockquote>
<div><ul class="simple">
<li>Task Scheduler</li>
<li>MUX Scheduler</li>
<li>Control Scheduler</li>
</ul>
</div></blockquote>
<p>The MUX and Control schedulers are simple MonitoredQueue ØMQ devices, with <tt class="docutils literal"><span class="pre">ROUTER</span></tt>
sockets on either side. This allows the queue to relay individual messages to particular
targets via <tt class="docutils literal"><span class="pre">zmq.IDENTITY</span></tt> routing. The Task scheduler may be a MonitoredQueue ØMQ
device, in which case the client-facing socket is <tt class="docutils literal"><span class="pre">ROUTER</span></tt>, and the engine-facing socket
is <tt class="docutils literal"><span class="pre">DEALER</span></tt>. The result of this is that client-submitted messages are load-balanced via
the <tt class="docutils literal"><span class="pre">DEALER</span></tt> socket, but the engine’s replies to each message go to the requesting client.</p>
<p>Raw <tt class="docutils literal"><span class="pre">DEALER</span></tt> scheduling is quite primitive, and doesn’t allow message introspection, so
there are also Python Schedulers that can be used. These Schedulers behave in much the
same way as a MonitoredQueue does from the outside, but have rich internal logic to
determine destinations, as well as handle dependency graphs Their sockets are always
<tt class="docutils literal"><span class="pre">ROUTER</span></tt> on both sides.</p>
<p>The Python task schedulers have an additional message type, which informs the Hub of
the destination of a task as soon as that destination is known.</p>
<p>Message type: <tt class="docutils literal"><span class="pre">task_destination</span></tt>:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">content</span> <span class="o">=</span> <span class="p">{</span>
<span class="s">'msg_id'</span> <span class="p">:</span> <span class="s">'abcd-1234-...'</span><span class="p">,</span> <span class="c"># the msg's uuid</span>
<span class="s">'engine_id'</span> <span class="p">:</span> <span class="s">'1234-abcd-...'</span><span class="p">,</span> <span class="c"># the destination engine's zmq.IDENTITY</span>
<span class="p">}</span>
</pre></div>
</div>
<div class="section" id="apply">
<h3><a class="reference external" href="http://docs.python.org/2/library/functions.html#apply" title="(in Python v2.7)"><tt class="xref py py-func docutils literal"><span class="pre">apply()</span></tt></a><a class="headerlink" href="#apply" title="Permalink to this headline">¶</a></h3>
<p>In terms of message classes, the MUX scheduler and Task scheduler relay the exact same
message types. Their only difference lies in how the destination is selected.</p>
<p>The <a class="reference external" href="http://gist.github.com/483294">Namespace</a> model suggests that execution be able to
use the model:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">ns</span><span class="o">.</span><span class="n">apply</span><span class="p">(</span><span class="n">f</span><span class="p">,</span> <span class="o">*</span><span class="n">args</span><span class="p">,</span> <span class="o">**</span><span class="n">kwargs</span><span class="p">)</span>
</pre></div>
</div>
<p>which takes <cite>f</cite>, a function in the user’s namespace, and executes <tt class="docutils literal"><span class="pre">f(*args,</span> <span class="pre">**kwargs)</span></tt>
on a remote engine, returning the result (or, for non-blocking, information facilitating
later retrieval of the result). This model, unlike the execute message which just uses a
code string, must be able to send arbitrary (pickleable) Python objects. And ideally, copy
as little data as we can. The <cite>buffers</cite> property of a Message was introduced for this
purpose.</p>
<p>Utility method <tt class="xref py py-func docutils literal"><span class="pre">build_apply_message()</span></tt> in <a class="reference internal" href="../api/generated/IPython.kernel.zmq.serialize.html#module-IPython.kernel.zmq.serialize" title="IPython.kernel.zmq.serialize"><tt class="xref py py-mod docutils literal"><span class="pre">IPython.kernel.zmq.serialize</span></tt></a> wraps a
function signature and builds a sendable buffer format for minimal data copying (exactly
zero copies of numpy array data or buffers or large strings).</p>
<p>Message type: <tt class="docutils literal"><span class="pre">apply_request</span></tt>:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">metadata</span> <span class="o">=</span> <span class="p">{</span>
<span class="s">'after'</span> <span class="p">:</span> <span class="p">[</span><span class="s">'msg_id'</span><span class="p">,</span><span class="o">...</span><span class="p">],</span> <span class="c"># list of msg_ids or output of Dependency.as_dict()</span>
<span class="s">'follow'</span> <span class="p">:</span> <span class="p">[</span><span class="s">'msg_id'</span><span class="p">,</span><span class="o">...</span><span class="p">],</span> <span class="c"># list of msg_ids or output of Dependency.as_dict()</span>
<span class="p">}</span>
<span class="n">content</span> <span class="o">=</span> <span class="p">{}</span>
<span class="n">buffers</span> <span class="o">=</span> <span class="p">[</span><span class="s">'...'</span><span class="p">]</span> <span class="c"># at least 3 in length</span>
<span class="c"># as built by build_apply_message(f,args,kwargs)</span>
</pre></div>
</div>
<p>after/follow represent task dependencies. ‘after’ corresponds to a time dependency. The
request will not arrive at an engine until the ‘after’ dependency tasks have completed.
‘follow’ corresponds to a location dependency. The task will be submitted to the same
engine as these msg_ids (see <tt class="xref py py-class docutils literal"><span class="pre">Dependency</span></tt> docs for details).</p>
<p>Message type: <tt class="docutils literal"><span class="pre">apply_reply</span></tt>:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">content</span> <span class="o">=</span> <span class="p">{</span>
<span class="s">'status'</span> <span class="p">:</span> <span class="s">'ok'</span> <span class="c"># 'ok' or 'error'</span>
<span class="c"># other error info here, as in other messages</span>
<span class="p">}</span>
<span class="n">buffers</span> <span class="o">=</span> <span class="p">[</span><span class="s">'...'</span><span class="p">]</span> <span class="c"># either 1 or 2 in length</span>
<span class="c"># a serialization of the return value of f(*args,**kwargs)</span>
<span class="c"># only populated if status is 'ok'</span>
</pre></div>
</div>
<p>All engine execution and data movement is performed via apply messages.</p>
</div>
</div>
<div class="section" id="control-messages">
<h2>Control Messages<a class="headerlink" href="#control-messages" title="Permalink to this headline">¶</a></h2>
<p>Messages that interact with the engines, but are not meant to execute code, are submitted
via the Control queue. These messages have high priority, and are thus received and
handled before any execution requests.</p>
<p>Clients may want to clear the namespace on the engine. There are no arguments nor
information involved in this request, so the content is empty.</p>
<p>Message type: <tt class="docutils literal"><span class="pre">clear_request</span></tt>:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">content</span> <span class="o">=</span> <span class="p">{}</span>
</pre></div>
</div>
<p>Message type: <tt class="docutils literal"><span class="pre">clear_reply</span></tt>:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">content</span> <span class="o">=</span> <span class="p">{</span>
<span class="s">'status'</span> <span class="p">:</span> <span class="s">'ok'</span> <span class="c"># 'ok' or 'error'</span>
<span class="c"># other error info here, as in other messages</span>
<span class="p">}</span>
</pre></div>
</div>
<p>Clients may want to abort tasks that have not yet run. This can by done by message id, or
all enqueued messages can be aborted if None is specified.</p>
<p>Message type: <tt class="docutils literal"><span class="pre">abort_request</span></tt>:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">content</span> <span class="o">=</span> <span class="p">{</span>
<span class="s">'msg_ids'</span> <span class="p">:</span> <span class="p">[</span><span class="s">'1234-...'</span><span class="p">,</span> <span class="s">'...'</span><span class="p">]</span> <span class="c"># list of msg_ids or None</span>
<span class="p">}</span>
</pre></div>
</div>
<p>Message type: <tt class="docutils literal"><span class="pre">abort_reply</span></tt>:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">content</span> <span class="o">=</span> <span class="p">{</span>
<span class="s">'status'</span> <span class="p">:</span> <span class="s">'ok'</span> <span class="c"># 'ok' or 'error'</span>
<span class="c"># other error info here, as in other messages</span>
<span class="p">}</span>
</pre></div>
</div>
<p>The last action a client may want to do is shutdown the kernel. If a kernel receives a
shutdown request, then it aborts all queued messages, replies to the request, and exits.</p>
<p>Message type: <tt class="docutils literal"><span class="pre">shutdown_request</span></tt>:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">content</span> <span class="o">=</span> <span class="p">{}</span>
</pre></div>
</div>
<p>Message type: <tt class="docutils literal"><span class="pre">shutdown_reply</span></tt>:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">content</span> <span class="o">=</span> <span class="p">{</span>
<span class="s">'status'</span> <span class="p">:</span> <span class="s">'ok'</span> <span class="c"># 'ok' or 'error'</span>
<span class="c"># other error info here, as in other messages</span>
<span class="p">}</span>
</pre></div>
</div>
</div>
<div class="section" id="implementation">
<h2>Implementation<a class="headerlink" href="#implementation" title="Permalink to this headline">¶</a></h2>
<p>There are a few differences in implementation between the <cite>StreamSession</cite> object used in
the newparallel branch and the <cite>Session</cite> object, the main one being that messages are
sent in parts, rather than as a single serialized object. <cite>StreamSession</cite> objects also
take pack/unpack functions, which are to be used when serializing/deserializing objects.
These can be any functions that translate to/from formats that ZMQ sockets can send
(buffers,bytes, etc.).</p>
<div class="section" id="split-sends">
<h3>Split Sends<a class="headerlink" href="#split-sends" title="Permalink to this headline">¶</a></h3>
<p>Previously, messages were bundled as a single json object and one call to
<tt class="xref py py-func docutils literal"><span class="pre">socket.send_json()</span></tt>. Since the hub inspects all messages, and doesn’t need to
see the content of the messages, which can be large, messages are now serialized and sent in
pieces. All messages are sent in at least 4 parts: the header, the parent header, the metadata and the content.
This allows the controller to unpack and inspect the (always small) header,
without spending time unpacking the content unless the message is bound for the
controller. Buffers are added on to the end of the message, and can be any objects that
present the buffer interface.</p>
</div>
</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="parallel_connections.html" title="Connection Diagrams of The IPython ZMQ Cluster"
>next</a> |</li>
<li class="right" >
<a href="messaging.html" title="Messaging in IPython"
>previous</a> |</li>
<li><a href="http://ipython.org">home</a>| </li>
<li><a href="../search.html">search</a>| </li>
<li><a href="../index.html">documentation </a> »</li>
<li><a href="index.html" >IPython developer’s guide</a> »</li>
</ul>
</div>
<div class="footer">
© Copyright The IPython Development Team.
Last updated on Sep 02, 2015.
Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.2.3.
</div>
</body>
</html>
distrib
>
Mageia
>
5
>
x86_64
>
media
>
core-updates
>
by-pkgid
>
c044f82ec6193fba7e13c97913613b07
>
files
>
950
