2. Sockets

Most Shrapnel programs make heavy use of sockets. The coro package implements its own socket class, which is nearly identical to the socket class in Python. Indeed, if you use coro.install_thread_emulation() then the socket class will be monkey-patched into Python’s socket module.

2.1. Creating Sockets

Though you are free to directly instantiate the coro.sock object, there are a variety of functions to assist in creating socket objects with a little more clarity.

coro.tcp6_sock()

Create a streaming IPv6 socket.

Returns:A socket object. Raises OSError:OS-level error.

coro.tcp_sock()

Create a streaming IPv4 socket.

Returns:A socket object. Raises OSError:OS-level error.

coro.udp6_sock()

Create a datagram IPv6 socket.

Returns:A socket object. Raises OSError:OS-level error.

coro.udp_sock()

Create a datagram IPv4 socket.

Returns:A socket object. Raises OSError:OS-level error.

coro.unix_sock()

Create a streaming unix-domain socket.

Returns:A socket object. Raises OSError:OS-level error.

coro.socketpair(int domain=AF_UNIX, int stype=SOCK_STREAM, int protocol=0)

Create an unnamed pair of connected sockets.

Parameters:

• domain – The socket domain family (defaults to AF_UNIX).
• stype – The socket type (defaults to SOCK_STREAM).
• protocol – The socket protocol (normally not used, defaults to 0).

Returns:

A tuple of 2 connected sockets.

Raises OSError:

OS-level error.

coro.has_ipv6()

Whether or not this system can create an IPv6 socket.

Returns:True if this system can create an IPv6 socket, False otherwise

2.2. Socket Classes

class coro.sock

Bases: object

sock(int domain=AF_INET, int stype=SOCK_STREAM, int protocol=0, int fd=-1)

Coro socket object.

This is typically used for network sockets, but can also be used for coro-safe IO on any file descriptor that supports kqueue non-blocking operations.

The constructor takes the following parameters:

Parameters:

• domain – The socket domain family, defaults to AF_INET (see AF).
• stype – The socket type, defaults to SOCK_STREAM (see SOCK).
• protocol – The socket protocol (normally not used, defaults to 0).
• fd – The file descriptor to use. Creates a new socket file descriptor if not specified.

Variables:

• fd – The file descriptor number. Set to -1 when the socket is closed.
• orig_fd – The original file descriptor number. This is left for debugging purposes to determine which file descriptor was in use before the socket was closed.
• domain – The socket domain (AF_INET, AF_UNIX, AF_UNSPEC).
• stype – The socket type (SOCK_STREAM, SOCK_DGRAM)

accept(self)

Accept a connection.

Returns:A tuple (socket, address) where socket is a socket object and address is an (IP, port) tuple for IP addresses or a string for UNIX-domain sockets. IP addresses are returned as strings. Raises OSError:OS-level error.

accept_many(self, int max=0)

Accept multiple connections.

This will accept up to max connections for any connections available on the listen queue. This will block if there are no connections waiting.

Parameters:max – The maximum number of connections to accept. If not specified, defaults to infinity (accept all pending connections). Returns:A list of (socket, address) tuples (see accept() method for information on return format). Raises OSError:OS-level error.

bind(self, address)

Bind the socket.

Parameters:address – The address to bind to. For IP, it should be a (IP, port) tuple where the IP is a string. Use the empty string to indicate INADDR_ANY. The port should always be a host-byte-order integer. For Unix-domain sockets, the address should be a string. Raises OSError:OS-level error.

close(self)

Close the socket.

It is safe to call this if the socket is already closed.

Raises OSError:OS-level error.

connect(self, address)

connect_addr(self, address, int resolve=False)

Connect the socket.

Parameters:address – The address to connect to. For IP, it should be a (IP, port) tuple where the IP is a string. The port should always be a host-byte-order integer. For Unix-domain sockets, the address should be a string. Raises OSError:OS-level error.

domain

domain: ‘int’

dup(self)

Duplicate the socket object using the OS dup() call.

Returns:A new sock instance that holds the new file descriptor.

fd

fd: ‘int’

fileno(self)

Get the current file descriptor.

Returns:The current file descriptor number. Returns -1 if the socket is closed.

get_fileno(self)

Get the current file descriptor.

Returns:The current file descriptor number. Returns -1 if the socket is closed.

getpeername(self)

Get the remote-side address.

Returns:A (IP, port) tuple for IP addresses where IP is a string. Returns a string for UNIX-domain sockets. Raises OSError:OS-level error.

getsockname(self)

Get the local address of the socket.

Returns:A (IP, port) tuple for IP addresses where IP is a string or an empty string for INADDR_ANY. Returns a string for UNIX-domain sockets (empty string if not bound).

getsockopt(self, int level, int optname, socklen_t buflen=0)

Get a socket option.

Parameters:

• level – The socket level to get (see SOL).
• optname – The socket option to get (see SO).
• buflen – The size of the buffer needed to retrieve the value. If not specified, it assumes the result is an integer and will return an integer. Otherwise, it will create a new string with the result, and you may use the struct module to decode it.

Returns:

An integer if buflen is zero, otherwise returns a string.

Raises OSError:

OS-level error.

listen(self, backlog)

Set the socket to listen for connections.

Parameters:backlog – The maximum size of the queue for pending connections. Raises OSError:OS-level error.

makefile(self, mode='r', bufsize=-1)

Return a regular file object corresponding to the socket.

The mode and bufsize arguments are as for the built-in open() function.

The underlying socket is duplicated via sock.dup to emulate Python’s reference counting behavior.

Parameters:

• mode – The mode of the file, defaults to ‘r’.
• bufsize – The buffer size (0 is no buffering, 1 is line buffering, greater than 1 is the explicit buffer size). Defaults to -1 (does not change the default buffering).

Returns:

A file-like object that wraps the socket.

orig_fd

orig_fd: ‘int’

read(self, buffer_size)

Read data.

This is an alias for the recv() method.

readv(self, size_list)

Read a vector array of data.

This will repeatedly call readv until all data is received. If the end of the stream is reached before all data is received, then the result tuple will only contain the elements competely or partially received.

Parameters:size_list – A sequence of integers that indicates the buffer sizes to read. Returns:A tuple of strings corresponding to the sizes requested in size_list. Raises OSError:OS-level error.

recv(self, int buffer_size)

Receive data.

This may return less data than you request if the socket buffer is not large enough. Use recv_exact() to ensure you receive exactly the amount requested.

Parameters:buffer_size – The number of bytes to receive. Returns:A string of data. Returns the empty string when the end of the stream is reached. Raises OSError:OS-level error.

recv_exact(self, int bytes)

Receive exactly the number of bytes requested.

This will repeatedly call read until all data is received.

Parameters:

bytes – The number of bytes to receive.

Returns:

The data as a string.

Raises:

• OSError – OS-level error.
• EOFError – Not all data could be read. The first argument includes any partial data read as a string.

recv_into(self, buffer, int nbytes=0, int flags=0)

Receive data into a Python buffer.

This is for the Python buffer interface. If you don’t know what that is, move along. This method is for Python socket compatibility.

Parameters:

• buffer – A writeable Python buffer object. Must be a contiguous segment.
• nbytes – Number of bytes to read. Must be less than or equal to the size of the buffer. Defaults to 0 which means the size of buffer.
• flags – Flags for the recv system call (see recv(2) manpage). Defaults to 0.

Returns:

The number of bytes read.

Raises OSError:

OS-level error.

recvfrom(self, int buffer_size, int flags=0)

Receive data.

This may return less data than you request if the socket buffer is not large enough.

Parameters:

• buffer_size – The number of bytes to receive.
• flags – Socket flags to set (defaults to 0) (see recvfrom(2) manpage).

Returns:

A tuple (data, address) where data is a string and address is the address of the remote side (string for unix-domain, tuple of (IP, port) for IP where IP is a string and port is an integer). Data is the empty string when the end of the stream is reached.

Raises OSError:

OS-level error.

recvfrom_into(self, buffer, int nbytes=0, int flags=0)

Receive data into a Python buffer.

This is for the Python buffer interface. If you don’t know what that is, move along. This method is for Python socket compatibility.

Parameters:

• buffer – A writeable Python buffer object. Must be a contiguous segment.
• nbytes – Number of bytes to read. Must be less than or equal to the size of the buffer. Defaults to 0 which means the size of buffer.
• flags – Flags for the recv system call (see recvfrom(2) manpage). Defaults to 0.

Returns:

A tuple (nbytes, address) where bytes is the number of bytes read and address then it is the address of the remote side.

Raises OSError:

OS-level error.

send(self, data)

Send data on the socket.

This will repeatedly call write to ensure all data has been sent. This will raise OSError if it is unable to send all data.

Parameters:data – The data to send. Returns:The number of bytes sent, which should always be the length of data. Raises OSError:OS-level error.

sendall(self, data)

Send all data.

This is an alias for the send() method.

sendto(self, data, address, int flags=0)

Send data to a specific address.

Parameters:

• data – The data to send.
• address – The address to send to. For unix-domain sockets, this is a string. For IP sockets, this is a tuple (IP, port) where IP is a string. Port is always an integer.
• flags – sendto flags to use (defaults to 0) (see sendto(2) manpage).

Returns:

The number of bytes sent which may be less than the send requested.

Raises OSError:

OS-level error.

set_reuse_addr(self)

Set the SO_REUSEADDR socket option.

setsockopt(self, int level, int optname, value)

Set a socket option.

Parameters:

• level – The socket level to set (see SOL).
• optname – The socket option to set (see SO).
• value – The value to set. May be an integer, or a struct-packed string.

Raises OSError:

OS-level error.

shutdown(self, int how)

Shutdown the socket.

Parameters:how – How to shut down the socket (see the shutdown(2) manpage). Raises OSError:OS-level error.

stype

stype: ‘int’

wait_for_read(self)

Block until the socket is readable.

This will block until there is data available to be read.

Returns:The amount “readable”. For different sockets, this may be different values, see the EVFILT_READ section of the kevent manpage for details. Raises OSError:OS-level error.

wait_for_write(self)

Block until the socket is writeable.

This will block until it is possible to write to the socket.

Returns:The number of bytes writeable on the socket. Raises OSError:OS-level error.

write(self, data)

Write data.

This is an alias for the send() method.

writev(self, data)

Write a vector array of data.

This will repeatedly call writev until all data is sent. If it is unable to send all data, it will raise an OSError exception.

Parameters:data – A sequence of strings to write. Returns:The number of bytes sent which should always be the sum of the lengths of all the strings in the data sequence. Raises OSError:OS-level error.

class coro.file_sock

Bases: coro._coro.sock

file_sock(fileobj) A file-object wrapper using the socket object.

The constructor takes one argument:

param fileobj:A Python-like file object. Currently only needs to implement the fileno method.

When the object is deallocated, the file descriptor is closed.

class coro.fd_sock

Bases: coro._coro.sock

fd_sock(fd) A file-descriptor wrapper using the socket object.

The constructor takes one argument:

param fd:A file descriptor.

When the object is deallocated, the file descriptor is closed.

2.3. Socket Functions

The coro module offers the following functions related to sockets.

coro.get_live_sockets()

Get the number of live socket objects. This includes socket objects that are closed.

Returns:The number of socket objects.

2.4. Socket Constants

The following classes provide a variety of constants often used with sockets.

class coro.AF

Socket families.

coro.PF

alias of AF

class coro.SHUT

Socket shutdown methods.

class coro.SO

Socket options.

class coro.SOCK

Socket types.

class coro.SOL

Socket levels.