560 lines
42 KiB
HTML
560 lines
42 KiB
HTML
|
||
<!DOCTYPE html>
|
||
|
||
<html xmlns="http://www.w3.org/1999/xhtml">
|
||
<head>
|
||
<meta charset="utf-8" />
|
||
<title>asyncore — Asynchronous socket handler — Python 3.7.4 documentation</title>
|
||
<link rel="stylesheet" href="../_static/pydoctheme.css" type="text/css" />
|
||
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
|
||
|
||
<script type="text/javascript" id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></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>
|
||
<script type="text/javascript" src="../_static/language_data.js"></script>
|
||
|
||
<script type="text/javascript" src="../_static/sidebar.js"></script>
|
||
|
||
<link rel="search" type="application/opensearchdescription+xml"
|
||
title="Search within Python 3.7.4 documentation"
|
||
href="../_static/opensearch.xml"/>
|
||
<link rel="author" title="About these documents" href="../about.html" />
|
||
<link rel="index" title="Index" href="../genindex.html" />
|
||
<link rel="search" title="Search" href="../search.html" />
|
||
<link rel="copyright" title="Copyright" href="../copyright.html" />
|
||
<link rel="next" title="asynchat — Asynchronous socket command/response handler" href="asynchat.html" />
|
||
<link rel="prev" title="selectors — High-level I/O multiplexing" href="selectors.html" />
|
||
<link rel="shortcut icon" type="image/png" href="../_static/py.png" />
|
||
<link rel="canonical" href="https://docs.python.org/3/library/asyncore.html" />
|
||
|
||
<script type="text/javascript" src="../_static/copybutton.js"></script>
|
||
<script type="text/javascript" src="../_static/switchers.js"></script>
|
||
|
||
|
||
|
||
<style>
|
||
@media only screen {
|
||
table.full-width-table {
|
||
width: 100%;
|
||
}
|
||
}
|
||
</style>
|
||
|
||
|
||
</head><body>
|
||
|
||
<div class="related" role="navigation" aria-label="related navigation">
|
||
<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="asynchat.html" title="asynchat — Asynchronous socket command/response handler"
|
||
accesskey="N">next</a> |</li>
|
||
<li class="right" >
|
||
<a href="selectors.html" title="selectors — High-level I/O multiplexing"
|
||
accesskey="P">previous</a> |</li>
|
||
<li><img src="../_static/py.png" alt=""
|
||
style="vertical-align: middle; margin-top: -1px"/></li>
|
||
<li><a href="https://www.python.org/">Python</a> »</li>
|
||
<li>
|
||
<span class="language_switcher_placeholder">en</span>
|
||
<span class="version_switcher_placeholder">3.7.4</span>
|
||
<a href="../index.html">Documentation </a> »
|
||
</li>
|
||
|
||
<li class="nav-item nav-item-1"><a href="index.html" >The Python Standard Library</a> »</li>
|
||
<li class="nav-item nav-item-2"><a href="ipc.html" accesskey="U">Networking and Interprocess Communication</a> »</li>
|
||
<li class="right">
|
||
|
||
|
||
<div class="inline-search" style="display: none" role="search">
|
||
<form class="inline-search" action="../search.html" method="get">
|
||
<input placeholder="Quick search" 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>
|
||
</div>
|
||
<script type="text/javascript">$('.inline-search').show(0);</script>
|
||
|
|
||
</li>
|
||
|
||
</ul>
|
||
</div>
|
||
|
||
<div class="document">
|
||
<div class="documentwrapper">
|
||
<div class="bodywrapper">
|
||
<div class="body" role="main">
|
||
|
||
<div class="section" id="module-asyncore">
|
||
<span id="asyncore-asynchronous-socket-handler"></span><h1><a class="reference internal" href="#module-asyncore" title="asyncore: A base class for developing asynchronous socket handling services."><code class="xref py py-mod docutils literal notranslate"><span class="pre">asyncore</span></code></a> — Asynchronous socket handler<a class="headerlink" href="#module-asyncore" title="Permalink to this headline">¶</a></h1>
|
||
<p><strong>Source code:</strong> <a class="reference external" href="https://github.com/python/cpython/tree/3.7/Lib/asyncore.py">Lib/asyncore.py</a></p>
|
||
<div class="deprecated">
|
||
<p><span class="versionmodified deprecated">Deprecated since version 3.6: </span>Please use <a class="reference internal" href="asyncio.html#module-asyncio" title="asyncio: Asynchronous I/O."><code class="xref py py-mod docutils literal notranslate"><span class="pre">asyncio</span></code></a> instead.</p>
|
||
</div>
|
||
<hr class="docutils" />
|
||
<div class="admonition note">
|
||
<p class="admonition-title">Note</p>
|
||
<p>This module exists for backwards compatibility only. For new code we
|
||
recommend using <a class="reference internal" href="asyncio.html#module-asyncio" title="asyncio: Asynchronous I/O."><code class="xref py py-mod docutils literal notranslate"><span class="pre">asyncio</span></code></a>.</p>
|
||
</div>
|
||
<p>This module provides the basic infrastructure for writing asynchronous socket
|
||
service clients and servers.</p>
|
||
<p>There are only two ways to have a program on a single processor do “more than
|
||
one thing at a time.” Multi-threaded programming is the simplest and most
|
||
popular way to do it, but there is another very different technique, that lets
|
||
you have nearly all the advantages of multi-threading, without actually using
|
||
multiple threads. It’s really only practical if your program is largely I/O
|
||
bound. If your program is processor bound, then pre-emptive scheduled threads
|
||
are probably what you really need. Network servers are rarely processor
|
||
bound, however.</p>
|
||
<p>If your operating system supports the <code class="xref c c-func docutils literal notranslate"><span class="pre">select()</span></code> system call in its I/O
|
||
library (and nearly all do), then you can use it to juggle multiple
|
||
communication channels at once; doing other work while your I/O is taking
|
||
place in the “background.” Although this strategy can seem strange and
|
||
complex, especially at first, it is in many ways easier to understand and
|
||
control than multi-threaded programming. The <a class="reference internal" href="#module-asyncore" title="asyncore: A base class for developing asynchronous socket handling services."><code class="xref py py-mod docutils literal notranslate"><span class="pre">asyncore</span></code></a> module solves
|
||
many of the difficult problems for you, making the task of building
|
||
sophisticated high-performance network servers and clients a snap. For
|
||
“conversational” applications and protocols the companion <a class="reference internal" href="asynchat.html#module-asynchat" title="asynchat: Support for asynchronous command/response protocols."><code class="xref py py-mod docutils literal notranslate"><span class="pre">asynchat</span></code></a>
|
||
module is invaluable.</p>
|
||
<p>The basic idea behind both modules is to create one or more network
|
||
<em>channels</em>, instances of class <a class="reference internal" href="#asyncore.dispatcher" title="asyncore.dispatcher"><code class="xref py py-class docutils literal notranslate"><span class="pre">asyncore.dispatcher</span></code></a> and
|
||
<a class="reference internal" href="asynchat.html#asynchat.async_chat" title="asynchat.async_chat"><code class="xref py py-class docutils literal notranslate"><span class="pre">asynchat.async_chat</span></code></a>. Creating the channels adds them to a global
|
||
map, used by the <a class="reference internal" href="#asyncore.loop" title="asyncore.loop"><code class="xref py py-func docutils literal notranslate"><span class="pre">loop()</span></code></a> function if you do not provide it with your own
|
||
<em>map</em>.</p>
|
||
<p>Once the initial channel(s) is(are) created, calling the <a class="reference internal" href="#asyncore.loop" title="asyncore.loop"><code class="xref py py-func docutils literal notranslate"><span class="pre">loop()</span></code></a> function
|
||
activates channel service, which continues until the last channel (including
|
||
any that have been added to the map during asynchronous service) is closed.</p>
|
||
<dl class="function">
|
||
<dt id="asyncore.loop">
|
||
<code class="descclassname">asyncore.</code><code class="descname">loop</code><span class="sig-paren">(</span><span class="optional">[</span><em>timeout</em><span class="optional">[</span>, <em>use_poll</em><span class="optional">[</span>, <em>map</em><span class="optional">[</span>, <em>count</em><span class="optional">]</span><span class="optional">]</span><span class="optional">]</span><span class="optional">]</span><span class="sig-paren">)</span><a class="headerlink" href="#asyncore.loop" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Enter a polling loop that terminates after count passes or all open
|
||
channels have been closed. All arguments are optional. The <em>count</em>
|
||
parameter defaults to <code class="docutils literal notranslate"><span class="pre">None</span></code>, resulting in the loop terminating only when all
|
||
channels have been closed. The <em>timeout</em> argument sets the timeout
|
||
parameter for the appropriate <a class="reference internal" href="select.html#select.select" title="select.select"><code class="xref py py-func docutils literal notranslate"><span class="pre">select()</span></code></a> or <a class="reference internal" href="select.html#select.poll" title="select.poll"><code class="xref py py-func docutils literal notranslate"><span class="pre">poll()</span></code></a>
|
||
call, measured in seconds; the default is 30 seconds. The <em>use_poll</em>
|
||
parameter, if true, indicates that <a class="reference internal" href="select.html#select.poll" title="select.poll"><code class="xref py py-func docutils literal notranslate"><span class="pre">poll()</span></code></a> should be used in
|
||
preference to <a class="reference internal" href="select.html#select.select" title="select.select"><code class="xref py py-func docutils literal notranslate"><span class="pre">select()</span></code></a> (the default is <code class="docutils literal notranslate"><span class="pre">False</span></code>).</p>
|
||
<p>The <em>map</em> parameter is a dictionary whose items are the channels to watch.
|
||
As channels are closed they are deleted from their map. If <em>map</em> is
|
||
omitted, a global map is used. Channels (instances of
|
||
<a class="reference internal" href="#asyncore.dispatcher" title="asyncore.dispatcher"><code class="xref py py-class docutils literal notranslate"><span class="pre">asyncore.dispatcher</span></code></a>, <a class="reference internal" href="asynchat.html#asynchat.async_chat" title="asynchat.async_chat"><code class="xref py py-class docutils literal notranslate"><span class="pre">asynchat.async_chat</span></code></a> and subclasses
|
||
thereof) can freely be mixed in the map.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="class">
|
||
<dt id="asyncore.dispatcher">
|
||
<em class="property">class </em><code class="descclassname">asyncore.</code><code class="descname">dispatcher</code><a class="headerlink" href="#asyncore.dispatcher" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>The <a class="reference internal" href="#asyncore.dispatcher" title="asyncore.dispatcher"><code class="xref py py-class docutils literal notranslate"><span class="pre">dispatcher</span></code></a> class is a thin wrapper around a low-level socket
|
||
object. To make it more useful, it has a few methods for event-handling
|
||
which are called from the asynchronous loop. Otherwise, it can be treated
|
||
as a normal non-blocking socket object.</p>
|
||
<p>The firing of low-level events at certain times or in certain connection
|
||
states tells the asynchronous loop that certain higher-level events have
|
||
taken place. For example, if we have asked for a socket to connect to
|
||
another host, we know that the connection has been made when the socket
|
||
becomes writable for the first time (at this point you know that you may
|
||
write to it with the expectation of success). The implied higher-level
|
||
events are:</p>
|
||
<table class="docutils align-center">
|
||
<colgroup>
|
||
<col style="width: 35%" />
|
||
<col style="width: 65%" />
|
||
</colgroup>
|
||
<thead>
|
||
<tr class="row-odd"><th class="head"><p>Event</p></th>
|
||
<th class="head"><p>Description</p></th>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">handle_connect()</span></code></p></td>
|
||
<td><p>Implied by the first read or write
|
||
event</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">handle_close()</span></code></p></td>
|
||
<td><p>Implied by a read event with no data
|
||
available</p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">handle_accepted()</span></code></p></td>
|
||
<td><p>Implied by a read event on a listening
|
||
socket</p></td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
<p>During asynchronous processing, each mapped channel’s <a class="reference internal" href="#asyncore.dispatcher.readable" title="asyncore.dispatcher.readable"><code class="xref py py-meth docutils literal notranslate"><span class="pre">readable()</span></code></a> and
|
||
<a class="reference internal" href="#asyncore.dispatcher.writable" title="asyncore.dispatcher.writable"><code class="xref py py-meth docutils literal notranslate"><span class="pre">writable()</span></code></a> methods are used to determine whether the channel’s socket
|
||
should be added to the list of channels <code class="xref c c-func docutils literal notranslate"><span class="pre">select()</span></code>ed or
|
||
<code class="xref c c-func docutils literal notranslate"><span class="pre">poll()</span></code>ed for read and write events.</p>
|
||
<p>Thus, the set of channel events is larger than the basic socket events. The
|
||
full set of methods that can be overridden in your subclass follows:</p>
|
||
<dl class="method">
|
||
<dt id="asyncore.dispatcher.handle_read">
|
||
<code class="descname">handle_read</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#asyncore.dispatcher.handle_read" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Called when the asynchronous loop detects that a <code class="xref py py-meth docutils literal notranslate"><span class="pre">read()</span></code> call on the
|
||
channel’s socket will succeed.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="asyncore.dispatcher.handle_write">
|
||
<code class="descname">handle_write</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#asyncore.dispatcher.handle_write" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Called when the asynchronous loop detects that a writable socket can be
|
||
written. Often this method will implement the necessary buffering for
|
||
performance. For example:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="k">def</span> <span class="nf">handle_write</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
|
||
<span class="n">sent</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">send</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">buffer</span><span class="p">)</span>
|
||
<span class="bp">self</span><span class="o">.</span><span class="n">buffer</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">buffer</span><span class="p">[</span><span class="n">sent</span><span class="p">:]</span>
|
||
</pre></div>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="asyncore.dispatcher.handle_expt">
|
||
<code class="descname">handle_expt</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#asyncore.dispatcher.handle_expt" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Called when there is out of band (OOB) data for a socket connection. This
|
||
will almost never happen, as OOB is tenuously supported and rarely used.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="asyncore.dispatcher.handle_connect">
|
||
<code class="descname">handle_connect</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#asyncore.dispatcher.handle_connect" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Called when the active opener’s socket actually makes a connection. Might
|
||
send a “welcome” banner, or initiate a protocol negotiation with the
|
||
remote endpoint, for example.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="asyncore.dispatcher.handle_close">
|
||
<code class="descname">handle_close</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#asyncore.dispatcher.handle_close" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Called when the socket is closed.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="asyncore.dispatcher.handle_error">
|
||
<code class="descname">handle_error</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#asyncore.dispatcher.handle_error" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Called when an exception is raised and not otherwise handled. The default
|
||
version prints a condensed traceback.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="asyncore.dispatcher.handle_accept">
|
||
<code class="descname">handle_accept</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#asyncore.dispatcher.handle_accept" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Called on listening channels (passive openers) when a connection can be
|
||
established with a new remote endpoint that has issued a <a class="reference internal" href="#asyncore.dispatcher.connect" title="asyncore.dispatcher.connect"><code class="xref py py-meth docutils literal notranslate"><span class="pre">connect()</span></code></a>
|
||
call for the local endpoint. Deprecated in version 3.2; use
|
||
<a class="reference internal" href="#asyncore.dispatcher.handle_accepted" title="asyncore.dispatcher.handle_accepted"><code class="xref py py-meth docutils literal notranslate"><span class="pre">handle_accepted()</span></code></a> instead.</p>
|
||
<div class="deprecated">
|
||
<p><span class="versionmodified deprecated">Deprecated since version 3.2.</span></p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="asyncore.dispatcher.handle_accepted">
|
||
<code class="descname">handle_accepted</code><span class="sig-paren">(</span><em>sock</em>, <em>addr</em><span class="sig-paren">)</span><a class="headerlink" href="#asyncore.dispatcher.handle_accepted" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Called on listening channels (passive openers) when a connection has been
|
||
established with a new remote endpoint that has issued a <a class="reference internal" href="#asyncore.dispatcher.connect" title="asyncore.dispatcher.connect"><code class="xref py py-meth docutils literal notranslate"><span class="pre">connect()</span></code></a>
|
||
call for the local endpoint. <em>sock</em> is a <em>new</em> socket object usable to
|
||
send and receive data on the connection, and <em>addr</em> is the address
|
||
bound to the socket on the other end of the connection.</p>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">New in version 3.2.</span></p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="asyncore.dispatcher.readable">
|
||
<code class="descname">readable</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#asyncore.dispatcher.readable" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Called each time around the asynchronous loop to determine whether a
|
||
channel’s socket should be added to the list on which read events can
|
||
occur. The default method simply returns <code class="docutils literal notranslate"><span class="pre">True</span></code>, indicating that by
|
||
default, all channels will be interested in read events.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="asyncore.dispatcher.writable">
|
||
<code class="descname">writable</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#asyncore.dispatcher.writable" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Called each time around the asynchronous loop to determine whether a
|
||
channel’s socket should be added to the list on which write events can
|
||
occur. The default method simply returns <code class="docutils literal notranslate"><span class="pre">True</span></code>, indicating that by
|
||
default, all channels will be interested in write events.</p>
|
||
</dd></dl>
|
||
|
||
<p>In addition, each channel delegates or extends many of the socket methods.
|
||
Most of these are nearly identical to their socket partners.</p>
|
||
<dl class="method">
|
||
<dt id="asyncore.dispatcher.create_socket">
|
||
<code class="descname">create_socket</code><span class="sig-paren">(</span><em>family=socket.AF_INET</em>, <em>type=socket.SOCK_STREAM</em><span class="sig-paren">)</span><a class="headerlink" href="#asyncore.dispatcher.create_socket" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>This is identical to the creation of a normal socket, and will use the
|
||
same options for creation. Refer to the <a class="reference internal" href="socket.html#module-socket" title="socket: Low-level networking interface."><code class="xref py py-mod docutils literal notranslate"><span class="pre">socket</span></code></a> documentation for
|
||
information on creating sockets.</p>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.3: </span><em>family</em> and <em>type</em> arguments can be omitted.</p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="asyncore.dispatcher.connect">
|
||
<code class="descname">connect</code><span class="sig-paren">(</span><em>address</em><span class="sig-paren">)</span><a class="headerlink" href="#asyncore.dispatcher.connect" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>As with the normal socket object, <em>address</em> is a tuple with the first
|
||
element the host to connect to, and the second the port number.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="asyncore.dispatcher.send">
|
||
<code class="descname">send</code><span class="sig-paren">(</span><em>data</em><span class="sig-paren">)</span><a class="headerlink" href="#asyncore.dispatcher.send" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Send <em>data</em> to the remote end-point of the socket.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="asyncore.dispatcher.recv">
|
||
<code class="descname">recv</code><span class="sig-paren">(</span><em>buffer_size</em><span class="sig-paren">)</span><a class="headerlink" href="#asyncore.dispatcher.recv" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Read at most <em>buffer_size</em> bytes from the socket’s remote end-point. An
|
||
empty bytes object implies that the channel has been closed from the
|
||
other end.</p>
|
||
<p>Note that <a class="reference internal" href="#asyncore.dispatcher.recv" title="asyncore.dispatcher.recv"><code class="xref py py-meth docutils literal notranslate"><span class="pre">recv()</span></code></a> may raise <a class="reference internal" href="exceptions.html#BlockingIOError" title="BlockingIOError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">BlockingIOError</span></code></a> , even though
|
||
<a class="reference internal" href="select.html#select.select" title="select.select"><code class="xref py py-func docutils literal notranslate"><span class="pre">select.select()</span></code></a> or <a class="reference internal" href="select.html#select.poll" title="select.poll"><code class="xref py py-func docutils literal notranslate"><span class="pre">select.poll()</span></code></a> has reported the socket
|
||
ready for reading.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="asyncore.dispatcher.listen">
|
||
<code class="descname">listen</code><span class="sig-paren">(</span><em>backlog</em><span class="sig-paren">)</span><a class="headerlink" href="#asyncore.dispatcher.listen" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Listen for connections made to the socket. The <em>backlog</em> argument
|
||
specifies the maximum number of queued connections and should be at least
|
||
1; the maximum value is system-dependent (usually 5).</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="asyncore.dispatcher.bind">
|
||
<code class="descname">bind</code><span class="sig-paren">(</span><em>address</em><span class="sig-paren">)</span><a class="headerlink" href="#asyncore.dispatcher.bind" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Bind the socket to <em>address</em>. The socket must not already be bound. (The
|
||
format of <em>address</em> depends on the address family — refer to the
|
||
<a class="reference internal" href="socket.html#module-socket" title="socket: Low-level networking interface."><code class="xref py py-mod docutils literal notranslate"><span class="pre">socket</span></code></a> documentation for more information.) To mark
|
||
the socket as re-usable (setting the <code class="xref py py-const docutils literal notranslate"><span class="pre">SO_REUSEADDR</span></code> option), call
|
||
the <a class="reference internal" href="#asyncore.dispatcher" title="asyncore.dispatcher"><code class="xref py py-class docutils literal notranslate"><span class="pre">dispatcher</span></code></a> object’s <code class="xref py py-meth docutils literal notranslate"><span class="pre">set_reuse_addr()</span></code> method.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="asyncore.dispatcher.accept">
|
||
<code class="descname">accept</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#asyncore.dispatcher.accept" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Accept a connection. The socket must be bound to an address and listening
|
||
for connections. The return value can be either <code class="docutils literal notranslate"><span class="pre">None</span></code> or a pair
|
||
<code class="docutils literal notranslate"><span class="pre">(conn,</span> <span class="pre">address)</span></code> where <em>conn</em> is a <em>new</em> socket object usable to send
|
||
and receive data on the connection, and <em>address</em> is the address bound to
|
||
the socket on the other end of the connection.
|
||
When <code class="docutils literal notranslate"><span class="pre">None</span></code> is returned it means the connection didn’t take place, in
|
||
which case the server should just ignore this event and keep listening
|
||
for further incoming connections.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="asyncore.dispatcher.close">
|
||
<code class="descname">close</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#asyncore.dispatcher.close" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Close the socket. All future operations on the socket object will fail.
|
||
The remote end-point will receive no more data (after queued data is
|
||
flushed). Sockets are automatically closed when they are
|
||
garbage-collected.</p>
|
||
</dd></dl>
|
||
|
||
</dd></dl>
|
||
|
||
<dl class="class">
|
||
<dt id="asyncore.dispatcher_with_send">
|
||
<em class="property">class </em><code class="descclassname">asyncore.</code><code class="descname">dispatcher_with_send</code><a class="headerlink" href="#asyncore.dispatcher_with_send" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>A <a class="reference internal" href="#asyncore.dispatcher" title="asyncore.dispatcher"><code class="xref py py-class docutils literal notranslate"><span class="pre">dispatcher</span></code></a> subclass which adds simple buffered output capability,
|
||
useful for simple clients. For more sophisticated usage use
|
||
<a class="reference internal" href="asynchat.html#asynchat.async_chat" title="asynchat.async_chat"><code class="xref py py-class docutils literal notranslate"><span class="pre">asynchat.async_chat</span></code></a>.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="class">
|
||
<dt id="asyncore.file_dispatcher">
|
||
<em class="property">class </em><code class="descclassname">asyncore.</code><code class="descname">file_dispatcher</code><a class="headerlink" href="#asyncore.file_dispatcher" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>A file_dispatcher takes a file descriptor or <a class="reference internal" href="../glossary.html#term-file-object"><span class="xref std std-term">file object</span></a> along
|
||
with an optional map argument and wraps it for use with the <code class="xref c c-func docutils literal notranslate"><span class="pre">poll()</span></code>
|
||
or <code class="xref c c-func docutils literal notranslate"><span class="pre">loop()</span></code> functions. If provided a file object or anything with a
|
||
<code class="xref c c-func docutils literal notranslate"><span class="pre">fileno()</span></code> method, that method will be called and passed to the
|
||
<a class="reference internal" href="#asyncore.file_wrapper" title="asyncore.file_wrapper"><code class="xref py py-class docutils literal notranslate"><span class="pre">file_wrapper</span></code></a> constructor.</p>
|
||
<p class="availability"><a class="reference internal" href="intro.html#availability"><span class="std std-ref">Availability</span></a>: Unix.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="class">
|
||
<dt id="asyncore.file_wrapper">
|
||
<em class="property">class </em><code class="descclassname">asyncore.</code><code class="descname">file_wrapper</code><a class="headerlink" href="#asyncore.file_wrapper" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>A file_wrapper takes an integer file descriptor and calls <a class="reference internal" href="os.html#os.dup" title="os.dup"><code class="xref py py-func docutils literal notranslate"><span class="pre">os.dup()</span></code></a> to
|
||
duplicate the handle so that the original handle may be closed independently
|
||
of the file_wrapper. This class implements sufficient methods to emulate a
|
||
socket for use by the <a class="reference internal" href="#asyncore.file_dispatcher" title="asyncore.file_dispatcher"><code class="xref py py-class docutils literal notranslate"><span class="pre">file_dispatcher</span></code></a> class.</p>
|
||
<p class="availability"><a class="reference internal" href="intro.html#availability"><span class="std std-ref">Availability</span></a>: Unix.</p>
|
||
</dd></dl>
|
||
|
||
<div class="section" id="asyncore-example-basic-http-client">
|
||
<span id="asyncore-example-1"></span><h2>asyncore Example basic HTTP client<a class="headerlink" href="#asyncore-example-basic-http-client" title="Permalink to this headline">¶</a></h2>
|
||
<p>Here is a very basic HTTP client that uses the <a class="reference internal" href="#asyncore.dispatcher" title="asyncore.dispatcher"><code class="xref py py-class docutils literal notranslate"><span class="pre">dispatcher</span></code></a> class to
|
||
implement its socket handling:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">asyncore</span>
|
||
|
||
<span class="k">class</span> <span class="nc">HTTPClient</span><span class="p">(</span><span class="n">asyncore</span><span class="o">.</span><span class="n">dispatcher</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">host</span><span class="p">,</span> <span class="n">path</span><span class="p">):</span>
|
||
<span class="n">asyncore</span><span class="o">.</span><span class="n">dispatcher</span><span class="o">.</span><span class="fm">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">)</span>
|
||
<span class="bp">self</span><span class="o">.</span><span class="n">create_socket</span><span class="p">()</span>
|
||
<span class="bp">self</span><span class="o">.</span><span class="n">connect</span><span class="p">(</span> <span class="p">(</span><span class="n">host</span><span class="p">,</span> <span class="mi">80</span><span class="p">)</span> <span class="p">)</span>
|
||
<span class="bp">self</span><span class="o">.</span><span class="n">buffer</span> <span class="o">=</span> <span class="nb">bytes</span><span class="p">(</span><span class="s1">'GET </span><span class="si">%s</span><span class="s1"> HTTP/1.0</span><span class="se">\r\n</span><span class="s1">Host: </span><span class="si">%s</span><span class="se">\r\n\r\n</span><span class="s1">'</span> <span class="o">%</span>
|
||
<span class="p">(</span><span class="n">path</span><span class="p">,</span> <span class="n">host</span><span class="p">),</span> <span class="s1">'ascii'</span><span class="p">)</span>
|
||
|
||
<span class="k">def</span> <span class="nf">handle_connect</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
|
||
<span class="k">pass</span>
|
||
|
||
<span class="k">def</span> <span class="nf">handle_close</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
|
||
<span class="bp">self</span><span class="o">.</span><span class="n">close</span><span class="p">()</span>
|
||
|
||
<span class="k">def</span> <span class="nf">handle_read</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
|
||
<span class="nb">print</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">recv</span><span class="p">(</span><span class="mi">8192</span><span class="p">))</span>
|
||
|
||
<span class="k">def</span> <span class="nf">writable</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
|
||
<span class="k">return</span> <span class="p">(</span><span class="nb">len</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">buffer</span><span class="p">)</span> <span class="o">></span> <span class="mi">0</span><span class="p">)</span>
|
||
|
||
<span class="k">def</span> <span class="nf">handle_write</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
|
||
<span class="n">sent</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">send</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">buffer</span><span class="p">)</span>
|
||
<span class="bp">self</span><span class="o">.</span><span class="n">buffer</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">buffer</span><span class="p">[</span><span class="n">sent</span><span class="p">:]</span>
|
||
|
||
|
||
<span class="n">client</span> <span class="o">=</span> <span class="n">HTTPClient</span><span class="p">(</span><span class="s1">'www.python.org'</span><span class="p">,</span> <span class="s1">'/'</span><span class="p">)</span>
|
||
<span class="n">asyncore</span><span class="o">.</span><span class="n">loop</span><span class="p">()</span>
|
||
</pre></div>
|
||
</div>
|
||
</div>
|
||
<div class="section" id="asyncore-example-basic-echo-server">
|
||
<span id="asyncore-example-2"></span><h2>asyncore Example basic echo server<a class="headerlink" href="#asyncore-example-basic-echo-server" title="Permalink to this headline">¶</a></h2>
|
||
<p>Here is a basic echo server that uses the <a class="reference internal" href="#asyncore.dispatcher" title="asyncore.dispatcher"><code class="xref py py-class docutils literal notranslate"><span class="pre">dispatcher</span></code></a> class to accept
|
||
connections and dispatches the incoming connections to a handler:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">asyncore</span>
|
||
|
||
<span class="k">class</span> <span class="nc">EchoHandler</span><span class="p">(</span><span class="n">asyncore</span><span class="o">.</span><span class="n">dispatcher_with_send</span><span class="p">):</span>
|
||
|
||
<span class="k">def</span> <span class="nf">handle_read</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
|
||
<span class="n">data</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">recv</span><span class="p">(</span><span class="mi">8192</span><span class="p">)</span>
|
||
<span class="k">if</span> <span class="n">data</span><span class="p">:</span>
|
||
<span class="bp">self</span><span class="o">.</span><span class="n">send</span><span class="p">(</span><span class="n">data</span><span class="p">)</span>
|
||
|
||
<span class="k">class</span> <span class="nc">EchoServer</span><span class="p">(</span><span class="n">asyncore</span><span class="o">.</span><span class="n">dispatcher</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">host</span><span class="p">,</span> <span class="n">port</span><span class="p">):</span>
|
||
<span class="n">asyncore</span><span class="o">.</span><span class="n">dispatcher</span><span class="o">.</span><span class="fm">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">)</span>
|
||
<span class="bp">self</span><span class="o">.</span><span class="n">create_socket</span><span class="p">()</span>
|
||
<span class="bp">self</span><span class="o">.</span><span class="n">set_reuse_addr</span><span class="p">()</span>
|
||
<span class="bp">self</span><span class="o">.</span><span class="n">bind</span><span class="p">((</span><span class="n">host</span><span class="p">,</span> <span class="n">port</span><span class="p">))</span>
|
||
<span class="bp">self</span><span class="o">.</span><span class="n">listen</span><span class="p">(</span><span class="mi">5</span><span class="p">)</span>
|
||
|
||
<span class="k">def</span> <span class="nf">handle_accepted</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">sock</span><span class="p">,</span> <span class="n">addr</span><span class="p">):</span>
|
||
<span class="nb">print</span><span class="p">(</span><span class="s1">'Incoming connection from </span><span class="si">%s</span><span class="s1">'</span> <span class="o">%</span> <span class="nb">repr</span><span class="p">(</span><span class="n">addr</span><span class="p">))</span>
|
||
<span class="n">handler</span> <span class="o">=</span> <span class="n">EchoHandler</span><span class="p">(</span><span class="n">sock</span><span class="p">)</span>
|
||
|
||
<span class="n">server</span> <span class="o">=</span> <span class="n">EchoServer</span><span class="p">(</span><span class="s1">'localhost'</span><span class="p">,</span> <span class="mi">8080</span><span class="p">)</span>
|
||
<span class="n">asyncore</span><span class="o">.</span><span class="n">loop</span><span class="p">()</span>
|
||
</pre></div>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
|
||
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
|
||
<div class="sphinxsidebarwrapper">
|
||
<h3><a href="../contents.html">Table of Contents</a></h3>
|
||
<ul>
|
||
<li><a class="reference internal" href="#"><code class="xref py py-mod docutils literal notranslate"><span class="pre">asyncore</span></code> — Asynchronous socket handler</a><ul>
|
||
<li><a class="reference internal" href="#asyncore-example-basic-http-client">asyncore Example basic HTTP client</a></li>
|
||
<li><a class="reference internal" href="#asyncore-example-basic-echo-server">asyncore Example basic echo server</a></li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
|
||
<h4>Previous topic</h4>
|
||
<p class="topless"><a href="selectors.html"
|
||
title="previous chapter"><code class="xref py py-mod docutils literal notranslate"><span class="pre">selectors</span></code> — High-level I/O multiplexing</a></p>
|
||
<h4>Next topic</h4>
|
||
<p class="topless"><a href="asynchat.html"
|
||
title="next chapter"><code class="xref py py-mod docutils literal notranslate"><span class="pre">asynchat</span></code> — Asynchronous socket command/response handler</a></p>
|
||
<div role="note" aria-label="source link">
|
||
<h3>This Page</h3>
|
||
<ul class="this-page-menu">
|
||
<li><a href="../bugs.html">Report a Bug</a></li>
|
||
<li>
|
||
<a href="https://github.com/python/cpython/blob/3.7/Doc/library/asyncore.rst"
|
||
rel="nofollow">Show Source
|
||
</a>
|
||
</li>
|
||
</ul>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<div class="clearer"></div>
|
||
</div>
|
||
<div class="related" role="navigation" aria-label="related navigation">
|
||
<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="asynchat.html" title="asynchat — Asynchronous socket command/response handler"
|
||
>next</a> |</li>
|
||
<li class="right" >
|
||
<a href="selectors.html" title="selectors — High-level I/O multiplexing"
|
||
>previous</a> |</li>
|
||
<li><img src="../_static/py.png" alt=""
|
||
style="vertical-align: middle; margin-top: -1px"/></li>
|
||
<li><a href="https://www.python.org/">Python</a> »</li>
|
||
<li>
|
||
<span class="language_switcher_placeholder">en</span>
|
||
<span class="version_switcher_placeholder">3.7.4</span>
|
||
<a href="../index.html">Documentation </a> »
|
||
</li>
|
||
|
||
<li class="nav-item nav-item-1"><a href="index.html" >The Python Standard Library</a> »</li>
|
||
<li class="nav-item nav-item-2"><a href="ipc.html" >Networking and Interprocess Communication</a> »</li>
|
||
<li class="right">
|
||
|
||
|
||
<div class="inline-search" style="display: none" role="search">
|
||
<form class="inline-search" action="../search.html" method="get">
|
||
<input placeholder="Quick search" 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>
|
||
</div>
|
||
<script type="text/javascript">$('.inline-search').show(0);</script>
|
||
|
|
||
</li>
|
||
|
||
</ul>
|
||
</div>
|
||
<div class="footer">
|
||
© <a href="../copyright.html">Copyright</a> 2001-2019, Python Software Foundation.
|
||
<br />
|
||
The Python Software Foundation is a non-profit corporation.
|
||
<a href="https://www.python.org/psf/donations/">Please donate.</a>
|
||
<br />
|
||
Last updated on Jul 13, 2019.
|
||
<a href="../bugs.html">Found a bug</a>?
|
||
<br />
|
||
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 2.0.1.
|
||
</div>
|
||
|
||
</body>
|
||
</html> |