The application interfaces are implemented by application developers to provide application-specific logic. The core application interface is IConnectionHandler:
Application objects that can handle connection input-data events
This is an application interface.
The methods defined be this interface will never be called simultaneously from separate threads, so implementation of the methods needn’t be concerned with thread safety with respect to these methods.
Receive notification that a connection has closed
The reason argument can be converted to a string for logging purposes. It may have data useful for debugging, but this is undefined.
Notifications are received when the connection is closed externally, for example, when the other side of the connection is closed or in case of a network failure. No notification is given when the connection’s close method is called.
Recieve a report of an exception encountered by a connection
This method is used to recieve exceptions from an NGI implementation. This will only be due to an error encounted processing data passed to the connection writelines methods.
Handle input data from a connection
The data is an 8-bit string.
Note that there are no promises about data organization. The data isn’t necessarily record oriented. For example, data could, in theory be passed one character at a time. It is up to applications to organize data into records, if desired.
Receive notifications of connection results
This is an application interface.
Receive notification that a connection had been established
Receive notification that a connection could not be established
The reason argument can be converted to a string for logging purposes. It may have data useful for debugging, but this is undefined.
Handle server connections
This is an application interface.
A server is just a callable that takes a connection and set’s it’s handler.
Handle udp messages
This is an application interface.
A UDP handler is a callable that takes a client address and an 8-bit string message.
Implementation interfaces are provided by an implementation and used by applications.
Network connections
This is an implementation interface.
Network connections support communication over a network connection, or any connection having separate input and output channels.
Close the connection
This method is thread safe. It may be called by any thread at any time.
Set the IConnectionHandler for a connection.
This method may be called multiple times, but it should only be called in direct response to an implementation call to a IConnectionHandler, IClientConnectHandler, or IServer.
Any failure of a handler call must be caught and logged. If an exception is raised by a call to hande_input or handle_exception, the connection must be closed by the implementation.
Output a string to the connection.
The write call is non-blocking.
This method is thread safe. It may be called by any thread at any time.
Output an iterable of strings to the connection.
The writelines call is non-blocking. Note, that the data may not have been consumed when the method returns.
This method is thread safe. It may be called by any thread at any time.
Standard interface for ngi implementations
Try to make a connection to the given address
The handler is an IClientConnectHandler. The handler connected method will be called with an IConnection object if and when the connection succeeds or failed_connect method will be called if the connection fails.
This method is thread safe. It may be called by any thread at any time.
Listen for incoming TCP connections
When a connection is received, call the handler.
An IListener object is returned.
This method is thread safe. It may be called by any thread at any time.
Send a UDP message
This method is thread safe. It may be called by any thread at any time.
Listen for incoming UDP messages
When a message is received, call the handler with the message.
An IUDPListener object is returned.
This method is thread safe. It may be called by any thread at any time.
Listener information and close control
This is an implementation interface.
The address the listener is listening for connections on.
Close the listener and all of its connections
If no handler is passed, the listener and its connections are closed immediately without waiting for any pending input to be handled or for pending output to be sent.
If a handler is passed, the listener will stop accepting new connections and existing connections will be left open. The handler will be called when all of the existing connections have been closed.
return an iterable of the current connections
Server connection
This is an implementation interface.
This section provides additional information about the included NGI implementations. For the most part, any implementation is specified by IImplementation, however, there are a few details of interest for the implementations.
As its name implies, the testing implementation supports testing application code. It allows testing networking applications without actually creating any sockets and without having to resort to threads or subprocesses.
Like any NGI implementation, the testing implementation is defined by IImplementation. This section expands on the documentation provided by IImplementation.
Note
The testing implementation provides a number of functions and methods not documented here or in the NGI interfaces that were documented in earlier versions of NGI. These should now be viewed as deprecated or internal to the testing implementation.
Addresses are only barely used by the testing implementation. Any hashable object may be used as an address.
The Connection class provides an implementation of IConnection. Connections may be created automatically by the implementation and passed to servers or client connect handlers <zc.ngi.interfaces.IClientConnectHandler, but for testing, you’ll often want to create your own connections so you can pass them to handlers yourself. Connections are created by calling them without arguments:
connection = zc.ngi.testing.Connection()
My default, test connections have handlers that write data to standard output. You can change their handlers using set_handler.
Test connections are used in pairs to simulate both ends of TCP connections. Connections have a peer attribute which represents the other end of a connection. A connection is its peer’s peer. When you pass data to a connection’s write or writelines methods, the data will ultimately be passed to the handle_input method of the connection’s peer.
The async impementation provides a real networking implementation using the asyncore module from the Python standard library. All you really need to know about it is described by the IImplementation interface. This section provides a few additional details of interest.
Addresses are generally 2-tuples having a host address and an integer port. On Unix-like systems, they may also be strings giving names of unix domain sockets.
The listener method also allows None to be passed as an address. If None is passed, a unused port on localhost will be randomly selected. The resulting address can be obtained using the address attribute. This is mainly useful for testing,
The zc.ngi.async modules provides a number of threading modes. See zc.ngi.async implementations and threading.