"""
    Transport-layer functionality.

    This implements the core TCP/UDP/SCTP functionality, plus relevant transport/application layer stuff like TLS, SOCKS, SSH-channels, etc.

    XXX: non-blocking interface?

    Firstly, this defines a set of abstract interfaces that model the actual implementation as built on top of the
    socket packages's network-layer implementation:


    Interfaces:

        Transport           - very abstract interface that embodies the notion of sending something somewhere

            ConnectedTransport      - connection-oriented transport
            
                Stream                  - connection-oriented full-duplex byte stream (reliable, sequenced)
                    
                    BufferedStream          - buffered version of the above
    
                PacketStream            - connection-oriented full-duplex packet-oriented communication
 

            UnconnectedTransport    - non-connection-oriented transport dealing with packets

                Peer                    - connectionless packet-oriented communication


        Endpoint        - some transport-level endpoint (local/remote address/socket)


        Client          - connection-oriented endpoint that can establish a Transport to some remote Service

        Service         - listening endpoint that recieves connections from remote Clients and represents those as Transports


    Next, there are some mid-level helpers, mostly for dealing with 


    Then there is are implementations of these interfaces for specific protocols, layering on top of the socket module,
    or other application-level protocols.

    TCP:
        TCP implementation using a SOCK_STREAM socket.

        Stream          - connected TCP socket with TCP's byte stream semantics

        Service         - TCP socket accept()'ing Streams from remote Clients

        Client          - TCP socket connect()'ing to a remote Service


    UDP:
        UDP implementation using a SOCK_DGRAM socket.

        Peer            - bind()'d UDP socket without any connection

        Client          - connect()'d UDP socket, representing a PacketStream


    UNIX:
        UNIX socket implementation support both SOCK_STREAM and SOCK_DGRAM.

        XXX: verify that this is correct...

        Stream          - connected AF_UNIX SOCK_STREAM

        Service         - accept()'ing AF_UNIX socket of either SOCK_STREAM mode

        Client          - connect()'ing AF_UNIX socket of SOCK_STREAM mode

        Peer            - bind()'d AF_UNIX socket of SOCK_DGRAM mode

    SCTP:
        SCTP implementation offering both SOCK_SEQPACKET and SOCK_STREAM -based socket interfaces.

        Stream          - a PacketStream carried by an Association

        Association     - a Transport that represents a SCTP association between a local and remote Endpoint

        Peer            - one-to-many style interface, with a single Peer holding multiple Associations

        Service         - a one-to-one style listen()'ing interface which accepts Associations from remote Endpoints

        Client          - a one-to-one style connect()'ing interface which establishes Associations with remote Endpoints

    SSL:
        SSL implementation using either OpenSSL or gnutls.

        Stream          - tcp.Stream carrying an encrypted byte stream

        Service         - tcp.Service accepting connections from SSL endpoints

        Client          - tcp.Client connecting to an SSL service

    SOCKS:
        SOCKSv5 client implementing TCP client serviecs.

        Stream          - tcp.Stream carried over a SOCKSv5 connections

        Client          - tcp.Client connecting via a SOCKSv5 server




    TODO:
        * implement the above
"""