| 1 |
<?xml version="1.0" encoding="utf-8" ?> |
| 2 |
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> |
| 3 |
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"> |
| 4 |
<head> |
| 5 |
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> |
| 6 |
<meta name="generator" content="Docutils 0.4: http://docutils.sourceforge.net/" /> |
| 7 |
<title>Connection objects</title> |
| 8 |
<link rel="stylesheet" href="html4css1.css" type="text/css" /> |
| 9 |
</head> |
| 10 |
<body> |
| 11 |
<div class="header"> |
| 12 |
<a class="reference" href="queue-objects.html">Prev</a> <a class="reference" href="processing-ref.html">Up</a> <a class="reference" href="manager-objects.html">Next</a> |
| 13 |
<hr class="header"/> |
| 14 |
</div> |
| 15 |
<div class="document" id="connection-objects"> |
| 16 |
<h1 class="title">Connection objects</h1> |
| 17 |
<p>Connection objects allow the sending and receiving of picklable |
| 18 |
objects or strings. They can be thought of as message oriented |
| 19 |
connected sockets.</p> |
| 20 |
<p>Connection objects usually created using <tt class="docutils literal"><span class="pre">processing.Pipe()</span></tt> -- see |
| 21 |
also <a class="reference" href="connection-ref.html">Listener and Clients</a>.</p> |
| 22 |
<p>Connection objects have the following methods:</p> |
| 23 |
<blockquote> |
| 24 |
<dl class="docutils"> |
| 25 |
<dt><tt class="docutils literal"><span class="pre">send(obj)</span></tt></dt> |
| 26 |
<dd><p class="first">Send an object to the other end of the connection which should |
| 27 |
be read using <tt class="docutils literal"><span class="pre">recv()</span></tt>.</p> |
| 28 |
<p class="last">The object must be picklable.</p> |
| 29 |
</dd> |
| 30 |
<dt><tt class="docutils literal"><span class="pre">recv()</span></tt></dt> |
| 31 |
<dd>Return an object sent from the other end of the connection |
| 32 |
using <tt class="docutils literal"><span class="pre">send()</span></tt>. Raises <tt class="docutils literal"><span class="pre">EOFError</span></tt> if there is nothing left to |
| 33 |
receive and the other end was closed.</dd> |
| 34 |
<dt><tt class="docutils literal"><span class="pre">fileno()</span></tt></dt> |
| 35 |
<dd>Returns the file descriptor or handle used by the connection.</dd> |
| 36 |
<dt><tt class="docutils literal"><span class="pre">close()</span></tt></dt> |
| 37 |
<dd><p class="first">Close the connection.</p> |
| 38 |
<p class="last">This is called automatically when the connection is garbage |
| 39 |
collected.</p> |
| 40 |
</dd> |
| 41 |
<dt><tt class="docutils literal"><span class="pre">poll(timeout=0.0)</span></tt></dt> |
| 42 |
<dd><p class="first">Return whether there is any data available to be read within |
| 43 |
<tt class="docutils literal"><span class="pre">timeout</span></tt> seconds.</p> |
| 44 |
<p>If <tt class="docutils literal"><span class="pre">timeout</span></tt> is <tt class="docutils literal"><span class="pre">None</span></tt> then an infinite timeout is used.</p> |
| 45 |
<p class="last">Unlike the other blocking methods on Windows this method can |
| 46 |
be interrupted by Ctrl-C.</p> |
| 47 |
</dd> |
| 48 |
<dt><tt class="docutils literal"><span class="pre">sendBytes(buffer)</span></tt></dt> |
| 49 |
<dd><p class="first">Send byte data from an object supporting the buffer interface |
| 50 |
as a complete message.</p> |
| 51 |
<p class="last">Can be used to send strings or a view returned by <tt class="docutils literal"><span class="pre">buffer()</span></tt>.</p> |
| 52 |
</dd> |
| 53 |
<dt><tt class="docutils literal"><span class="pre">recvBytes()</span></tt></dt> |
| 54 |
<dd>Return a complete message of byte data sent from the other end |
| 55 |
of the connection as a string. Raises <tt class="docutils literal"><span class="pre">EOFError</span></tt> if there is |
| 56 |
nothing left to receive and the other end was closed.</dd> |
| 57 |
<dt><tt class="docutils literal"><span class="pre">recvBytesInto(buffer,</span> <span class="pre">offset=0)</span></tt></dt> |
| 58 |
<dd><p class="first">Read into <tt class="docutils literal"><span class="pre">buffer</span></tt> at position <tt class="docutils literal"><span class="pre">offset</span></tt> a complete message of |
| 59 |
byte data sent from the other end of the connection and return |
| 60 |
the number of bytes in the message. Raises <tt class="docutils literal"><span class="pre">EOFError</span></tt> if |
| 61 |
there is nothing left to receive and the other end was closed.</p> |
| 62 |
<p><tt class="docutils literal"><span class="pre">buffer</span></tt> must be an object satisfying the writable buffer |
| 63 |
interface and <tt class="docutils literal"><span class="pre">offset</span></tt> must be non-negative and less than |
| 64 |
the length of <tt class="docutils literal"><span class="pre">buffer</span></tt> (in bytes).</p> |
| 65 |
<p class="last">If the buffer is too short then a <tt class="docutils literal"><span class="pre">BufferTooShort</span></tt> exception |
| 66 |
is raised and the complete message is available as <tt class="docutils literal"><span class="pre">e.args[0]</span></tt> |
| 67 |
where <tt class="docutils literal"><span class="pre">e</span></tt> is the exception instance.</p> |
| 68 |
</dd> |
| 69 |
</dl> |
| 70 |
</blockquote> |
| 71 |
<p>For example:</p> |
| 72 |
<blockquote> |
| 73 |
<pre class="doctest-block"> |
| 74 |
>>> from processing import Pipe |
| 75 |
>>> a, b = Pipe() |
| 76 |
>>> a.send([1, 'hello', None]) |
| 77 |
>>> b.recv() |
| 78 |
[1, 'hello', None] |
| 79 |
>>> b.sendBytes('thank you') |
| 80 |
>>> a.recvBytes() |
| 81 |
'thank you' |
| 82 |
>>> import array |
| 83 |
>>> arr1 = array.array('i', range(5)) |
| 84 |
>>> arr2 = array.array('i', [0] * 10) |
| 85 |
>>> a.sendBytes(arr1) |
| 86 |
>>> count = b.recvBytesInto(arr2) |
| 87 |
>>> assert count == len(arr1) * arr1.itemsize |
| 88 |
>>> arr2 |
| 89 |
array('i', [0, 1, 2, 3, 4, 0, 0, 0, 0, 0]) |
| 90 |
</pre> |
| 91 |
</blockquote> |
| 92 |
<div class="warning"> |
| 93 |
<p class="first admonition-title">Warning</p> |
| 94 |
<p>The <tt class="docutils literal"><span class="pre">recv()</span></tt> method automatically unpickles the data it receives |
| 95 |
which can be a security risk unless you can trust the process |
| 96 |
which sent the message.</p> |
| 97 |
<p class="last">Therefore, unless the connection object was produced using |
| 98 |
<tt class="docutils literal"><span class="pre">Pipe()</span></tt> you should only use the <tt class="docutils literal"><span class="pre">recv()</span></tt> and <tt class="docutils literal"><span class="pre">send()</span></tt> methods |
| 99 |
after performing some sort of authentication. See <a class="reference" href="connection-ref.html#authentication-keys">Authentication |
| 100 |
keys</a>.</p> |
| 101 |
</div> |
| 102 |
<div class="warning"> |
| 103 |
<p class="first admonition-title">Warning</p> |
| 104 |
<p class="last">If a process is killed while it is trying to read or write to a |
| 105 |
pipe then the data in the pipe is likely to become corrupted |
| 106 |
because it may become impossible to be sure where the message |
| 107 |
boundaries lie.</p> |
| 108 |
</div> |
| 109 |
</div> |
| 110 |
<div class="footer"> |
| 111 |
<hr class="footer" /> |
| 112 |
<a class="reference" href="queue-objects.html">Prev</a> <a class="reference" href="processing-ref.html">Up</a> <a class="reference" href="manager-objects.html">Next</a> |
| 113 |
</div> |
| 114 |
</body> |
| 115 |
</html> |