Skip to content
This repository has been archived by the owner on Sep 10, 2022. It is now read-only.

io.QueuedSocket

Jump to bottom
Aaron Graubert edited this page Sep 18, 2018 · 9 revisions

Deprecation Notice: agutil.io.QueuedSocket is deprecated in favor of agutil.io.MPlexSocket

io.QueuedSocket

The agutil.io module includes the class QueuedSocket which wraps a regular agutil.io.Socket class. QueuedSocket instances are designed to allow multiple threads to utilize the same socket by dividing data across multiple channels. The .send() and .recv() methods now take an (optional) additional channel argument compared to the methods on a regular agutil.io.Socket instance (API below). .send() and .recv() will send and receive data across the specified channel.

API

  • QueuedSocket(address, port, logmethod=agutil.DummyLog) (Constructor)

    address and port are used to establish a connection to a remote socket. logmethod specifies a logging object to use (it defaults to agutil.DummyLog), but may also be an agutil.Logger instance or a bound method returned by agutil.Logger.bindToSender().

  • QueuedSocket.send(msg, channel='__orphan__') Sends a message over the specified channel. If the channel argument is omitted, it is sent over a default channel. Channel names cannot contain the pipe character ('|', ascii 124), which is used as a delimiter for encoding the channel name into transmissions

  • QueuedSocket.recv(channel='__orphan__', decode=False, timeout=None) Receives a message from the specified channel, or blocks until a message is available. If decode is True, the bytes object is decoded into a str object. If a timeout is specified and not None, the method will block for at most timeout seconds, then raise a socket.timeout exception.

  • QueuedSocket.close(timeout=1) Shuts down the connection and closes the underlying agutil.io.Socket. If a timeout is specified, this is the maximum amount of time the QueuedSocket will wait for its background thread to finish before closing the socket.

  • QueuedSocket.settimeout(timeout) Sets the socket timeout. This method is identical to agutil.io.Socket.settimeout()

  • QueuedSocket.gettimeout() Returns the current timeout. This method is identical to agutil.io.Socket.gettimeout()

  • queuedsocket.flush()

    Waits for all queued outgoing messages to be sent, then returns.

Note on padding:

QueuedSockets add a few extra bytes to each message sent to indicate the channel of the message. In addition to the padding added by the underlying agutil.io.Socket protocol (see this note for a description of Socket message padding), QueuedSockets add a minimum of 5 bytes to each message. The formula for the exact amount of padding added for a channel name with a length len is as follows: padding = 5 + len

Clone this wiki locally