Debian Codegraph @

pypy3.11/doc/connection-objects.html

raw
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> &nbsp; &nbsp; &nbsp; &nbsp; <a class="reference" href="processing-ref.html">Up</a> &nbsp; &nbsp; &nbsp; &nbsp; <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 &gt;&gt;&gt; from processing import Pipe
75 &gt;&gt;&gt; a, b = Pipe()
76 &gt;&gt;&gt; a.send([1, 'hello', None])
77 &gt;&gt;&gt; b.recv()
78 [1, 'hello', None]
79 &gt;&gt;&gt; b.sendBytes('thank you')
80 &gt;&gt;&gt; a.recvBytes()
81 'thank you'
82 &gt;&gt;&gt; import array
83 &gt;&gt;&gt; arr1 = array.array('i', range(5))
84 &gt;&gt;&gt; arr2 = array.array('i', [0] * 10)
85 &gt;&gt;&gt; a.sendBytes(arr1)
86 &gt;&gt;&gt; count = b.recvBytesInto(arr2)
87 &gt;&gt;&gt; assert count == len(arr1) * arr1.itemsize
88 &gt;&gt;&gt; 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> &nbsp; &nbsp; &nbsp; &nbsp; <a class="reference" href="processing-ref.html">Up</a> &nbsp; &nbsp; &nbsp; &nbsp; <a class="reference" href="manager-objects.html">Next</a>
113 </div>
114 </body>
115 </html>