The latest issue is socket shutdown.

Cpython sockets have two separate methods related to terminating a socket connection; the close method and the shutdown method.

Before we get into the difference between the two, we should note that when a TCP socket connection is to be terminated, a network packet containing a FIN is sent to the peer, informing them to tear down the connection (although sometimes an RST packet can be sent instead). It is a sometimes used practice to shutdown only one side of a connection. For example, when a client knows that its request has been fully transmitted, it shuts down its transmit stream to the server, but leaves the receive stream open for the response. This makes the clients intention for future communications more explicit, and may lighten the load on the server. However, this is controversial topic, because that can also lead asynchronous servers to mistakenly think that a socket is readable when it is not. You can find a detailed and thorough discussion of this topic in ActiveState Recipe 408997: When to not just use socket.close(); make sure to read all of the comments.

The close method of sockets closes the file descriptor to which the socket is connected. When the last file descriptor connected to the socket is closed, then the operating system also closes the underlying socket, which results in the transmission of the FIN packet. That wording is important: “when the last file descriptor .. is closed” has specific meaning in many unix network servers architectures. The archetypal design for a network server on unix is to accept incoming socket connections in one process, and then spawn a subprocess to service the connection. Since the child process inherits the file descriptor table of its parent, it also inherits a file descriptor for the socket. Which means that there can be multiple file descriptors open on a socket. Which means that closing a socket is not guaranteed to close the connection; that will not happen until all file descriptors for the socket are closed.

The shutdown method, on the other hand only sends the FIN packet, regardless of how many file descriptors are open to the socket; moreover, it doesn’t affect any of those file descriptors.

There are some problems for implementing shutdown on java and thus on jython. Java servers are almost always multi-threaded, and process incoming requests in spawned threads, not processes. For this reason, and because of the fact that java does not expose C file descriptors, there are no socket methods that differentiate between the socket and file descriptor; the two are one and the same in java. This applies to all types of socket.

Implementing shutdown will be discussed below under the different socket types

1. TCP client sockets are fine: java.net.Socket objects have the shutdownInput and shutdownOutput methods, which shut down the receive stream and the transmit stream respectively.
2. TCP server sockets are different: they don’t have transmit and receive streams: they exist only to accept incoming socket connections. So when a TCP server socket is shutdown, the result of the call should be to close the listen queue for the socket, and discard all queued incoming connections. In java, server sockets do not have a shutdown method (as you can see from their javadocs: java.net.ServerSocket and java.nio.channels.ServerSocketChannels: remember, both classes are required to fully implement all cpython socket semantics in jython). So, how to implement the shutdown for TCP server sockets? In java, the same effect is achieved is issuing the close method. So the choice is whether or not to make shutdown call close? Since production code that uses the shutdown method will also call the close method immediately, or soon afterwards, that would make that series of calls fail. Therefore, the right choice (IMHO) is to have the shutdown method as a no-op, i.e. do nothing, and document the fact that the user must call close on the socket in the jython socket module documentation.
3. UDP sockets, similarly don’t have input and output streams; calling shutdown on the socket should stop the acceptance of incoming packets. But in java, neither java.net.DatagramSockets nor java.nio.channels.DatagramSocketChannels have shutdown methods; instead the same effect is achieved in by calling the close method. So, the right choice for the shutdown of UDP sockets is to make it a no-op, and document that fact.

I have checked in an implementation of the above into the jython SVN; in the release 2.2 maintenance branch at revision 6000 and into trunk at revision 6001. I have put together this page to record my reasoning for implementing things this way, and the research that I’ve done in trying to arrive at the right implementation. Or at least, an implementation that is as right as possible for the jython programmer.

On a related note, I see that the good people over in Twisted Matrix are making great progress with getting twisted running on jython. It will be fantastic to see one of the premier python asynchronous frameworks working on jython!

Lastly, thanks to Glyph Lefkowitz of twisted for reporting this situation in the jython bug tracker: listening socket shutdown expects the wrong kind of socket.

Cpython excels in a very specific area; asynchronous (aka non-blocking) network servers. Back in the days before multi-threading was invented, asynchronous designs were the only available mechanism for managing more than one connection in a single process. Although it was possible to spawn off new processes to service incoming requests, that made communicating and sharing information and resources (e.g. database connections) between server components more complex and intractable.

With an asynchronous design, all of the incoming socket connections are managed by a single process. Current socket connections are kept in a simple data structure, such as a list, along with state information relating to the connection, and perhaps a handler, i.e. a piece of code that services the incoming requests. The single process used the unix select call (or its descendants such as poll) to monitor the state of every connection simultaneously, and then invoking the associated handlers when a network event of interest to them occurred (i.e. following a reactor pattern). And therein lies the problem.

When the asynch server calls the handler to service a request, that handler cannot delay before it returns; it must return very quickly, or it holds up the entire server. Returning quickly is easy if you’re doing trivial processing, e.g. an echo or chat server. But if you need to connect to a database, or even do something as simple as a DNS lookup, that requires forming another network connection, sending a request packet and waiting for a response. Which means that if your database or DNS library waits until the response arrives, hundreds of milliseconds or even seconds later, then the entire network server is held up, and clients must wait possibly seconds for service; clearly unacceptable. So with asynchronous servers, you must always use libraries that are aware they are operating in an asynchronous environment, are able to surrender control while they are awaiting a network response, and can add themselves to the server reactor, so that they can be notified when their response arrives.

While asynchronous architectures thrived in many areas, they proved to be overly complex for the mainstream programming market. Making all libraries asynch-aware, and tracking all of the interactions between them, was complex, difficult to understand, and thus error-prone. Multi-threading was invented to circumvent these problems. Instead of a single thread of execution controlling network service, separate threads of execution could be created, giving the illusion that there were multiple copies of the server code executing simultaneously, inside the same process, sharing memory, etc. Actually all the threads were running on the same linear processor, and the available timeslices were divided between them, in much the same way that most modern operating systems timeslice a single processor between multiple processes. The threads would generally run the same instructions, but would have their own program counter and call stack. Threads made programmers lives much easier, since threads could be designed to execute in a linear fashion. If the thread needed to pause at any stage, e.g. to await the response to a network request, it simply suspended itself, and a different thread would be selected to be given CPU time. At low cost.

Well, not quite.

There are problem with threads. Threads can have very large memory overheads, perhaps measuring in megabytes. Threads must synchronised, so that they don’t corrupt shared data structures, e.g. race conditions, which can be very hard to recognise when they happen, and complex to avoid in design. And threads can deadlock, which can be enormously difficult to debug.

The overhead of threads is such that it is rare to see a threading-based server outperform a well designed asynchronous server, on identical hardware. Threaded servers rarely service more than a couple of thousand network connections simultaneously; many can only service in the hundreds per second. There have been incredible increases in all forms of hardware capacity in recent decades; commodity boxes come with gigahertz processors, gigabytes of memory, terabytes of hard disk, and gigabits of network bandwidth. But although threaded-based servers have vastly improved in design, they still cannot match the performance of asynchronous servers, and address the C10K problem.

The C10K problem is a simple one; how to service 10,000 simultaneous network requests. I refer to you the C10K website for enormously detailed technical information on this complex problem. Suffice it to say that asynchronous architectures, with their much smaller memory usage, and lack of need for locking, synchronisation and context-switching, are generally considered to be far more performant than threaded architectures.

So where does python come in? It so happens that python is an excellent language for writing asynchronous servers. Python’s expressiveness and conciseness make it an excellent choice for developing simple and elegant solutions to the problems posed by asynchronous designs. Python was first published in 1991, years before java, and did not develop multi-threading until much later; python’s threading design borrows much from java’s design. Before threading came to python, asynchronous was the design of choice; none more so than Sam Rushing’s medusa, which is still considered the archetypal asychronous design, and was adapted into python as the asyncore module.

But asyncore is basic, and doesn’t provide non-blocking support for the protocols necessary in a real-world application; database protocols, DNS lookups, etc. But there are two heavyweights in the python asynchronous world that have the required support, in a robust form. Zope Corporation was there first with their venerable Zope product, arguably the grand-daddy of all python web frameworks. But dissatisfaction with Zope’s complexity lead to a new initiative; the Twisted Matrix. I won’t try to introduce Twisted here; take a look at the names of the sponsors on the Twisted website to see how important a framework it is.

And that’s why I’m excited; Twisted could soon be running on jython!

Back in the old days, jython 2.1 could not do aysnchronous socket operations. Jython 2.1 was written in the days when the only socket support in java was java.net, which was threading oriented. It was only in version 1.4 of the JVM that asynchronous support arrived, in the shape of the java.nio package. Now java has robust asynchronous support, after several years in the field.

I saw the possibility of using java.nio to enable jython to do asynchronous sockets a couple of years ago. I developed the support, and checked it into jython 2.2 last year, in the hope that it would draw the attention of developers of the big cpython asynchronous frameworks. Java has some distinct advantages over cpython in high performance network serving world, with the most obvious being the ability to run on all cores of multi-core processors simultaneously. Cpython is restricted in this regard by it’s Global Interpreter Lock, which prevents multiple threads running pure python code from running on multiple cores or processors simultanously. In java, and thus in jython, every single core in the multi-core system can be running its own reactor, actually simultaneously.

It’s looking more like those cpython asynchronous frameworks could be coming to jython soon.

The founder and chief architect of Twisted, Glyph Lefkowitz, logged three bugs (1119, 1120, 1121) against the jython socket module last week; I fixed them yesterday. I’m glad to say that they were all relating to corner cases and unusual usage; so far there have been no reports of serious bugs in the main functionality of the socket module. So hopefully the road to running twisted on jython is clear and obstacle free, at least at the level of socket communications.

And the Zope people have an ongoing project to get Zope running on jython; see the Zope-dev archives for ongoing updates.

Yes, exciting times indeed!

If you are interested in reading further about asynchronous I/O in the java.nio package, I thoroughly recommend Ron Hitchens book Java NIO.

Although these notes are now out-of-date, having been surpassed by the actual implementation itself, I am publishing them here for historical purposes. The notes are broken down into four main areas.

1. Overview
2. Socket module
3. Select module
4. Asyncore module

For documentation on how to use the jython’s asynchronous socket I/O, see the documentation for the socket, select, asyncore, and asynchat modules.

Introduction

The purpose of this document is to discuss the implementation of socket timeouts and asynchronous socket I/O processing in jython.

In versions of the java language prior to 1.4, java had no built in support for non-blocking I/O. This applied to all forms of I/O, including files, sockets, pipes, etc. This has meant that all I/O involved the use of blocking calls, which consequently required the use of threads. While threads are a useful abstraction for programmers that permits the processing of multiple requests simultaneously, this abstraction comes at a high cost, in terms of resource consumption. High consumption of resources leads to fundamental limits on the number of requests that can be processed at a time, which means that thread-based architectures can scale badly, and perhaps fail to take advantage of the capabilities of modern PC hardware. For a more detailed discussion of this topic, read about the C10K problem. For more information about processing sockets in an asynchronous fashion, read this tutorial on Asynchronous Socket Programming.

In contrast, cpython has had inbuilt support for non-blocking I/O for a long time, based on the C/unix select call, which allows the programmer to examine the readiness state of multiple file descriptors (the unix abstraction which represents all I/O channels). This non-blocking I/O support has enabled cpython to support development of server and client architectures that do not suffer from the limitations of threads, and to process large numbers of requests in a highly stable fashion. Among the cpython frameworks based on non-blocking I/O are

• Twisted
• Medusa
• Asyncore (library module)

Prior to version 1.4, java did not provide support for non-blocking socket I/O, therefore it was not possible to provide such support in jython. In version 1.4, java evolved the capability of using I/O channels in a non-blocking manner. This means that it is now possible to implement non-blocking I/O in jython, in a manner that is compatible with cpython. The purpose of these documents is to discuss the implementation of such facilities.

Also, since version 2.3, cpython has had support for socket timeouts. However, support does not currently exist in jython for socket timeouts, since at the time that the existing jython module was written (version 2.1), timeouts were not a part of the standard interface of sockets. The java platform has always had support for socket timeouts, even in version prior to java 1.4. If modifications are to made to the existing jython socket module to support non-blocking I/O, now is the ideal opportunity to update the socket module to support timeouts as well. As will be discussed, there is a fundamental relationship between non-blocking socket I/O and socket timeouts, in the cpython model at least.

Goals for this implementation project

The following are goals for this implementation of non-blocking I/O in jython.

1. Cpython compatibility. The primary requirement is that the developed software be interface-compatible with the cpython library modules which provide socket support. This so that the existing large volume of cpython code which uses sockets can be executed in jython with no modification.
2. Thread-safe. The developed software must be thread-safe, i.e. as far as is possible, accessing objects (created through the software) from multiple threads simultaneously must result in predictable behaviour and no corruption of data.
3. Non-blocking TCP socket support. The developed software should support nonblocking access to both client and server TCP sockets. This applies to all operations, including opening and closing connections to socket endpoints, reading and writing data, and detection of out-of-band data.
4. Non-blocking UDP socket support. Ideally, non-blocking operations should be supported on UDP/datagram sockets.
5. Socket timeout support. In cpython 2.3, socket objects gained two new methods: the settimeout and setblocking methods. Although the language features to implement these capabilities for jython sockets have always been available on the Java platform, the current jython socket implementation does not support thse methods (since they were not a standard part of the cpython socket API when the jython module was first written). Although the primary goals of this project are to support nonblocking I/O, it would also be desirable to implement these methods for all versions of java prior to 1.4, so that jythonistas can at least have an API which is as compatible as possible with cpython 2.3, even if they are using a pre1.4 JVM.

The following are not goals of this project.

1. Non-blocking file operation support. Ideally, in order to support the development of high-throughput and robust server architectures, the developed software should provide support for non-blocking operations on files and directories.
2. Non-blocking pipe operation support. Ideally, the developed software should provide support for non-blocking operations on pipe, i.e. communications channels between OS processes.
3. Non-blocking generic I/O support. Ideally, the developed software should provide support for non-blocking operations on any form of I/O channel, i.e. any communications channel that supports transmission and receipt of a stream of bytes.

However, it is currently not possible to provide support for these desirable features, in a platform independent fashion, since java 1.4 does not support non-blocking operations on I/O channels other than sockets. While it is possible to provide support in a platform-dependent fashion, using JNI, such an implementation is outside the scope of this project.

Java vs. jython

There are two choices for the language in which this software can be implemented.

It is proposed to implement this software in jython.

Although these notes are now out-of-date, having been surpassed by the actual implementation itself, I am publishing them here for historical purposes. The notes are broken down into four main areas.

1. Overview
2. Socket module
3. Select module
4. Asyncore module

For documentation on how to use the jython’s asynchronous socket I/O, see the documentation for the socket, select, asyncore, and asynchat modules.

Modifications to the existing jython socket module

There are a number of modifications that would need to be made to the existing jython socket implementation in order to facilitate support for timeouts and for non-blocking operations. These modifications are discussed in this document.

Socket objects vs. SocketChannel objects

It is required to provide a facility in jython which permits the programmer to “watch” the readiness status of multiple I/O channels. In cpython, file descriptors are the handles which are used to represent watchable channels. A typical code sequence might look like this

s = socket.socket(AF_INET, SOCK_STREAM)
fd = s.fileno()
po = select.poll()
po.register(fd)

However, the concept of a file descriptor has no meaning on the java platform, since the JVM does not use file descriptors (they are too platform specific). Instead, in a jython implementation, it will be necessary to obtain a java.nio.channels.SelectableChannel representing the channel to be watched.

Fortunately, all socket objects in the java.net package have a getChannel() method (as of java 1.4 anyway).

Unfortunately, this method returns a null value when used with a socket created by the constructors java.net.Socket, java.net.ServerSocket, java.net.DatagramSocket. The only time when java.net.*Socket.getChannel() returns a SelectableChannel is when the socket itself was created through the java.nio.channels package. In all cases, this is done by calling a static method of the relevant class. The creation methods for the different channel types are

This restriction means that all sockets that are to be processed using this proposed non-blocking socket I/O API must be created through the java.nio construction method outlined above.

However, it is not simply of case of switching over to the new methods for all socket creation, since it is hoped to also support as many operations as possible on JVMs prior to version 1.4, e.g. timeouts. Therefore, it is necessary to separate out socket creation operations to a single set of factory methods or functions, which can be altered depending on the runtime environment in which they are run. The following is one proposed code sequence for creating socket factory functions, which should work on all JVMs. Another possible approach might be to create a factory class which dynamically modifies its behaviour.

try:
    import java.nio.channels
    print "using java.nio"
 
    def _createclientsock():
        return java.nio.channels.SocketChannel.open().socket()
 
    def _createserversock():
        return java.nio.channels.ServerSocketChannel.open().socket()
 
    def _createdatagramsock():
        return java.nio.channels.DatagramChannel.open().socket()
 
except ImportError:
    print "using java.net"
 
    def _createclientsock():
        return java.net.Socket()
 
    def _createserversock():
        return java.net.ServerSocket()
 
    def _createdatagramsock():
        return java.net.DatagramSocket()

Note that it should be sufficient to return simple java.net socket objects from these functions, because

1. It requires less code modification to the existing jython socket module: the existing code is designed to work with java.net.*Socket objects.
2. In the case of 1.4 JVMs, where support for non-blocking operations is provided, the SelectableChannel corresponding to a socket can always be retrieved from the socket’s getChannel() method.
3. In the case of pre-1.4 JVMs, which do not support nonblocking I/O, calls to the getChannel() method will fail. However, non-blocking support is not provided for pre-1.4 JVMs.

In summary

1. Sockets should be created using the java.nio APIs where possible
2. Sockets should be created using the java.et APIs if java.nio is not available
3. Both these factory methods should return objects which implement the same interface, i.e. the interface presented by socket objects in the java.net package.
4. When a java.nio.channels.SelectableChannel is required, it can be retrieved from the socket using the the getChannel() method.

Socket creation in existing jython socket module

The existing jython socket module constructs all sockets by using constructors from the java.net package. However, as discussed above, if a socket channel is to be watchable, a java.nio.channels.SelectableChannel object is required. Thus, the existing jython socket module will have to be modified to use the the factory approach outlined above, which uses java.nio where possible, and java.net where not. The only parts of the socket module that should require modification are the parts that actually create sockets.

For example, the following is the current code for the connect method of socket objects

def connect(self, addr, port=None):
    "This signifies a client socket"
     if port is not None:
         addr = (addr, port)
     assert not self.sock
     host, port = addr
     if host == "":
         host = java.net.InetAddress.getLocalHost()
     self._setup(java.net.Socket(host, port))

Which could be replaced with code similar to the following

def connect(self, addr, port=None):
    "This signifies a client socket"
     if port is not None:
         addr = (addr, port)
     assert not self.sock
     host, port = addr
     if host == "":
         host = java.net.InetAddress.getLocalHost()
     sock = _createclientsocket()
     self._setup(sock)
     self.sock.connect(java.net.InetSocketAddress(host, port))

Note that this code is not yet sufficient: there is still timeout and blocking configuration to be taken into account. See below under Implementing the cpython 2.3 blocking/timeout model.

Types of channels that can be examined

In cpython, when a channel is to be watched, the file descriptor representing the channel is registered with a poll object. However, whether or not the channel is watchable is determined by the operating system, and is thus platform independent. This model fits very well with cpython’s late-binding ethos.

In contrast, java has a very precise object model which differentiates watchable channels from other channel types by having watchable channel types extend the abstract class java.nio.channels.SelectableChannel. If a java object is not a subclass of this abstract class, it cannot be “watched”.

This means that a mechanism is required for obtaining the underlying SelectableChannel from any given socket, through a public method, preferably re-using a known and comparable method from the cpython 2.3 API.

It is proposed to use the (currently unimplemented in jython) fileno() method to enable the programmer to obtain a SelectableChannel object which can be passed to poll objects. The fileno() method is the closest analogy to a SelectableChannel in the cpython model, and its return value is most frequently used as a SelectableChannel would be. However, since the two concepts are different, it is proposed to create two separate methods with the same interface. Thus, the fileno method for sockets could be defined as follows in the jython socket module.

class _tcpsocket:
 [....]
    def getchannel(self):
        return self.sock.getChannel()
 
    fileno = getchannel

The getchannel() method could be used internally to the new jython socket module, since it has inherent knowledge that the returned value is not a file descriptor but a SelectableChannel.

A similar method would be required for the _udpsocket class.

Implementing the cpython 2.3 blocking/timeout model

The following list of cpython socket methods (as of cpython 2.3) are currently not available on jython socket objects, mostly because they are to do with non-blocking I/O or timeouts.

In the cpython socket model, the above top two methods are closely related. The cpython module reference for the socket module says the following

Some notes on socket blocking and timeouts: A socket object can be in one of three modes: blocking, non-blocking, or timeout. Sockets are always created in blocking mode. In blocking mode, operations block until complete. In non-blocking mode, operations fail (with an error that is unfortunately system-dependent) if they cannot be completed immediately. In timeout mode, operations fail if they cannot be completed within the timeout specified for the socket. The setblocking() method is simply a shorthand for certain settimeout() calls.

Timeout mode internally sets the socket in non-blocking mode. The blocking and timeout modes are shared between file descriptors and socket objects that refer to the same network endpoint. A consequence of this is that file objects returned by the makefile() method should only be used when the socket is in blocking mode; in timeout or non-blocking mode file operations that cannot be completed immediately will fail.

The following algorithms for a jython implementation of the above methods could be proposed, in order to reflect the same semantics as the cpython API.

    def settimeout(self, timeout):
        if timeout is None:
            self.setblocking(1)
        else:
            millis = int(timeout * 1000)
            if millis == 0:
                self.setblocking(0)
            else:
                self.sock.setSoTimeout(millis)
 
    def setblocking(self, flag):
        try:
            self.getchannel().configureBlocking(flag)
        except:
            raise JynioException('Channel cannot be configured for blocking')

However these naive implementations cannot be used in practice, because of the deferred creation of socket implementation objects. This deferred creation of socket implementation objects means that the actual underlying implementation socket may not exist when the settimeout() and setblocking() methods are called. Therefore the socket configuration information must be stored locally on the jython socket object, for use in configuring the socket after it’s deferred creation.

Since the goal of this project is cpython 2.3 compatibility, it is proposed that the three explicit modes mentioned in the cpython documenation be adopted as allowable states of jython socket objects. These modes are blocking, non-blocking, timeout, and could be represented as constants as follows.

MODE_BLOCKING    = 'block'
MODE_NONBLOCKING = 'nonblock'
MODE_TIMEOUT     = 'timeout'

Also, there should be a permitted set of states for any given socket. Whether or not a socket is in one of the permitted states can be checked by assertions.

_permittedstates = (MODE_BLOCKING, MODE_NONBLOCKING, MODE_TIMEOUT)

Note, however, that compatibility with cpython 2.3 on JVM platforms prior to 1.4 is also a goal. On such JVMs there are only two permissible modes of operation: blocking and timeout: non-blocking operation is not supported. Therefore, the code above would have to be written as

try:
    import java.nio.channels
    _permittedmodes = (MODE_BLOCKING, MODE_NONBLOCKING, MODE_TIMEOUT)
except ImportError:
    _permittedmodes = (MODE_BLOCKING, MODE_TIMEOUT)

The definition of the above methods then becomes (including required modifications to other functions/methods).

def socket(family, type, flags=0):
    [.....]
    self.blockmode = MODE_BLOCKING
    self.timeout = 0
    [.....]
 
 
class _tcpsocket:
 
    def _config(self):
        assert self.blockmode in _permittedmodes
        if not self.sock: return
        if self.blockmode == MODE_BLOCKING:
            self.sock.setSoTimeout(0)
        if self.blockmode == MODE_NONBLOCKING:
            self.sock.getchannel().configureBlocking(0)
        if self.blockmode == MODE_TIMEOUT:
            self.sock.setSoTimeout(int(self.timeout*1000))
 
    def settimeout(self, timeout):
        if timeout is None:
            self.blockmode = MODE_BLOCKING
            self.timeout = None
        elif int(timeout) == 0:
            self.blockmode = MODE_NONBLOCKING
            self.timeout = 0
        else:
            self.blockmode = MODE_TIMEOUT
            self.timeout = timeout
        self._config()
 
    def setblocking(self, flag):
        if flag:
            self.blockmode = MODE_BLOCKING
            self.timeout = 0
        else:
            self.blockmode = MODE_NONBLOCKING
            self.timeout = 0
        self._config()

Note the introduction of the _config() method, which will be required on the _tcpsocket and _udpsocket classes. When and where this method should be used is discussed below.

Deferred creation of socket implementation objects

In cpython, after a socket object has been created, it can be used as either a server or a client socket. However, on the java platform, this “late-binding” on the socket implementation object itself cannot be used, because server and client socket objects are implemented through separate classes on the JVM.

The current jython socket module defers the creation of socket objects until it is known for what purpose the socket will be used. For example, when the connect() method is called on a socket object, it is then known that this is to be a client socket.

All such methods that determine the final server/client/datagram nature of a socket (i.e. that both create and configure sockets), must be modified to take the new timout and blocking configuration options into account. This can be done through the _config() method discussed in the previous section. The sequence of operations should then be

1. Create the socket
2. Configure the socket for timeouts, blocking, etc
3. Carry out the desired operation on the socket (e.g. accept, connect, etc)

Taking the above definition of the socket.connect() method, and modifying it to support blocking configuration gives the following code.

    def connect(self, addr, port=None):
        "This signifies a client socket"
        if port is not None:
            addr = (addr, port)
        assert not self.sock
        host, port = addr
        if host == "":
            host = java.net.InetAddress.getLocalHost()
        sock = _createclientsock()
        self._setup(sock)
        self._config() # Configure timeouts, etc, now that the socket exists
        self.sock.connect(java.net.InetSocketAddress(host, port))

The following is a typical expected call sequence for using sockets with timeouts.

from socket import *
 
s = socket(AF_INT, SOCK_STREAM)
s.settimeout(1.0)
s.connect( ('www.python.org', 80) )

Socket methods that would require similar modification to the connect() method above are

1. _tcpsocket.accept()
2. _tcpsocket.listen()
3. _udpsocket.bind()
4. _udpsocket.connect()
5. _udpsocket.sendto()

Exception compatibility with cpython.

It is desirable that the proposed new jython socket module present the same “exceptions interface” as the cpython 2.3 socket module. This is currently not the case with the existing jython socket module. Consider the following two logs of interactive sessions with socket, one on cpython 2.3 and the other on jython 2.1.

Python 2.3 (#46, Jul 29 2003, 18:54:32) [MSC v.1200 32 bit (Intel)] on win32
Type "help", "copyright", "credits" or "license" for more information.
>>> from socket import *
>>> s = socket(AF_INET, SOCK_STREAM)
>>> s.connect( ('anamethatdoesnotexist', 80) )
Traceback (most recent call last):
  File "<stdin>", line 1, in ?
  File "<string>", line 1, in connect
socket.gaierror: (4, 'getaddrinfo failed')

And

Jython 2.1 on java1.4.2 (JIT: null)
Type "copyright", "credits" or "license" for more information.
>>> from socket import *
>>> s = socket(AF_INET, SOCK_STREAM)
>>> s.connect( ('anamethatdoesnotexist', 80) )
Traceback (innermost last):
  File "<console>", line 1, in ?
  File "C:\jython21\Lib\socket.py", line 135, in connect
java.net.UnknownHostException: anamethatdoesnotexist
        at java.net.PlainSocketImpl.connect(PlainSocketImpl.java:153)
        [.......]
        at org.python.util.jython.main(jython.java)
 
java.net.UnknownHostException: java.net.UnknownHostException: anamethatdoesnotexist

This difference between exceptions reported on the different platforms makes it more difficult to write robust portable code, and can lead to unnecessary increased code density. It is desirable that the jython socket module generate the same exceptions as the cpython 2.3 module, to make the programmers job more straightforward.

However, this is non-trivial task. There is a very wide variety of socket exceptions that can be reported, reflecting the wide varieties of errors or problems that can be encountered with sockets, especially in relation to resource usage and other physical considerations. Also, sometimes the same exception differs in meaning subtly between platforms.

Another point is that although it may not be trivial to report the same exceptions as cpython, the following question should be asked: Is it correct to raise Java platform exceptions from socket methods?

To be discussed. I know this is not a trivial problem.

Although these notes are now out-of-date, having been surpassed by the actual implementation itself, I am publishing them here for historical purposes. The notes are broken down into four main areas.

1. Overview
2. Socket module
3. Select module
4. Asyncore module

For documentation on how to use the jython’s asynchronous socket I/O, see the documentation for the socket, select, asyncore, and asynchat modules.

Implementing the select function and poll objects

The purpose of this document is to discuss implementation strategies for a jython implementation of the cpython select module. In cpython, the select module provides two different methods for simultaneously examining the readiness status of a set of I/O channels.

1. The select function, which is derived from the original Unix select call, and takes as parameters three lists of file descriptors:
   1. a list containing file descriptors which may be readable
   2. a list containing file descriptors which may be writable
   3. a list containing file descriptors which may have out-of-band(OOB) data

   When the select function is called, it reads through each of these lists, and prepares its own internal lists of file descriptors which are to be “selected”. It then examines the readiness of the file descriptors in this internal list, and returns three lists which are subsets of the three lists passed in as parameters.

2. Poll objects, which are object-oriented descendants of the select function. In order to examine the readiness status of multiple file descriptors, the programmer creates a poll object. File descriptors are explicitly registered with the poll object. These descriptors are checked every time the poll objects poll() method is called, until the file descriptor is explicitly unregistered.

As mentioned on the cpython Poll objects documentation page, poll objects are superior to the select function call, since they only require listing the file descriptors of interest, while select() builds a bitmap, turns on bits for the fds of interest, and then afterward the whole bitmap has to be linearly scanned again. This means that performance of poll objects should be better than the select function.

Although poll objects may be superior, the select function call is still supported in cpython, for the following reasons.

1. Historic. There is a substantial body of code written in cpython which uses the select function.
2. Windows. Windows does not support poll objects (Windows has it’s own equivalent API call).
3. Unix. Although most modern unices support poll objects, there are still some variants that do not.

As discussed below, cpython poll objects exhibit a very similar model to java.nio.channels.Selector objects, and thus it is natural to implement one using the other. Once poll objects have been implemented, a jython implementation of the select function can be layered on top of them.

Implementing poll objects with java Selector objects

A likely approach to implementing cpython poll objects in jython is to implement them using java Selector objects.

The following are similarities between cpython select.poll objects and java.nio.channels.Selector objects.

1. Both are single objects which can “watch” multiple I/O channels at once.
2. Both monitor a set of I/O channels which have been explicitly registered with the object.
3. Both return a set of “keys” which indicate which channels are ready for I/O. In case of cpython, this is in the form of a list of tuples giving (file descriptor, event mask). In java’s case, this is in the form of a set of java.nio.channels.SelectionKeys, which contain an event mask (or in java terminology, a set of interestOps()).
4. Both objects support the concept of a timeout, i.e. that the method call which watches the set of registered channels can timeout after a user specified time.
5. Both objects support the concept of taking a “snapshot view”, i.e. a zero-length timeout.
6. Both objects support the concept of waiting indefinitely for some readiness notification to appear.

The important differences are as follows

1. Java Selector objects have clearly defined semantics when a single selector object is operated from multiple threads. In contrast, the documentation for cpython poll objects makes no guarantees (or even statements) at all about access to poll objects from multiple threads (presumably this is related to the fact that cpython has a Global Interpreter Lock (GIL) which prevents more than one thread from executing python at any given time. See below under Threading for more information).
2. Java SelectionKey objects permit the attachment of application objects, meaning that the programmer can attach a handler object to each channel, and which might be rsponsible for handling all I/O on the channel. Note however that although this facility is useful when writing application frameworks, it is unlikely to be useful in the case of implementing a cpython compatible select module, since cpython poll objects do not support the “attachment” of application objects to I/O channels to be watched. However, the asyncore module may be an ideal place to exploit this feature.

Threading and the cpython Global Interpreter Lock

TBD: Need to understand possible use-cases for calling poll objects from multiple threads.

If you have come across a need to call poll objects from multiple threads, I’d like to hear about it.

Registering and unregistering channels

The cpython documentation states that when a channel is to be registered, the parameter passed can be either of two object types:-

1. The channels file descriptor
2. An object which has a fileno() method which returns a file descriptor.

In the jython implementation of poll objects, a SelectableChannel object is required. Therefore, it is proposed that in jython the same model as cpython be adopted, with the term file descriptor replaced by the term SelectableChannel.

If an object is registered which is an instance of java.nio.channels.SelectableChannel or any of subclasses, then that object represents the channel which is to be watched.

If the object is not such an instance, then the objects fileno() method should be called, to attempt retrieve a SelectableChannel. If the method does not exist, then the object is not watchable, and an exception should be raised. If the method returns an object, but that object is not a SelectableChannel, the channel is unwatchable and an exception should be raised. If the method returns an object and that object is a SelectableChannel, then that object is the channel to be watched.

Suggested code for this purpose is

import java.nio.channels
 
class poll:
 
    def _getselectable(self, channel):
        if isinstance(channel, java.nio.channels.SelectableChannel):
            return channel
        else:
            if hasattr(channel, 'fileno') and callable(getattr(channel, 'fileno')):
                result = getattr(channel, 'fileno')()
                if isinstance(result, java.nio.channels.SelectableChannel):
                    return result
                else:
                    raise JynioException('Channel '%s' is not a watchable channel' % channel)
            else:
                raise JynioException('Channel '%s' is not a watchable channel' % channel)

A typical call sequence using the register function is given here. Note that this code should work in both cpython and jython.

import select
from socket import *
 
pobj = select.poll()
s = socket(AF_INET, SOCK_STREAM)
s.setblocking(0)
s.connect( ('www.python.org', 80) )
pobj.register(s, select.POLLIN | select.POLLOUT)
readychans = pobj.poll()

Internal data of the poll object

The poll object needs to keep track of the channels which it is watching. In java, java.nio.channels.Selector objects are used to watch multiple channels. Therefore, it is proposed to have a Selector as an instance variable of every poll object, against which all channels can be registered. The Selector should be created at __init__ time of the poll object, like so.

import java.nio.channels
 
class poll:
 
    def __init__(self):
        [....]
        self.selector = java.nio.channels.Selector.open()
        [....]

In the cpython model, a channel is registered with a watcher, whereas in java the channel registers itself with the watcher, returning a SelectionKey representing the registration. This means that when a Selector returns a set of channels that are ready for I/O operations, it will return a set of SelectionKeys. But we need to return the original object back to the programmer that they passed in. So we need a mechanism for mapping SelectionKeys back to original parameters.

When a SelectionKey is returned from a Selector, the channel corresponding to that key can be obtained through the channel() method. Further, since we know that that channel represents a socket, we can retrieve the users original socket through the socket() method. However, if we do not keep track of the users original object, then we cannot know from the SelectionKey which object the user passed in. Therefore, we need to keep track of the original object the user passed into the function. This could be done with a simple dictionary which is internal to the jython poll object. The key for the dictionary would be the SelectableChannel corresponding to the channel.

When a channel is unregistered with a poll object, the channel should no longer be watched. The java model, however, is slightly different than what might be expected (surprise!): instead of a watcher unregistering a watchable channel, the key representing the registration of a watchable channel with a watcher must be cancelled! Therefore, it will be necessary to keep track of all SelectionKeys generated by the Selectable/Selector/registration process, so that they can be cancelled later.

It is proposed to store this information in a simple python dictionary which is internal to the jython poll object. The key for the dictionary would be the SelectableChannel corresponding to the channel. The values in the dictionary should contain the following.

1. userobject, i.e. the object which the user passed into the registration function, and which should be returned to them when the channel is ready for I/O.
2. SelectionKey, i.e. the SelectionKey representing the registration with the internal Selector object. This is so that the registration can be cancelled at a later stage.

This dictionary should created at __init__ time of the poll object, and modified at every channel registration and unregistration. The following are suggested algorithms for the poll object. Note that, according to the cpython 2.3 documentation, it is not an error for a channel to be registered twice with a poll object, but any attempt to unregister a channel that was never registered should result in a KeyError. Note that this code ignores the need for event flags, the implementation of which will be discussed below.

import java.nio.channels
 
class poll:
 
    def __init__(self):
        self.selector = java.nio.channels.Selector.open()
        self.chanmap = {}
 
     def _getselectable(self, userobject):
         # Implementation which seeks a SelectableChannel object given above
 
    def register(self, userobject, flags):
        # Flags ignored for now
        channel = self._getselectable(userobject)
        selectionkey = channel.register(self.selector, flags)
        self.chanmap[channel] = (userobject, selectionkey)
 
    def unregister(self, userobject):
        channel = self._getselectable(userobject)
        self.chanmap[channel][1].cancel()
        del self.chanmap[channel]

Mapping cpython event flags to java interest ops

When a channel is registered with a watcher, the programmer defines a set of events in which they are interested. In cpython, this is done through OR’ing bitmasks containing the following possible values

The following are important to note

1. Cpython does not have an event flag to represent a CONNECT event. Instead, a client socket is known to be connected when it is ready for writing, i.e. a POLLOUT event is generated.
2. Cpython does not have an event flag to represent a ACCEPT event, i.e. that a server socket accept() would not block if called, and would return a new socket. Instead, a server socket is known to be ready to accept when it is ready for reading, i.e. a POLLIN event is generated.
3. Note the above seems only to be documented in the cpython documentation for the asyncore module. It is also interesting to note that the asyncore module has reverse-engineered its own pseudo-events to represent the CONNECT and ACCEPT events.

Java also uses a OR’ed bitmasks of flags to represent the sert of events that is of interest on the channel. Java defines the following constants in the java.nio.channels.SelectionKey object.

Obviously, this presents some difficulties, since there are discrepancies between the event flags that are used by cpython and java. Cpython uses the POLLIN flag to represent two events that are represented by separate flags in java: OP_ACCEPT and OP_READ. Similarly, cpython uses the POLLOUT flag to represent both the java events OP_CONNECT and OP_WRITE. There is no way in cpython to specify the CONNECT or ACCEPT events, but these are required by Java. Conundrum!

A naive solution to this problem might be to attempt to set both java flags as being of interest when the relevant cpython flag is specified. For example, use both event mask OP_READ | OP_ACCEPT when the python mask POLLIN is specified. However, this may result in error, since OP_ACCEPT is only a valid flag on server socket channels: it would probably generate an IllegalArgumentException if used on a client socket (see the documentation for the SelectionKey.interestOps() method for more information. As mentioned on that page, if an event flag is not present in the mask of valid operations on that channel (as determined by the SelectableChannel.validOps() method, then an exception is raised.

Therefore, a proposed solution is to only add these implied java events when they are present in the validOps mask for the channel being registered. Code to carry out this proposed mapping is as follows

from java.nio.channels.SelectionKey import OP_ACCEPT, OP_CONNECT, OP_WRITE, OP_READ
 
POLLIN   = 1
POLLOUT  = 2
POLLPRI  = 4
 
class poll:
 
    def register(self, channel, mask):
        jmask = 0
        if mask & POLLIN:
            # Note that OP_READ is NOT a valid event on server socket channels.
            if channel.validOps() & OP_ACCEPT:
                jmask = OP_ACCEPT
            else:
                jmask = OP_READ
        if mask & POLLOUT:
            jmask |= OP_WRITE
            if channel.validOps() & OP_CONNECT:
                jmask |= OP_CONNECT
        [....]

Note that the absence of the python POLLPRI constant is discussed below.

Combining this code with the code given above, this gives a final definition of the poll object (minus the definition of the poll() method) as follows.

import java.nio.channels
from java.nio.channels.SelectionKey import OP_ACCEPT, OP_CONNECT, OP_WRITE, OP_READ
 
# These values should be checked in the cpython implementation.
 
POLLIN   = 1
POLLOUT  = 2
POLLPRI  = 4
 
class poll:
 
    def __init__(self):
        self.selector = java.nio.channels.Selector()
        self.chanmap = {}
 
     def _getselectable(self, userobject):
         # Implementation which seeks a SelectableChannel object given above
 
    def register(self, userobject, mask):
        jmask = 0
        if mask & POLLIN:
            # Note that OP_READ is NOT a valid event on server socket channels.
            if channel.validOps() & OP_ACCEPT:
                jmask = OP_ACCEPT
            else:
                jmask = OP_READ
        if mask & POLLOUT:
            jmask |= OP_WRITE
            if channel.validOps() & OP_CONNECT:
                jmask |= OP_CONNECT
        channel = self._getselectable(userobject)
        selectionkey = channel.register(self.selector, jmask)
        self.chanmap[channel] = (userobject, selectionkey)
 
    def unregister(self, userobject):
        channel = self._getselectable(userobject)
        self.chanmap[channel][1].cancel()
        del self.chanmap[channel]

An implementation of the poll method

We are now in a position to define the poll() method of poll objects. The return value from this function should be a list of tuples, containing (channel, event mask), where event mask has bits set for all events that occurred on the channel. Since the event mask returned from the internal java.nio.channels.Selector object will possibly contain the extended java events OP_ACCEPT and OP_CONNECT, these should be mapped to the python events POLLOUT and POLLIN respectively.

The cpython poll.poll() method takes a timeout parameter, which means different things depending on its value. Java uses separate methods to represent these different timeout scenarios. The mapping from one to the other is given in this table.

Therefore, different methods of the internal Selector object will have to be called, depending on the timeout value specified.

class poll:
 
    def poll(self, timeout=None):
        if timeout is None or timeout < 0:
            self.selector.select()
        elif timeout == 0:
            self.selector.selectNow()
        else:
            # No multiplication required: both cpython and java use millisecond timeouts
            self.selector.select(timeout)
        selectedkeys = self.selector.selectedKeys() # is this thread-safe?
        results = []
        for k in selectedkeys: # Naive implementation, returned list is actually a java.util.Set
            jmask = k.readyOps()
            pymask = 0
            if jmask &amp; OP_READ: pymask |= POLLIN
            if jmask &amp; OP_WRITE: pymask |= POLLOUT
            if jmask &amp; OP_ACCEPT: pymask |= POLLIN
            if jmask &amp; OP_CONNECT: pymask |= POLLOUT
            # Now return the original userobject, and the return event mask
            # A python 2.2 generator would be sweet here
            results.append( (self.chanmap[k.channel()][0], pymask) )
        return results

How to deal with Out-Of-Band data

In cpython, it is possible to check for the presence of Out-Of-Band data on a channel. Out-of-Band data, also known as priority data or urgent data, is a TCP feature whereby bytes can be sent on a socket which bypass the normal sequencing restrictions imposed on data sent through a socket.

However, although this is a built-in feature of TCP sockets, such out-of-band data is rarely used in actual protocol implementations. Nonetheless, there may be software out there which uses this facility. The readiness status for presence of this data is checked by passing the flag POLLPRI when registering the channel.

Currently, the java.nio non-blocking APIs seem to have minimal support for Out-Of-Band data. There are no events masks with which one can register interest in such priority data. This is confirmed on the documentation page for java.net.Socket.setOOBInline() method, which says: “Note, only limited support is provided for handling incoming urgent data. In particular, no notification of incoming urgent data is provided and there is no capability to distinguish between normal data and urgent data unless provided by a higher level protocol“.

Because of this lack of support for priority/urgent data on the java platform, it is proposed that this form of processing not be supported in this module. If the programmer requires the use of urgent data with jython, i.e. on the java platform, then they will probably be sophisticated enough to bypass this implementation of the select module in jython, and go direct to the java API. A consequent question is whether POLLPRI flags should simply be ignored when used, or should raise an UnsupportedOperation exception.

If this is deemed to be an unacceptable compromise, then I have no solution to propose for the problem.

Implementing the select function using poll objects.

Now that we have finished the implementation of poll objects, we can use them to implement the select function, also in the cpython select module.

The only complexity is that the select function takes separate lists for channels that are to be examined for read and write events. It might be required that the user wants to watch a channel for both read and write events, so a given channel might be present in both lists. This means that if a channel is given in both lists, it must only be registered once with the selector object, using an event mask that checks for both READ and WRITE events.

def select ( read_fd_list, write_fd_list, outofband_fd_list):
	# First create a poll object to do the actual watching.
	pobj = poll()
	# Check the read list
	for fd in read_fd_list:
		mask = POLLIN
		if fd in write_fd_list:
			mask |= POLLOUT
		pobj.register(fd, mask)
	# And now the write list
	for fd in write_fd_list:
		if not fd in read_fd_list: # fds in both have already been registered.
			pobj.register(fd, POLLOUT)
	results = poll.poll()
	# Now start preparing the results
	read_ready_list, write_ready_list, oob_ready_list = [], [], []
	for fd, mask in results:
		if mask & POLLIN:
			read_ready_list.append(fd)
		if mask & POLLOUT:
			write_ready_list.append(fd)
	return read_ready_list, write_ready_list, oob_ready_list

Complete but untested code based on these notes.

The following code should be a complete implementation of the cpython select module, in jython, using java APIs. However, the following are important points

1. Will not work without socket mods. In order for this code to work, a number of modifications would have to be made to the jython socket module. I currently have no plans to make these modifications: I can’t afford the time. Maybe in a few months.
2. Code is completely untested. This code has only been tested for correct syntax. It has never even been run.

Although these notes are now out-of-date, having been surpassed by the actual implementation itself, I am publishing them here for historical purposes. The notes are broken down into four main areas.

1. Overview
2. Socket module
3. Select module
4. Asyncore module

For documentation on how to use the jython’s asynchronous socket I/O, see the documentation for the socket, select, asyncore, and asynchat modules.

Introduction

The purpose of this document is to discuss the implementation of the cpython asycnore module in jython.

The purpose of the asyncore module is to add the last piece of the puzzle in asynchronous processing: the dispatcher. A dispatcher is responsible for watching multiple registered channels. When a readiness event occurs on any channel, the dispatcher calls special events of a handler object associated with each channel.

Important points to note about the existing cpython asyncore module are as follows.

1. It is written pure python.
2. It uses only the interface defined by the cpython select module.
3. It recreates both the ACCEPT and CONNECT events, even though the cpython select module “hides” these events as POLLIN and POLLOUT events.

There are three main strategies that can be adopted for implementing the asyncore module, along with pros and cons. These are listed in the sections below.

Use the existing cpython asyncore module

The simplest and quickest option for providing asyncore support in jython is to use the existing cpython module. The advantages of this approach include

1. No new code need be written
2. Existing code is widely used, and thus well tested.

The disadvantages are

1. Potential for error because of the possibility of different semantics of ACCEPT and CONNECT events on cpython vs. java (on multiple platforms).
2. Mildly inefficient, because of all the mask translation and dictionary lookups
3. Existing code is messy because of varying platform support for the select.select() and select.poll() objects in cpython.

Write a jython specific module, using jython

Another approach is write a jython specific asyncore module, written in jython, but directly using the java.nio APIs. There is quite a close correlation between the models in the cpython asyncore module and java.nio.channels.Selector objects. It is possible to write a more efficient asyncore implemenation by using the java APIs directly. The advantanges of this approach are

1. Can be more robust because of java’s explicit support for ACCEPT and CONNECT events, which can be directly translated to the relevant “dispatcher” events.
2. Can be slightly more efficient, because it avoids a layer of calls to jython implemented poll objects.
3. Asyncore model maps directly onto semantics of a java.nio.channels.Selector (even more than cpython)
4. “Dispatcher” objects can be registered as attached objects to the java.nio.channels.SelectionKeys that represent them. This would make them directly available to the asyncore.loop() function (which would receive a set of java.nio.channels.SelectionKeys, each having the dispatcher as an attachment, which avoids the dictionary lookups involved in poll objects.
5. Can easily be translated to java later on.

The disadvantages are

1. New code needs to be written. Not too much though.
2. Extensive testing will have to be done to ensure that the new module implements the precise contract of the cpython asyncore module.

TBD: Must write sample code for a jython asyncore module.

Write jython specific module, using java

The last major approach is to, as above, write a jython specific module, but in java. However, this is unlikely to the optimal approach, at least in the short term. Advantages include

1. Best possible efficiency

The disadvantages are

1. A lot of hard work!
2. The java/jython object model is likely to change soon.