.. include:: header.txt

====================
 Connection objects
====================

Connection objects allow the sending and receiving of picklable
objects or strings.  They can be thought of a 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()`.

    `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)`
        Return whether there is any data available to be read within
        `timeout` seconds.

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

    `recvbytes_into(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.  

        `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 of bytes data 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)
    >>> b.recvbytes_into(arr2)
    20
    >>> 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
