Module network.channel

Description

load network.channel

This module provides classes to manage data exchanges between network devices using messages. The Network.AsynchronousChannel class manages asynchronous exchanges and Network.SynchronousChannel manage synchronous exchanges.

Packages

• Network

Classes

Network.AsynchronousChannel

This class manages asynchronous exchanges between network devices. Intances of this class should be synchronized using the Network.Scheduler object.

Public members

Modifiers	Member	Description
const	bind	Attempts to bind the channel to the remote device. Returns true if binding su...
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. This method calls the Net...
const	getEndpoint	Returns the underling end point object.
const	getEvents	Returns the events expected by the channel as mask of values from the Network...
const	getSocket	Returns the channel's socket as a number. This method calls the Network.Async...
const	getState	Returns the current state of the channel as a value of Network.AsynchronousCh...
const	isNonBlocking	Returns true if the channel performs I/O operations asynchronously (i.e. read...
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 underling end point has received a ne...
const	notifyError	Notifies the channel that the underling end point has received an error. The ...
const	notifyReadable	Notifies the channel that the underling end point is readable. The channel wi...
const	notifyStateChanged	Notifies the channel that the underling end point's state is about to change....
const	notifyWritable	Notifies the channel that the underling end point is writable. The channel wi...
	onClose	This method can be rebinded to handle close events. The channel parameter is ...
	onMessage	This method can be rebinded to handle message events. The channel parameter i...
	onOpen	This method can be rebinded to handle connection success events. The channel ...
	onState	This method can be rebinded to handle state change events. The channel parame...
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	unwatch	Removes the channel from the Network.AsynchronousChannel.Network.Scheduler ob...
const	watch	Adds the channel to the Network.AsynchronousChannel.Network.Scheduler object....
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	endpoint	Internal underling end point.
final	reply	Internal Network.AsynchronousChannel.DataQueue instance for replies waiting t...
final	request	Internal Network.AsynchronousChannel.DataQueue instance for requests waiting ...

Network.AsynchronousChannel.DataQueue

This class manage a data queue where data can be pushed as messages or as byte stream and converted unsing 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 endpoint and push the new endpoint in the que...
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 endpoint and append received data to the queue. ...
const	write	Performs a write operation on endpoint using the data available in the queue....

Private members

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

Network.SynchronousChannel

This class manages synchronous exchanges between network devices.

Public members

Modifiers	Member	Description
const	bind	Attempts to bind the channel to the remote device. Returns true if binding su...
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. Returns true if connectio...
const	finalizeClose	Finalize the close of the underling end point. Return true if the close succe...
const	finalizeConnection	Finalize the connection to the peer. Return true if the connection succed; ot...
const	getEndpoint	Returns the underling end point object.
const	getSocket	Returns the channel's socket as a number. This method calls the Network.Synch...
const	getState	Returns the current state of the channel as a value of Network.SynchronousCha...
const	isNonBlocking	Returns true if the channel performs I/O operations asynchronously (i.e. read...
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	write	Writes the pending data to the underling end point. Returns true if the write...

Private members

Modifiers	Member	Description
final	endpoint	Internal underling end point.
final	reply	Internal serializer object for reading replies.
final	request	Internal serializer object for writing requests.

Descriptions

Network.AsynchronousChannel.DataQueue.accept

def (self, endpoint)

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

Network.AsynchronousChannel.DataQueue.isEmpty

def (const self)

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

Network.AsynchronousChannel.DataQueue.mutex

null

Internal mutex.

Network.AsynchronousChannel.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.AsynchronousChannel.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.AsynchronousChannel.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.AsynchronousChannel.DataQueue.read

def (self, endpoint)

Performs a read operation on endpoint 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.AsynchronousChannel.DataQueue.serializer

null

Internal serializer object.

Network.AsynchronousChannel.DataQueue.write

def (self, endpoint)

Performs a write operation on endpoint 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.AsynchronousChannel.bind

def (self)

Attempts to bind the channel to the remote device. Returns true if binding succed; otherwise returns false. This method calls the Network.EndPoint.bind method of the underling object.

An instance of Exception.SocketError is raised on error.

Network.AsynchronousChannel.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 openned with listen. This method calls the Network.EndPoint.close method of the underling 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.AsynchronousChannel.connect

def (self)

Attempts to make a connection to the remote device. This method calls the Network.EndPoint.connect method of the underling object.

The channel is connected asynchronously when the connection is accepted by the peer. The connection will be finalized if the channel is watched (see watch) and Network.Scheduler.synchronize is called or if Network.Scheduler.poll is called with an instance of Network.Scheduler.PollDescriptor created for this object. On connection success, the onOpen method will be called.

An instance of Exception.SocketError is raised on error.

Network.AsynchronousChannel.endpoint

null

Internal underling end point.

Network.AsynchronousChannel.getEndpoint

def (const self)

Returns the underling end point object.

Network.AsynchronousChannel.getEvents

def (const self)

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

Network.AsynchronousChannel.getSocket

def (const self)

Returns the channel's socket as a number. This method calls the Network.EndPoint.getSocket method of the underling object.

Network.AsynchronousChannel.getState

def (const self)

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

Network.AsynchronousChannel.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.EndPoint.isNonBlocking method of the underling object.

Network.AsynchronousChannel.listen

def (self)

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

An instance of Exception.SocketError is raised on error.

Network.AsynchronousChannel.new

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

Creates a new channel to manage asynchronous exchanges with the device described by endpoint. The endpoint parameter must implement the Network.EndPoint 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 endpoint parameter is none, the channel is not created.

Network.AsynchronousChannel.notifyClosed

def (self)

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

An instance of Exception.SocketError is raised on error.

Network.AsynchronousChannel.notifyConnection

def (self)

Notifies the listening channel that the underling 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.AsynchronousChannel.notifyError

def (self)

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

Network.AsynchronousChannel.notifyReadable

def (self)

Notifies the channel that the underling 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.AsynchronousChannel.notifyStateChanged

def (self, % state)

Notifies the channel that the underling 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.EndPoint.setState in this method can result in an infinite loop.

Network.AsynchronousChannel.notifyWritable

def (self)

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

An instance of Exception.SocketError is raised on error.

Network.AsynchronousChannel.onClose

def (self, channel)

This method can be rebinded 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.AsynchronousChannel.onMessage

def (self, channel)

This method can be rebinded 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 underling end point receive more data. The read method should then be called by this method until none is returned.

Network.AsynchronousChannel.onOpen

def (self, channel)

This method can be rebinded 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.AsynchronousChannel.onState

def (self, channel, % state)

This method can be rebinded 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 underling end point. The previous state can still be accessed with getState until the end of the method.

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

Network.AsynchronousChannel.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 underling end point become readable if the channel is watched (see watch) and Network.Scheduler.synchronize is called or if Network.Scheduler.poll is called with an instance of Network.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.EndPoint.read method of the underling end point.

Network.AsynchronousChannel.reply

null

Internal DataQueue instance for replies waiting to be read.

Network.AsynchronousChannel.request

null

Internal DataQueue instance for requests waiting to be sent.

Network.AsynchronousChannel.setNonBlocking

def (self, enabled)

Sets the non blocking mode of the channel to enabled. This method calls the Network.EndPoint.setNonBlocking method of the underling 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.AsynchronousChannel.unwatch

def (self)

Removes the channel from the Network.Scheduler object. This method calls the Network.Scheduler.remove method.

Network.AsynchronousChannel.watch

def (self)

Adds the channel to the Network.Scheduler object. This method calls the Network.Scheduler.watch method.

An instance of Exception.SocketError is raised on error.

Network.AsynchronousChannel.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 underling end point will become writable if the channel is watched (see watch) and Network.Scheduler.synchronize is called or if Network.Scheduler.poll is called with an instance of Network.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.EndPoint.write method of the underling end point.

Network.SynchronousChannel.bind

def (self)

Attempts to bind the channel to the remote device. Returns true if binding succed; otherwise returns false. This method calls the Network.EndPoint.bind method of the underling object.

An instance of Exception.SocketError is raised on error.

Network.SynchronousChannel.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 openned with listen. This method calls the Network.EndPoint.close method of the underling object. Returns true if the socket was successfully closed; otherwise returns false.

If the method returns false and the underling end point enters the Network.EndPoint.State.Closing state, the close operation must be finalized later using the finalizeClose method.

An instance of Exception.SocketError is raised on error.

Network.SynchronousChannel.connect

def (self)

Attempts to make a connection to the remote device. Returns true if connection succed; otherwise returns false. This method calls the Network.EndPoint.connect method of the underling object.

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

An instance of Exception.SocketError is raised on error.

Network.SynchronousChannel.endpoint

null

Internal underling end point.

Network.SynchronousChannel.finalizeClose

def (self)

Finalize the close of the underling end point. Return true if the close succed; otherwise returns false. This method calls the Network.EndPoint.finalizeClose method of the underling end point.

An instance of Exception.SocketError is raised on error.

Network.SynchronousChannel.finalizeConnection

def (self)

Finalize the connection to the peer. Return true if the connection succed; otherwise returns false. This method calls the Network.EndPoint.finalizeConnection method of the underling end point.

An instance of Exception.SocketError is raised on error.

Network.SynchronousChannel.getEndpoint

def (const self)

Returns the underling end point object.

Network.SynchronousChannel.getSocket

def (const self)

Returns the channel's socket as a number. This method calls the Network.EndPoint.getSocket method of the underling object.

Network.SynchronousChannel.getState

def (const self)

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

Network.SynchronousChannel.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.EndPoint.isNonBlocking method of the underling object.

Network.SynchronousChannel.listen

def (self)

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

An instance of Exception.SocketError is raised on error.

Network.SynchronousChannel.new

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

Creates a new channel to manage synchronous exchanges with the device described by endpoint. The endpoint parameter must implement the Network.EndPoint 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 endpoint parameter is none, the channel is not created.

Network.SynchronousChannel.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.EndPoint.read method of the underling end point.

Network.SynchronousChannel.reply

null

Internal serializer object for reading replies.

Network.SynchronousChannel.request

null

Internal serializer object for writing requests.

Network.SynchronousChannel.setNonBlocking

def (self, enabled)

Sets the non blocking mode of the channel to enabled. This method calls the Network.EndPoint.setNonBlocking method of the underling 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.SynchronousChannel.write

def (self)

Writes the pending data to the underling end point. 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.EndPoint.write method of the underling end point.

def (self, data)

Writes the message object described by data to the underling end point. 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.EndPoint.write method of the underling end point.