Socket I/O — kaa.base v0.6.0 documentation

### Navigation

- index
- next |
- previous |
- kaa.base v0.6.0 documentation »
- The Core Framework »

# Socket I/O

class `kaa.` `Socket`(buffer_size=None, chunk_size=1048576)

  Communicate over TCP or Unix sockets, implementing fully asynchronous reads and writes.

  #### Synopsis

  Class Hierarchy

  `kaa.Object`
  └─ `kaa.IOChannel`
  └─ `kaa.Socket`

  Methods

  `close()` | Closes the socket.
  `connect()` | Connects to the host specified in address.
  `listen()` | Sets the socket to listen.
  `wrap()` | Wraps an existing low-level socket object.

  Properties

  `address` | read-only | Either a 2-tuple containing the (host, port) of the remote end of the socket, or a string in the case of a UNIX socket.
  `alive` | read-only | True if the socket is alive, and False otherwise.
  `buffer_size` | read/write | Size of the send and receive socket buffers (SO_SNDBUF and SO_RCVBUF) in bytes.
  `connected` | read-only | Boolean representing the connected state of the socket.
  `connecting` | read-only | True if the socket is in the process of establishing a connection but is not yet connected.
  `fileno` | read-only | The file descriptor (integer) for this channel, or None if no channel has been set.
  `listening` | read-only | True if this is a listening socket, and False otherwise.
  `readable` | read-only | True if the socket is readable, and False otherwise.

  Signals

  `new-client` | Emitted when a new client connects to a listening socket.

  #### Methods

  `close`(immediate=False, expected=True)

    Closes the socket.

    Parameters: | immediate (bool) – if False and there is data in the write buffer, the channel is closed once the write buffer is emptied. Otherwise the channel is closed immediately and the closed signal is emitted.

  `connect`(addr)

    Connects to the host specified in address.

    Parameters: | addr (str or 2-tuple) – if a string in the form host:port, or a tuple the form (host, port), a TCP socket is established. Otherwise a Unix socket is established and addr is treated as a filename. In this case, if addr does not start with a / character, a kaa tempfile is created.
    Returns: | An `InProgress` object.

    This function is executed in a thread to avoid blocking. It therefore returns an InProgress object. If the socket is connected, the InProgress is finished with no arguments. If the connection cannot be established, an exception is thrown to the InProgress.

  `listen`(bind_info, qlen=5)

    Sets the socket to listen.

    Parameters: | bind_info (int or 2-tuple) – Binds the socket using this value. If an int, this specifies a port that is bound on all interfaces; if a 2-tuple, specifies (ip, port) where ip is the single interface on which to bind.

    If the bind fails, an exception is raised.

    Once listening, new connections are automatically accepted, and the ‘new-client’ signal is emitted for each new connection. Callbacks connecting to the signal will receive a new Socket object representing the client connection.

  `wrap`(sock, addr=None)

    Wraps an existing low-level socket object.

    addr specifies the address corresponding to the socket.

  #### Properties

  `address`

    Either a 2-tuple containing the (host, port) of the remote end of the socket, or a string in the case of a UNIX socket.

    host may be an IP address or hostname, but it is always a string.

    If this is a listening socket, it is a 2-tuple of the address the socket was bound to.

  `alive`

    True if the socket is alive, and False otherwise.

    A socket is considered alive when it is connected or in the process of connecting.

  `buffer_size`

    Size of the send and receive socket buffers (SO_SNDBUF and SO_RCVBUF) in bytes.

    Setting this to higher values (say 1M) improves performance when sending large amounts of data across the socket. Note that the upper bound may be restricted by the kernel. (Under Linux, this can be tuned by adjusting /proc/sys/net/core/[rw]mem_max)

  `connected`
    Boolean representing the connected state of the socket.
  `connecting`

    True if the socket is in the process of establishing a connection but is not yet connected.

    Once the socket is connected, the connecting property will be False, but the connected property will be True.

  `fileno`
    The file descriptor (integer) for this channel, or None if no channel has been set.
  `listening`
    True if this is a listening socket, and False otherwise.
  `readable`

    True if the socket is readable, and False otherwise.

    A socket is considered readable when it is listening or alive.

  #### Signals

  `new-client`

    Emitted when a new client connects to a listening socket.

    `def callback(client, ...)`

    Parameters: | client (`Socket` object) – the new client that just connected.

### Navigation

- index
- next |
- previous |
- kaa.base v0.6.0 documentation »
- The Core Framework »