| 123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112 |
- .. include:: header.txt
- ====================
- Connection objects
- ====================
- Connection objects allow the sending and receiving of picklable
- objects or strings. They can be thought of as message oriented
- connected sockets.
- Connection objects usually created using `processing.Pipe()` -- see
- also `Listener and Clients <connection-ref.html>`_.
- Connection objects have the following methods:
- `send(obj)`
- Send an object to the other end of the connection which should
- be read using `recv()`.
- The object must be picklable.
- `recv()`
- Return an object sent from the other end of the connection
- using `send()`. Raises `EOFError` if there is nothing left to
- receive and the other end was closed.
- `fileno()`
- Returns the file descriptor or handle used by the connection.
- `close()`
- Close the connection.
- This is called automatically when the connection is garbage
- collected.
- `poll(timeout=0.0)`
- Return whether there is any data available to be read within
- `timeout` seconds.
- If `timeout` is `None` then an infinite timeout is used.
-
- Unlike the other blocking methods on Windows this method can
- be interrupted by Ctrl-C.
- `sendBytes(buffer)`
- Send byte data from an object supporting the buffer interface
- as a complete message.
- Can be used to send strings or a view returned by `buffer()`.
- `recvBytes()`
- Return a complete message of byte data sent from the other end
- of the connection as a string. Raises `EOFError` if there is
- nothing left to receive and the other end was closed.
- `recvBytesInto(buffer, offset=0)`
- Read into `buffer` at position `offset` a complete message of
- byte data sent from the other end of the connection and return
- the number of bytes in the message. Raises `EOFError` if
- there is nothing left to receive and the other end was closed.
- `buffer` must be an object satisfying the writable buffer
- interface and `offset` must be non-negative and less than
- the length of `buffer` (in bytes).
-
- If the buffer is too short then a `BufferTooShort` exception
- is raised and the complete message is available as `e.args[0]`
- where `e` is the exception instance.
- For example:
- >>> from processing import Pipe
- >>> a, b = Pipe()
- >>> a.send([1, 'hello', None])
- >>> b.recv()
- [1, 'hello', None]
- >>> b.sendBytes('thank you')
- >>> a.recvBytes()
- 'thank you'
- >>> import array
- >>> arr1 = array.array('i', range(5))
- >>> arr2 = array.array('i', [0] * 10)
- >>> a.sendBytes(arr1)
- >>> count = b.recvBytesInto(arr2)
- >>> assert count == len(arr1) * arr1.itemsize
- >>> arr2
- array('i', [0, 1, 2, 3, 4, 0, 0, 0, 0, 0])
- .. warning::
-
- The `recv()` method automatically unpickles the data it receives
- which can be a security risk unless you can trust the process
- which sent the message.
-
- Therefore, unless the connection object was produced using
- `Pipe()` you should only use the `recv()` and `send()` methods
- after performing some sort of authentication. See `Authentication
- keys <connection-ref.html#authentication-keys>`_.
-
-
- .. warning::
-
- If a process is killed while it is trying to read or write to a
- pipe then the data in the pipe is likely to become corrupted
- because it may become impossible to be sure where the message
- boundaries lie.
- .. _Prev: queue-objects.html
- .. _Up: processing-ref.html
- .. _Next: manager-objects.html
|