Module network.channel

Description

load network.channel

This module provides message-oriented channel abstractions for exchanging protocol messages over a network socket.

The implementations are split by execution model:

• Network.Channel performs synchronous exchanges and returns immediately when a read or write operation can be completed.
• Network.AsyncChannel exposes coroutine-friendly methods that suspend until the underlying socket becomes ready for the requested operation.
• Network.EventChannel is designed for event-driven usage and integrates with the polling layer so it can be driven by readiness notifications.

In all cases, the underlying socket is responsible for the low-level I/O and the serializer is responsible for framing and decoding message objects.

Packages

• Network

Classes

Network.AsyncChannel

This class provides coroutine-friendly, message-oriented communication over a socket using a serializer. The read, write, and close operations are asynchronous and may suspend the current coroutine until the requested operation completes. This class is intended for use with Runtime.Scheduler and Mint coroutines. When an operation cannot complete immediately, it is submitted to the underlying asynchronous I/O mechanism. The scheduler resumes the coroutine when the operation has completed, either successfully or with an error.

Public members

Modifiers	Member	Description
const	bind	Attempts to bind the channel to the remote device identified by endpoint. Ret...
const	close	Closes the communication with the peer. Returns true if the channel was succe...
	connect	Attempts to make a connection to the remote device identified by endpoint. Re...
const	getHandle	Returns the channel's socket's handle as an instance of mint::handle_t. This ...
const	getScheduler	Returns the scheduler associated with the object. This method calls the Netwo...
const	getSocket	Returns the underlying end point object.
const	getState	Returns the current state of the underlying socket as a value of Network.Asyn...
const	isOpen	Returns true if the underlying socket is open; otherwise returns false.
const	listen	Tells the channel to listen for incoming connections on address configured by ``...
const	new	Creates a new asynchronous channel to manage exchanges with the asynchronous ...
	read	Returns the next message object in the reply queue or none if no more message...
	write	Writes the pending data to the underlying socket. Returns true if the write o...

Private members

Modifiers	Member	Description
final	reply	Internal serializer object for reading replies.
final	request	Internal serializer object for writing requests.
final	socket	Internal underlying socket.

Network.Channel

This class provides synchronous, message-oriented communication over a socket using a serializer.

Each operation is attempted immediately. If the underlying socket is not yet ready, the operation returns false or none, and the caller can retry later or switch to one of the other channel abstractions.

This class is well suited for explicit I/O loops and for code that wants to control buffering and readiness handling itself.

For coroutine-based flows, prefer Network.AsyncChannel. For event-driven loops that are driven by Network.Poller, prefer Network.EventChannel.

Public members

Modifiers	Member	Description
const	bind	Attempts to bind the channel to the remote device identified by endpoint. Ret...
const	close	Closes the communication with the peer if the channel was connected using the ``...
const	connect	Attempts to make a connection to the remote device identified by endpoint. Re...
const	finalizeConnection	Finalize the connection to the peer. Return true if the connection succeed; o...
const	getHandle	Returns the channel's socket's handle as an instance of mint::handle_t. This ...
const	getSocket	Returns the underlying end point object.
const	getState	Returns the current state of the channel as a value of Network.Channel.Networ...
const	isNonBlocking	Returns true if the channel performs I/O operations asynchronously (i.e. read...
const	isOpen	Returns true if the underlying socket is open; otherwise returns false.
const	listen	Tells the channel to listen for incoming connections on address configured by ``...
const	new	Creates a new channel to manage synchronous exchanges with the device describ...
const	read	Returns the next message object in the reply queue or none if no more message...
const	setNonBlocking	Sets the non blocking mode of the channel to enabled. This method calls the N...
const	shutdown	Disable sends or receives on the socket if it was in the Network.Channel.Netw...
const	write	Writes the pending data to the underlying socket. Returns true if the write o...

Private members

Modifiers	Member	Description
final	reply	Internal serializer object for reading replies.
final	request	Internal serializer object for writing requests.
final	socket	Internal underlying socket.

Network.EventChannel

This class provides event-driven, message-oriented communication over a socket using a serializer.

It is intended for code that consumes readiness notifications from Network.Poller rather than relying on coroutine suspension. Operations are driven by state and readiness callbacks and are suitable for applications that manage their own event loop or integrate with the poller infrastructure.

Public members

Modifiers	Member	Description
const	!=	Returns false if other is equal to this channel; otherwise returns true.
const	==	Returns true if other is equal to this channel; otherwise returns false.
const	bind	Attempts to bind the channel to the remote device identified by endpoint. Ret...
const	close	Closes the communication with the peer if the channel was connected using the ``...
const	connect	Attempts to make a connection to the remote device identified by endpoint. Th...
const	getEvents	Returns the events expected by the channel as mask of values from the Network...
const	getHandle	Returns the channel's socket's handle as an instance of mint::handle_t. This ...
const	getSocket	Returns the underlying end point object.
const	getState	Returns the current state of the channel as a value of Network.EventChannel.N...
const	isNonBlocking	Returns true if the channel performs I/O operations asynchronously (i.e. read...
const	isOpen	Returns true if the underlying socket is open; otherwise returns false.
const	listen	Tells the channel to listen for incoming connections on address configured by ``...
const	new	Creates a new channel to manage asynchronous exchanges with the device descri...
const	notifyClosed	Notifies the channel that the connection was closed by the peer. The connecti...
const	notifyConnection	Notifies the listening channel that the underlying end point has received a n...
const	notifyError	Notifies the channel that the underlying end point has received an error. The...
const	notifyReadable	Notifies the channel that the underlying end point is readable. The channel w...
const	notifyStateChanged	Notifies the channel that the underlying end point's state is about to change...
const	notifyWritable	Notifies the channel that the underlying end point is writable. The channel w...
	onClose	This method can be rebound to handle close events. The channel parameter is t...
	onMessage	This method can be rebound to handle message events. The channel parameter is...
	onOpen	This method can be rebound to handle connection success events. The channel p...
	onState	This method can be rebound to handle state change events. The channel paramet...
const	read	Returns the next message object in the reply queue or none if no more message...
const	setNonBlocking	Sets the non blocking mode of the channel to enabled. This method calls the N...
const	write	Pushes the message object described by data to the request queue. The message...

Private members

Modifiers	Member	Description
class	DataQueue	This class manage a data queue where data can be pushed as messages or as byt...
final	reply	Internal Network.EventChannel.DataQueue instance for replies waiting to be read.
final	request	Internal Network.EventChannel.DataQueue instance for requests waiting to be s...
final	socket	Internal underlying end point.

Network.EventChannel.DataQueue

This class manage a data queue where data can be pushed as messages or as byte stream and converted using an object implementing the network.serializers interface.

Any method of this class is thread safe.

Public members

Modifiers	Member	Description
const	accept	Performs an accept operation on socket and push the new socket in the queue. ...
const	isEmpty	Returns true if no more message can be retrieved from the queue; otherwise re...
const	new	Creates a new data queue. The Serializer parameter must be a class implementi...
const	pop	Removes the oldest message from the queue and returns it. If no more message ...
const	push	Pushes the message object described by data into the queue. The data paramete...
const	read	Performs a read operation on socket and append received data to the queue. R...
const	write	Performs a write operation on socket using the data available in the queue. R...

Private members

Modifiers	Member	Description
final	mutex	Internal mutex.
final	serializer	Internal serializer object.

Descriptions

Network.AsyncChannel.bind

def (self, endpoint)

Attempts to bind the channel to the remote device identified by endpoint. Returns true if binding succeed; otherwise returns false. This method calls the Network.Socket.bind method of the underlying object.

An instance of Exception.SocketError is raised on error.

Network.AsyncChannel.close

def (self)

Closes the communication with the peer. Returns true if the channel was successfully closed; otherwise returns false.

The underlying synchronous close attempt is performed by Network.AsyncSocket.close.

On success, the channel enters the Network.Socket.State.Closed state.

On failure, the channel enters the Network.Socket.State.Error state.

Network.AsyncChannel.connect

def (self, endpoint)

Attempts to make a connection to the remote device identified by endpoint. Returns true if connection succeed; otherwise returns false. This method calls the Network.Socket.connect method of the underlying object.

This method suspends the current coroutine until the connection attempt either succeeds or fails.

If the method returns false and the underlying end point enters the Network.Socket.State.Connecting state, the connection must be finalized later using the finalizeConnection method.

An instance of Exception.SocketError is raised on error.

Network.AsyncChannel.getHandle

def (const self)

Returns the channel's socket's handle as an instance of mint::handle_t. This method calls the Network.Socket.getHandle method of the underlying object.

Network.AsyncChannel.getScheduler

def (const self)

Returns the scheduler associated with the object. This method calls the Network.Socket.getScheduler method of the underlying object.

Network.AsyncChannel.getSocket

def (const self)

Returns the underlying end point object.

Network.AsyncChannel.getState

def (const self)

Returns the current state of the underlying socket as a value of Network.Socket.State.

Network.AsyncChannel.isOpen

def (const self)

Returns true if the underlying socket is open; otherwise returns false.

Network.AsyncChannel.listen

def (self, endpoint)

Tells the channel to listen for incoming connections on address configured by endpoint. Returns true on success; otherwise returns false. This method calls the Network.Socket.listen method of the underlying object. The Network.ServerSerializer should be used has serializer class to correctly handle incoming connections.

An instance of Exception.SocketError is raised on error.

Network.AsyncChannel.new

def (self, socket, Serializer = Network.AsyncTextSerializer)

Creates a new asynchronous channel to manage exchanges with the asynchronous device described by socket.

Network.AsyncChannel.read

def (self)

Returns the next message object in the reply queue or none if no more message is available.

This method suspends the current coroutine until the read operation completes.

The message objects are created from a Serializer.DataStream using the serializer class. The serializer must receive enough data from the peer to construct a message using the Network.Socket.read method of the underlying socket.

Network.AsyncChannel.reply

null

Internal serializer object for reading replies.

Network.AsyncChannel.request

null

Internal serializer object for writing requests.

Network.AsyncChannel.socket

null

Internal underlying socket.

Network.AsyncChannel.write

def (self)

Writes the pending data to the underlying socket. Returns true if the write operation succeed; otherwise returns false and the remaining data should be sent later.

This method suspends the current coroutine until the write operation completes.

The message object will be converted to Serializer.DataStream using the serializer class and sent to the peer using the Network.Socket.write method of the underlying socket.

def (self, data)

Writes the message object described by data to the underlying socket. Returns true if the write operation succeed; otherwise returns false and the remaining data should be sent later using write.

This method suspends the current coroutine until the write operation completes.

The message object will be converted to Serializer.DataStream using the serializer class and sent to the peer using the Network.Socket.write method of the underlying socket.

Network.Channel.bind

def (self, endpoint)

Attempts to bind the channel to the remote device identified by endpoint. Returns true if binding succeed; otherwise returns false. This method calls the Network.Socket.bind method of the underlying object.

An instance of Exception.SocketError is raised on error.

Network.Channel.close

def (self)

Closes the communication with the peer if the channel was connected using the connect method or stops listening if the channel was opened with listen. This method calls the Network.Socket.close method of the underlying object.

An instance of Exception.SocketError is raised on error.

Network.Channel.connect

def (self, endpoint)

Attempts to make a connection to the remote device identified by endpoint. Returns true if connection succeed; otherwise returns false. This method calls the Network.Socket.connect method of the underlying object.

If the method returns false and the underlying end point enters the Network.Socket.State.Connecting state, the connection must be finalized later using the finalizeConnection method.

An instance of Exception.SocketError is raised on error.

Network.Channel.finalizeConnection

def (self)

Finalize the connection to the peer. Return true if the connection succeed; otherwise returns false. This method calls the Network.Socket.finalizeConnection method of the underlying end point.

An instance of Exception.SocketError is raised on error.

Network.Channel.getHandle

def (const self)

Returns the channel's socket's handle as an instance of mint::handle_t. This method calls the Network.Socket.getHandle method of the underlying object.

Network.Channel.getSocket

def (const self)

Returns the underlying end point object.

Network.Channel.getState

def (const self)

Returns the current state of the channel as a value of Network.Socket.State. This method calls the Network.Socket.getState method of the underlying object.

Network.Channel.isNonBlocking

def (const self)

Returns true if the channel performs I/O operations asynchronously (i.e. read or write data without blocking other channels); otherwise returns false. This method calls the Network.Socket.isNonBlocking method of the underlying object.

Network.Channel.isOpen

def (const self)

Returns true if the underlying socket is open; otherwise returns false.

Network.Channel.listen

def (self, endpoint)

Tells the channel to listen for incoming connections on address configured by endpoint. Returns true on success; otherwise returns false. This method calls the Network.Socket.listen method of the underlying object. The Network.ServerSerializer should be used has serializer class to correctly handle incoming connections.

An instance of Exception.SocketError is raised on error.

Network.Channel.new

def (self, socket, Serializer = Network.TextSerializer)

Creates a new channel to manage synchronous exchanges with the device described by socket. The socket parameter must implement the Network.Socket interface. The Serializer parameter must be a class implementing the network.serializers interface used to detect messages end and convert exchanged data into objects.

If the socket parameter is none, the channel is not created.

Network.Channel.read

def (self)

Returns the next message object in the reply queue or none if no more message is available.

The message objects are created from a Serializer.DataStream using the serializer class. The serializer must receive enough data from the peer to construct a message using the Network.Socket.read method of the underlying socket.

Network.Channel.reply

null

Internal serializer object for reading replies.

Network.Channel.request

null

Internal serializer object for writing requests.

Network.Channel.setNonBlocking

def (self, enabled)

Sets the non blocking mode of the channel to enabled. This method calls the Network.Socket.setNonBlocking method of the underlying object. Returns true if the mode was successfully changed; otherwise returns false.

[!WARNING] Disable the non blocking mode on a channel can slow down any network I/O operations of the application. Other channels will not be able to perform I/O operations until the current operation's acknowledgment by the peer.

An instance of Exception.SocketError is raised on error.

Network.Channel.shutdown

def (self)

Disable sends or receives on the socket if it was in the Network.Socket.State.Connected state or stops listening if it was in the Network.Socket.State.Listening state. This method calls the Network.Socket.shutdown method of the underlying object.

An instance of Exception.SocketError is raised on error.

Network.Channel.socket

null

Internal underlying socket.

Network.Channel.write

def (self)

Writes the pending data to the underlying socket. Returns true if the write operation succeed; otherwise returns false and the remaining data should be sent later.

The message object will be converted to Serializer.DataStream using the serializer class and sent to the peer using the Network.Socket.write method of the underlying socket.

def (self, data)

Writes the message object described by data to the underlying socket. Returns true if the write operation succeed; otherwise returns false and the remaining data should be sent later using write.

The message object will be converted to Serializer.DataStream using the serializer class and sent to the peer using the Network.Socket.write method of the underlying socket.

Network.EventChannel.!=

def (const self, const other)

Returns false if other is equal to this channel; otherwise returns true.

Network.EventChannel.==

def (const self, const other)

Returns true if other is equal to this channel; otherwise returns false.

Network.EventChannel.DataQueue.accept

def (self, socket)

Performs an accept operation on socket and push the new socket in the queue. Returns true if a new connection was successfully accepted; otherwise returns false.

Network.EventChannel.DataQueue.isEmpty

def (const self)

Returns true if no more message can be retrieved from the queue; otherwise returns false.

Network.EventChannel.DataQueue.mutex

null

Internal mutex.

Network.EventChannel.DataQueue.new

def (self, Serializer)

Creates a new data queue. The Serializer parameter must be a class implementing the network.serializers interface used to detect messages end and convert data from or to objects.

Network.EventChannel.DataQueue.pop

def (self)

Removes the oldest message from the queue and returns it. If no more message can be generated using the remaining byte stream, none is returned.

Network.EventChannel.DataQueue.push

def (self, data)

Pushes the message object described by data into the queue. The data parameter must a message object that can be converted into a byte stream by the serializer object to be stored in the queue.

Network.EventChannel.DataQueue.read

def (self, socket)

Performs a read operation on socket and append received data to the queue. Returns true if at least one message can be constructed from the data pushed into the queue; otherwise returns false.

Network.EventChannel.DataQueue.serializer

null

Internal serializer object.

Network.EventChannel.DataQueue.write

def (self, socket)

Performs a write operation on socket using the data available in the queue. Returns true if the data was successfully sent; otherwise returns false. After this call, the sent data should be removed from the queue.

Network.EventChannel.bind

def (self, endpoint)

Attempts to bind the channel to the remote device identified by endpoint. Returns true if binding succeed; otherwise returns false. This method calls the Network.Socket.bind method of the underlying object.

An instance of Exception.SocketError is raised on error.

Network.EventChannel.close

def (self)

Closes the communication with the peer if the channel was connected using the connect method or stops listening if the channel was opened with listen. This method calls the Network.Socket.close method of the underlying object. If the socket was successfully closed, onClose is called; otherwise the socket will be closed later.

An instance of Exception.SocketError is raised on error.

Network.EventChannel.connect

def (self, endpoint)

Attempts to make a connection to the remote device identified by endpoint. This method calls the Network.Socket.connect method of the underlying object.

The channel is connected asynchronously when the connection is accepted by the peer. The connection will be finalized if Network.poll is called on this instance. On connection success, the onOpen method will be called.

An instance of Exception.SocketError is raised on error.

Network.EventChannel.getEvents

def (const self)

Returns the events expected by the channel as mask of values from the Network.PollEvent enum.

Network.EventChannel.getHandle

def (const self)

Returns the channel's socket's handle as an instance of mint::handle_t. This method calls the Network.Socket.getHandle method of the underlying object.

Network.EventChannel.getSocket

def (const self)

Returns the underlying end point object.

Network.EventChannel.getState

def (const self)

Returns the current state of the channel as a value of Network.Socket.State. This method calls the Network.Socket.getState method of the underlying object.

Network.EventChannel.isNonBlocking

def (const self)

Returns true if the channel performs I/O operations asynchronously (i.e. read or write data without blocking other channels); otherwise returns false. This method calls the Network.Socket.isNonBlocking method of the underlying object.

Network.EventChannel.isOpen

def (const self)

Returns true if the underlying socket is open; otherwise returns false.

Network.EventChannel.listen

def (self, endpoint)

Tells the channel to listen for incoming connections on address configured by endpoint. Returns true on success; otherwise returns false. This method calls the Network.Socket.listen method of the underlying object. The Network.ServerSerializer should be used has serializer class to correctly handle incoming connections.

An instance of Exception.SocketError is raised on error.

Network.EventChannel.new

def (self, socket, Serializer = Network.TextSerializer)

Creates a new channel to manage asynchronous exchanges with the device described by socket. The socket parameter must implement the Network.Socket interface. The Serializer parameter must be a class implementing the network.serializers interface used to detect messages end and convert exchanged data into objects.

If the socket parameter is none, the channel is not created. The call to Network.Socket.setNonBlocking must succeed to create the channel. The channel is created in non blocking mode and the socket parameter is configured to call the channel's notifyStateChanged, notifyReadable, notifyWritable, notifyConnection, notifyClosed and notifyError methods on state change, readability, writability, new connection, close and error events respectively.

Network.EventChannel.notifyClosed

def (self)

Notifies the channel that the connection was closed by the peer. The connection is then closed using Network.Socket.close and onClose is called.

An instance of Exception.SocketError is raised on error.

Network.EventChannel.notifyConnection

def (self)

Notifies the listening channel that the underlying end point has received a new connection request. The end point corrsponding to the new connection is pushed to the reply queue and onMessage is called.

An instance of Exception.SocketError is raised on error.

Network.EventChannel.notifyError

def (self)

Notifies the channel that the underlying end point has received an error. The end point state is updated to Network.Socket.State.Error and an instance of Exception.SocketError is raised.

Network.EventChannel.notifyReadable

def (self)

Notifies the channel that the underlying end point is readable. The channel will then read all available data on the end point and send it to the serializer object. If one or more message can created with the data, onMessage is called.

An instance of Exception.SocketError is raised on error.

Network.EventChannel.notifyStateChanged

def (self, % state)

Notifies the channel that the underlying end point's state is about to change. The state parameter is the new state that will be applied to the end point. This value is passed to a call to onState. The previous state can still be accessed with getState until the end of the method.

[!WARNING] Calling Network.Socket.setState in this method can result in an infinite loop.

Network.EventChannel.notifyWritable

def (self)

Notifies the channel that the underlying end point is writable. The channel will then send all available data from the serializer object to the end point. If the underlying end point was connecting, the connection is finalized and onOpen is called.

An instance of Exception.SocketError is raised on error.

Network.EventChannel.onClose

def (self, channel)

This method can be rebound to handle close events. The channel parameter is the channel that received the event. This can be used to cleanup a context or try to reconnect when the connection was closed by the peer.

Network.EventChannel.onMessage

def (self, channel)

This method can be rebound to handle message events. The channel parameter is the channel that received the event. The messages can be accessed using the read method.

[!NOTE] This method can be called for one or more messages and will not be called until the underlying end point receive more data. The read method should then be called by this method until none is returned.

Network.EventChannel.onOpen

def (self, channel)

This method can be rebound to handle connection success events. The channel parameter is the channel that received the event. This method can be used to begin exchanges with the peer.

Network.EventChannel.onState

def (self, channel, % state)

This method can be rebound to handle state change events. The channel parameter is the channel that received the event and the state parameter is the state that will be applied to the underlying end point. The previous state can still be accessed with getState until the end of the method.

[!WARNING] Calling Network.Socket.setState in this method can result in an infinite loop.

Network.EventChannel.read

def (self)

Returns the next message object in the reply queue or none if no more message is available.

Messages are added asynchronously when the underlying end point become readable if the channel is watched (see watch) and Runtime.Scheduler.synchronize is called or if Runtime.Scheduler.poll is called with an instance of Runtime.Scheduler.PollDescriptor created for this object.

The message objects are created from a DataStreamSerializer. using the serializer class. The serializer must receive enough data from the peer to construct a message using the Network.Socket.read method of the underlying end point.

Network.EventChannel.reply

null

Internal DataQueue instance for replies waiting to be read.

Network.EventChannel.request

null

Internal DataQueue instance for requests waiting to be sent.

Network.EventChannel.setNonBlocking

def (self, enabled)

Sets the non blocking mode of the channel to enabled. This method calls the Network.Socket.setNonBlocking method of the underlying object. Returns true if the mode was successfully changed; otherwise returns false.

[!WARNING] Disable the non blocking mode on a channel can slow down any network I/O operations of the application. Other channels will not be able to perform I/O operations until the current operation's acknowledgment by the peer.

An instance of Exception.SocketError is raised on error.

Network.EventChannel.socket

null

Internal underlying end point.

Network.EventChannel.write

def (self, data)

Pushes the message object described by data to the request queue.

The message is not sent directly but will be sent asynchronously when the underlying end point will become writable if the channel is watched (see watch) and Runtime.Scheduler.synchronize is called or if Runtime.Scheduler.poll is called with an instance of Runtime.Scheduler.PollDescriptor created for this object.

The message object will then be converted to Serializer.DataStream using the serializer class and sent to the peer using the Network.Socket.write method of the underlying end point.