io.Socket

io.SOCKET

The agutil.io module includes the class Socket. Socket instances provide a simple interface built on top of the standard library's socket.

API

• Socket(address, port) (constructor) Creates a connection to address:port

• Socket.send(msg) Encodes and sends msg over the connection. msg must either be a str or bytes object. Transmission starts with a sequence of bytes representing ascii numerals equaling the length (in bytes) of the following payload. The length transmission is terminated with ascii 124 (the pipe character, | ). Then the payload (the message sent) follows.

• Socket.recv(decode=False) Receives a message over the connection (following the above protocol) The received payload is returned (the length string and pipe character are discarded) If decode is true, then the payload will be decoded into a str object before returned

• Socket.settimeout(time) Passes the value time (in seconds) to the internal socket object's settimeout method. A non-zero value will set all socket operations to have a timeout equal to time If time is 0, the socket is set to non-blocking mode If time is None, the socket is set to blocking mode

• Socket.gettimeout() Returns the timeout set on the underlying socket

• Socket.close() Shuts down and closes the connection

---

Note on padding:

Socket objects add a few bytes to every message sent to ensure message integrity while allowing the user to send messages of arbitrary length. Each message is preceded by 2 or more bytes indicating the length of the message to follow, and is followed by 3 bytes of padding to detect errors in transmission. The amount of padding is at least 5 bytes, but increases proportional to the log of the message length. The formula for the exact amount of padding bytes added for a message with length len is as follows: padding = 4 + ceil(log16(3 + len))