connection-objects.txt 3.7 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112
  1. .. include:: header.txt
  2. ====================
  3. Connection objects
  4. ====================
  5. Connection objects allow the sending and receiving of picklable
  6. objects or strings. They can be thought of as message oriented
  7. connected sockets.
  8. Connection objects usually created using `processing.Pipe()` -- see
  9. also `Listener and Clients <connection-ref.html>`_.
  10. Connection objects have the following methods:
  11. `send(obj)`
  12. Send an object to the other end of the connection which should
  13. be read using `recv()`.
  14. The object must be picklable.
  15. `recv()`
  16. Return an object sent from the other end of the connection
  17. using `send()`. Raises `EOFError` if there is nothing left to
  18. receive and the other end was closed.
  19. `fileno()`
  20. Returns the file descriptor or handle used by the connection.
  21. `close()`
  22. Close the connection.
  23. This is called automatically when the connection is garbage
  24. collected.
  25. `poll(timeout=0.0)`
  26. Return whether there is any data available to be read within
  27. `timeout` seconds.
  28. If `timeout` is `None` then an infinite timeout is used.
  29. Unlike the other blocking methods on Windows this method can
  30. be interrupted by Ctrl-C.
  31. `sendBytes(buffer)`
  32. Send byte data from an object supporting the buffer interface
  33. as a complete message.
  34. Can be used to send strings or a view returned by `buffer()`.
  35. `recvBytes()`
  36. Return a complete message of byte data sent from the other end
  37. of the connection as a string. Raises `EOFError` if there is
  38. nothing left to receive and the other end was closed.
  39. `recvBytesInto(buffer, offset=0)`
  40. Read into `buffer` at position `offset` a complete message of
  41. byte data sent from the other end of the connection and return
  42. the number of bytes in the message. Raises `EOFError` if
  43. there is nothing left to receive and the other end was closed.
  44. `buffer` must be an object satisfying the writable buffer
  45. interface and `offset` must be non-negative and less than
  46. the length of `buffer` (in bytes).
  47. If the buffer is too short then a `BufferTooShort` exception
  48. is raised and the complete message is available as `e.args[0]`
  49. where `e` is the exception instance.
  50. For example:
  51. >>> from processing import Pipe
  52. >>> a, b = Pipe()
  53. >>> a.send([1, 'hello', None])
  54. >>> b.recv()
  55. [1, 'hello', None]
  56. >>> b.sendBytes('thank you')
  57. >>> a.recvBytes()
  58. 'thank you'
  59. >>> import array
  60. >>> arr1 = array.array('i', range(5))
  61. >>> arr2 = array.array('i', [0] * 10)
  62. >>> a.sendBytes(arr1)
  63. >>> count = b.recvBytesInto(arr2)
  64. >>> assert count == len(arr1) * arr1.itemsize
  65. >>> arr2
  66. array('i', [0, 1, 2, 3, 4, 0, 0, 0, 0, 0])
  67. .. warning::
  68. The `recv()` method automatically unpickles the data it receives
  69. which can be a security risk unless you can trust the process
  70. which sent the message.
  71. Therefore, unless the connection object was produced using
  72. `Pipe()` you should only use the `recv()` and `send()` methods
  73. after performing some sort of authentication. See `Authentication
  74. keys <connection-ref.html#authentication-keys>`_.
  75. .. warning::
  76. If a process is killed while it is trying to read or write to a
  77. pipe then the data in the pipe is likely to become corrupted
  78. because it may become impossible to be sure where the message
  79. boundaries lie.
  80. .. _Prev: queue-objects.html
  81. .. _Up: processing-ref.html
  82. .. _Next: manager-objects.html