Prev Up Next

# 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 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.

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.