connection-objects.html 6.6 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115
  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>