.. include:: header.txt

==============================
 Connection package reference
==============================

The `connection` sub-package allows the sending of picklable objects
between processes using sockets or *named pipes*.

The sub-package contains C-extensions `socket_connection` and
`pipe_connection`.  Without these extensions `connection` will
still work, but will be slower and will not support the use of named
pipes on Windows.


Classes and functions
=====================

One class is exported:

   **class** `Listener(address=None, family=None, backlog=1)` 
       A wrapper for a bound socket or Windows named pipe which is
       'listening' connections.

One function is exported:

    `Client(address, family=None)`
        Attempts to set up a connection to the listener which is using
        address `address`.  

        The type of the connection is determined by `family`
        argument, but this can generally be omitted since it can
        usually be inferred from the format of the address.

        A `Connection` object is returned.  (See `Connection
        objects`_.)


Listener Objects
================

Instances of `Listener` have the following methods:

    `__init__(address=None, family=None, backlog=1)`
        `address`
           The address to be used by the bound socket
           or named pipe of the listener object.

        `family`
           The type of the socket (or named pipe) to use.

           This can be one of the strings `'AF_INET'` (for a TCP
           socket), `'AF_UNIX'` (for a Unix domain socket) or
           `'AF_PIPE'` (for a Windows named pipe).  Of these only
           the first is guaranteed to be available.

           If `family` is `None` than the family is inferred from
           the format of `address`.  If `address` is also `None`
           then a default is chosen.  This default is the family which
           is assumed to be the fastest available.
        
        `backlog`
           If the listener object uses a socket then `backlog` is
           passed to the `listen()` method of the socket once it has
           been bound.

    `accept()`
        Accept a connection on the bound socket or named pipe of 
        the listener object.

        Returns a `Connection` object.  (See `Connection objects`_.)

    `close()`
        Close the bound socket or named pipe of the listener object.

        (Note that this is called automatically when the listener is
        garbage collected.)


Listener objects have the following read-only properties:

    `address`
        The address which is being used by the listener object.

    `last_accepted`
        The address from which the last accepted connection came.

        If this is unavailable then `None` is returned.


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

Connections objects have the following methods:

    `recv()`
        Return an object sent from the other end of the connection.

    `send(obj)`
        Send an object to the other end of the connection.

        The object must be picklable.

    `recv_string()`
        Return a string sent from the other end of the connection.

    `send_string(obj)`
        Send a string to the other end of the connection.

    `close()`
        Close the connection.

        This is called automatically when the connection is garbage
        collected.


Address formats
===============

* An `'AF_INET'` address is a tuple of the form `(hostname, port)`
  where `hostname` is a string and `port` is an integer

* An `'AF_UNIX'` address is a string representing a filename on the
  filesystem.

* An `'AF_PIPE'` address is a string of the form
  `r'\\.\pipe\PipeName'`.
  
  To use `Client` to connect to a named pipe on a remote computer
  called `ServerName` one should use an address of the form
  `r'\\ServerName\pipe\PipeName'` instead.


Example
=======

The following server code creates a listener, waits for a connection,
receives an object and then sends it back boxed inside a list::

    from processing.connection import Listener

    address = ('localhost', 6000)     # family is deduced to be 'AF_INET'
    listener = Listener(address)

    conn = listener.accept()
    print 'connection accepted from', listener.last_accepted

    obj = conn.recv()
    boxed_obj = [obj]
    conn.send(boxed_obj)

The following code connects to the server, sends it the number 42, and
then prints the reply from the server::

    from processing.connection import Client

    address = ('localhost', 6000)
    conn = Client(address)

    obj = 42
    print 'sending:', obj
    conn.send(obj)
    print 'recieved:', conn.recv()    # prints '[42]'


.. _Prev: proxy-objects.html
.. _Up: processing-ref.html
.. _Next: programming-guidelines.html

