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
addressread-onlyEither a 2-tuple containing the (host, port) of the remote end of the socket, or a string in the case of a UNIX socket.
aliveread-onlyTrue if the socket is alive, and False otherwise.
buffer_sizeread/writeSize of the send and receive socket buffers (SO_SNDBUF and SO_RCVBUF) in bytes.
connectedread-onlyBoolean representing the connected state of the socket.
connectingread-onlyTrue if the socket is in the process of establishing a connection but is not yet connected.
filenoread-onlyThe file descriptor (integer) for this channel, or None if no channel has been set.
listeningread-onlyTrue if this is a listening socket, and False otherwise.
readableread-onlyTrue if the socket is readable, and False otherwise.
Signals
new-clientEmitted 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.

Previous topic

I/O Channels

Next topic

Sub-Process I/O

This Page

Quick search