So I’ve decided to expand the database to encompass the other language that I regularly use, java, and publish a database of open source HTTP proxies written in java.

While carrying out a web development project a few years ago, I needed a HTTP proxy to help with development and debugging. Rather than write my own, I decided to research what open source options were already available.

However, Python is such an easy language to write web servers and proxies in that a lot people had written and puiblished HTTP proxies, so making the decision wasn’t easy. It required a lot of research, which basically meant a code and architectural review of all of the open source python proxies available.

Since most web programmers use a HTTP proxy at some stage, I thought it would be a useful exercise to compile a complete list of the available options, with a comparison table to enable a feature by feature comparison.

The result of that was this comparison table of open source HTTP proxies written in python, which became quite popular, because it saved python programmers going through the same complex comparison and review process I had undertaken.

Since I’m currently working on another proxy-related project, I needed to review available open source HTTP proxies written in java. And I thought I’d save someone some research time by publishing a similar comparison table of open source HTTP proxies in java.

I hope you find it useful.

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.

The support was very basic, because it is an implementation of the existing core cpython ssl socket support, which is really basic, merely allowing a client to make an SSL connection to a server. Cpython has no server-side SSL support in the standard library (although multiple 3rd party modules do support it), and it has no support for certificate management or verification. So basically the cpython ssl support is really only useful for testing; without certificate verification, it’s not really usable in scenarios where authentication actually matters, e.g. E-commerce.

Because the jython socket module is layered on top of java socket libraries, it automatically inherits java behaviour in relation to certificate validation; java by default always validates certificates.

Which is great, if you want certificate validation; it means that you can use the jython ssl support when counterparty authentication actually matters, because it will always verify that the server certificate is valid, and will refuse to form a connection if the certificate is not valid.

However, this is problematic for jython users who want to use the jython ssl support like they would use the cpython ssl support: for testing. In testing phases, it’s very common for users to create and test with their own self-signed certificates; installing real production certificates may be difficult for a number of operational reasons.

As described above, this is not a problem for cpython users. But jython users have to go an extra step in order to be able to use self-signed certificates. There are two choices

1. Add the self signed certificate to the JVM configuration. To do that, read this Sun article on Installing and Configuring SSL Support.
2. Install a custom java Security Provider which simply trusts all certificates. WARNING: Installing a security provider that accepts all certificates leaves you open to all forms of impersonation and other identity-verification failures; only use it for testing purposes! To install a custom security provider requires writing some java. I’ll explain it below.

In order to change the Java trust decision process, you have to create an X509TrustManager. Java TrustManagers are based on an exception model; the trust manager is called to determine if a given client, server or issuer is trusted. If not, the TrustManager should raise a CertificateException. Which means that if a TrustManager wishes to trust everyone, it simply should not raise exceptions when a trust request is made.

But you can’t just create and install a TrustManager; TrustManagers are created by a TrustManagerFactory, so you have to create and install one of those. And in order to do that, you have to create and install a java.security.Provider. Sounds complex?

Well, thankfully it’s not that complex, as you can see in the code sample from this article on the ZXTC KnowledgeHub: Using the Control API with Java. I have reproduced that code here.

 
// Example java.security.Provider implementation
// that trusts ALL SSL certificates
// Regardless of whether they are valid or not
 
// Store this code in a file called MyProvider.java
 
import java.security.Security;
import java.security.KeyStore;
import java.security.Provider;
import java.security.cert.X509Certificate;
import javax.net.ssl.ManagerFactoryParameters;
import javax.net.ssl.TrustManager;
import javax.net.ssl.TrustManagerFactorySpi;
import javax.net.ssl.X509TrustManager;
 
public class MyProvider extends Provider
{
  public MyProvider()
  {
    super("MyProvider", 1.0, "Trust certificates");
    put("TrustManagerFactory.TrustAllCertificates", MyTrustManagerFactory.class.getName());
  }
 
  protected static class MyTrustManagerFactory extends TrustManagerFactorySpi
  {
    public MyTrustManagerFactory()
      {}
    protected void engineInit( KeyStore keystore )
      {}
    protected void engineInit(ManagerFactoryParameters mgrparams )
      {}
    protected TrustManager[] engineGetTrustManagers()
    {
      return new TrustManager[] {new MyX509TrustManager()};
    }
  }
 
  protected static class MyX509TrustManager implements X509TrustManager
  {
    public void checkClientTrusted(X509Certificate[] chain, String authType)
      {}
    public void checkServerTrusted(X509Certificate[] chain, String authType)
      {}
    public X509Certificate[] getAcceptedIssuers()
      { return null; }
  }
 
}

This class should be stored in a file called MyProvider.java, and compiled with javac to generate a MyProvider.class file, which you should place in the classpath.

Once that’s complete, execute the following piece of jython

java.security.Security.addProvider(MyProvider())
java.security.Security.setProperty("ssl.TrustManagerFactory.algorithm", "TrustAllCertificates");

And your code should now start accepting all SSL certificates, regardless of whether they are valid or not.

This issue came up on jython-users, where a jython user was wondering why, after he had installed his own TrustManagerFactory, he could access an HTTPS url on a server with an invalid certificate, without problems, when using java.net.URL.

But when he tried to use jython’s urllib2, it failed with a java.security.cert.CertPathValidatorException. The reason for that is that the jython urllib2 module does not use java.net.URL; it uses the jython socket module directly. So over-riding the default TrustManagerFactory for the javax.net.ssl.HttpsURLConnection class has no effect on anything but instances of the HttpsURLConnection class. Which happens to be the class that java.net.URL uses to make HTTPS connections.

Read the jython-users post HTTPS and invalid certs for more details.

Lastly, this information is reproduced on the Jython Socket Module Wiki page, which I try to keep up-to-date as much as possible.

I wrote a documentation page about the new timeout support, and placed it on xhaus.com. Due to a rearrangement of the xhaus.com website, I am moving that page to this blog.

It should be noted that the timeout functionality has been superceded by the further work that I did to make the socket module support asychronous I/O. So you should refer to the jython socket module documentation to see how to use timeouts. This page appears here solely for historical purposes.

Introduction

Socket timeouts are now included in the jython 2.2 distribution! So the information on this page is now out of date; you should download the latest release of jython instead.

Sockets are the core technology that enable inter-machine communications on the Internet. They generally do a pretty excellent job of communicating information across the globe, and are generally straightforward to use in software. But sometimes networks are saturated or servers are overloaded, which means that code using sockets has to be aware that socket connections can break, or can timeout, meaning that replies were not received from a remote party before a specified time had elapsed.

Writing robust network software can be made much easier when a language supports detection of timeouts on sockets. The purpose of this page is to describe some modifications I’ve made to the standard jython socket module to support socket timeouts.

You can read below about the history of socket timeouts in cpython, java and jython.

How to get the code

To use timeouts, simply

1. Download CVS version 1.16 of the socket.py module.
2. Replace the $jython_home/Lib/socket.py module with the new one just downloaded.

The source was originally made available as a patch against version 1.15 of the socket module.

Documentation

The API implemented should be identical to the cpython 2.3 API, so you should use the cpython 2.3 socket module documentation. In most cases, you should get identical behaviour from the same code run on both platforms. This includes the socket.timeout exception, which is defined as a subclass of the socket.error exception.

However, see below for one important difference between cpython and jython: the treatment of a zero timeout value.

Testing

I have also provided a module of unit-tests for the new timeout functionality. This module is derived mostly from the socket test module from cpython 2.3: I copied a lot of that code, and added a couple of new tests.

The test module is designed to run on both cpython (2.3+ only) and jython, and should ideally give identical results on both platforms. However, there is one of the tests (testTimeoutZero), that will fail on cpython, because of the problem with zero timeouts.

Differences in the treatment of zero timeout values

On cpython, when you specify a zero (i.e. 0 or 0.0) timeout value, the socket should behave the same as if the socket had been placed in non-blocking mode. See the cpython 2.3 socket object documentation for details.

Unfortunately, it is not possible to support non-blocking mode on sockets in java versions prior to 1.4. Moreover, java interprets a zero timeout value as an infinite timeout, i.e. the socket is placed in blocking mode.

To solve this conflict, I decided that the best thing to do with zero timeouts is to adjust them to the smallest possible timeout in java, which is 1 millisecond. So if you do socket.settimeout(0) with this module, what you will really get is equivalent to the cpython call socket.settimeout(0.001).

This means that you may get differing exception signatures when using zero timeouts under cpython and jython.

1. Cpython: socket operations with zero timeouts that fail will raise socket.error exceptions. This is equivalent to a -1 return from the C socket.recv call, with errno set to EAGAIN, meaning "The socket is marked non-blocking and the receive operation would block, or a receive timeout had been set and the timeout expired before data was received."
2. Jython: socket operations with zero timeouts that fail will generate socket.timeout exceptions.

History of socket timeouts in python & java

Timeouts in cpython

A socket timeout API was only introduced in Cpython version 2.3. Prior to that, the only way to implement socket timeouts was to use the select system call, a technique which was used by Tim O Malley’s timeoutsocket.py

Timeouts in java

Java has supported socket timeouts since JDK version 1.1, when the getSoTimeout() and setSoTimeout() methods were added to java.net.Socket objects.

However, Java could not support non-blocking I/O until JVM 1.4, which introduced the java.nio package.

Timeouts in jython

Although Java has been capable of supporting socket timeouts since JDK 1.1, this feature was never added to released versions of jython, since the most recent version of jython released is jython 2.1. Because socket timeouts were only introduced into cpython in version 2.3, there was no cpython 2.1 API for jython 2.1 to copy or implement. The code that I have provided implements the cpython 2.3 socket timeout API.

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.

1. Introduction
2. Can the browser handle GZIPped content?
3. GZIP vs ZLIB
4. Content-encoding vs Transfer-encoding
5. Content-length
6. Character translation on Windows and OS/2
7. OutputStream vs. Writer in jython servlets
8. Some links for related reading
9. Some sample CGI code
10. Some sample code for mod_python
11. Some sample code for jython servlets

Introduction

These are some notes on how to do HTTP compression, i.e. compress content before it is sent to the user. The benefits are

1. You transmit less bandwidth. If the amount of bandwidth you can serve is limited (i.e. you have fixed allocation of X gig/month), then compressing your content before you send it can dramatically lower your transmitted bandwidth.
2. Your client receives less bandwidth, meaning that pages load faster for them. This is particularly important for people using modems. (Although some modems already do compression. I have no idea how efficient modem compression is compared to gzip. See the Links section for a link to an article which discusses HTML compression vs. modem compression.)

Some points to remember

1. Although you save on bandwidth transmitted from your server, it comes at a cost of increased CPU usage on the server.
2. Compressing images probably isn’t worth it. Specialised image compression formats such as GIF, JPEG, and PNG are optimised for the content they carry, and probably cannot be much improved on. So it’s probably not worth compressing images using these techniques.
3. The best bandwidth saving will be achieved on textual files, i.e. mime types like <text/plain>, <text/html>, <text/xml>.

I’m not going to go into the details of the rationale or the mechanisms of compression here, I’m just going to stick to telling you how to do http compression in python. If you want to know about the nuts and bolts of compression and http, I suggest you read

1. RFC2616: Hypertext Transfer Protocol — HTTP/1.1
2. RFC1952: GZIP file format specification version 4.3

Can the browser handle GZIPped content?

Not all browsers can handle compressed content. Old browsers that support HTTP version 0.9 are unlikely to support compressed content. Compression was optional in version 1.0 of the HTTP spec, so only some HTTP 1.0 clients support it, most notably versions 4.x of Netscape Navigator. Support for compression is compulsory in HTTP 1.1, so all HTTP 1.1 clients should support compression. HTTP 1.1 clients include Internet Explorer 5.0 and up. Although I don’t know if Internet Explorer 4.0 is HTTP 1.1 or 1.0, I’m sure IE 4.0 supports gzip compression.

Fortunately, you don’t have to guess or keep a list of which browsers do or do not support compression, since the browsers themselves will inform you of it in their HTTP request. Browsers that support compression will inform you via the HTTP header Accept-Encoding (Check your browser’s headers here). Possible compression methods, as mentioned in RFC2616, include gzip, compress, deflate, and identity. Note that the last one, identity, means no compression. Note also that I’m only going to cover gzip in this document.

So if a browser supports compression, its HTTP request will include a header similar to one of the following

Accept-Encoding: gzip
Accept-Encoding: gzip, deflate

So you need to get the value of the Accept-Encoding header, and check if it contains gzip. If it does, then you can send gzip-compressed content to that browser. Here is some CGI code that checks the content of the header

import string
import os
 
acceptsGzip = 0
try:
    if string.find(os.environ["HTTP_ACCEPT_ENCODING"], "gzip") != -1:
        acceptsGzip = 1
except:
    pass

And here is some mod_python code that checks the content of the header.

import string
 
def acceptsGzip(req):
    """
        Checks if a browser request indicates that the browser will accept
        gzipped content in reply.
    """
    if req.headers_in.has_key('accept-encoding'):
        encodings = req.headers_in['accept-encoding']
        return (string.find(encodings, "gzip") != -1)
    else:
        return 0

And here is some jython servlet code that checks the content of the header.

import string
 
def acceptsGzip(req):
    """
        Checks if a browser request indicates that the browser will accept
        gzipped content in reply.
    """
    encodings = req.getHeader('accept-encoding')
    if encodings != None:
        return (string.find(encodings, "gzip") != -1)
    else:
        return 0

GZIP vs ZLIB

There are a few compression libraries that come with Python. The one which is used in HTTP compression is GZIP. ZLIB, although it is used by GZIP to do part of its job, should not be needed directly in your code.

When a file is compressed for transmission through http, it must be preceded by some special header bytes and followed by some special trailer bytes. Conveniently enough, the python GZIP module constructs exactly those headers and trailers. The details of what those headers and trailers are can be found in RFC1952.

In order to compress using the GZIP module, you’ll need to use code something like this.

import gzip
 
def compressBuf(buf):
    zbuf = cStringIO.StringIO()
    zfile = gzip.GzipFile(mode = 'wb',  fileobj = zbuf, compresslevel = 9)
    zfile.write(buf)
    zfile.close()
    return zbuf.getvalue()

Note that this code compresses into a buffer held in memory, rather than a disk file. This is done through the use of cStringIO.StringIO().

You can vary the compression level by changing the value of the compresslevel parameter, with compresslevel = 9 giving the best compression but consuming the most CPU cycles, and compresslevel = 1 giving the least compression and also consuming the least CPU.

Content-encoding vs Transfer-encoding

When you’re sending compressed content back to the browser, you have to inform the browser of the compression. This is done by the header Content-Encoding. So you should include a header in your response that looks like this.

Content-Encoding: gzip

You don’t need to read any further in this section. The note below about different methods of declaring encoding is just here for interest and completeness.

Note: There is another possible way to communicate the encoding: the Transfer-Encoding header. According to RFC2616, the difference between the two headers is as follows

1. Content-Encoding should be used when the encoding is a property of the content. So if you were serving a static file that is always compressed, then this is the header to use.
2. Transfer-Encoding should be used when the encoding is a property of the message used to transmit the content. So you were sending a static file that is normally uncompressed, and were compressing it just so as to minimise bandwidth during the transmission, then this is the header you should use.

However, RFC2616 is unclear what encoding to use if you are generating dynamic content, which may only be transient in memory and has no lifetime beyond the HTTP request-response pair it was contructed for. In such a situation, an argument could be made for using either Content-Encoding or Transfer-Encoding.

Rather than try to resolve that (potentially unresolvable) issue, I would just like to point out that majority of software "out there" seems to have opted for using Content-Encoding, and that’s the choice that I’ve made as well. You are, of course, free to choose otherwise.

Content-Length

You also need to tell the client browser the length of the compressed content you are sending. This is done by sending a Content-Length header, like this.

Content-Length: xyz

where xyz is the COMPRESSED length of the content.

There seems to be some "folk wisdom" out there on the ‘net that you should send the uncompressed length of the content. This is wrong! RFC2616 is quite clear about this. If you are interested, read sections 7.2.2 Entity-Length and 4.4 Message Length.

As far as I can see, the definitive statement on this matter is at the end of section 4.4 (I have underlined the relevant statement)

When a Content-Length is given in a message where a message-body
is allowed, its field value MUST exactly match the number of OCTETs
in the message-body. HTTP/1.1 user agents MUST notify the user when
an invalid length is received and detected.

Character translation on Windows and OS/2

If you’re working in CGI, and on Windows or on OS/2, you need to be careful about character translation.

As you may be aware, Windows and OS/2 are different from other platforms in the way that they represent an end of line. Whereas most platforms, including *nix, represent line ends as an ASCII linefeed (hex 0×0A, octal 012, python escape string ‘\n’), Windows and OS/2 represent end-of-line as a sequence of two characters, an ASCII carriage return followed by an ASCII linefeed (hex 0×0D 0×0A, octal 015 012, python escape string ‘\r\n’). Therefore, when you print anything in python, or write anything to sys.stdout, using code like this

print "Hello World!"
sys.stdout.write("Hello World!\n")

then both Windows and OS/2 filter the characters, and turn all linefeed characters into a sequence of carriage return followed by linefeed.

This is fine when you’re printing text. But when you’re trying to send binary information, particularly a compressed gzipped file, then this translation will corrupt the binary content, and your transmission of gzip compressed content will fail. Therefore, you have to disable this character translation in order for transmission of gzipped content to work.

When you’re working in CGI, the best way to do this is with the “-u” command line flag to python. This was kindly pointed out by Richie Hindle, who says

…… There is a much simpler way to switch off character translation of the standard
channels. The python interpreter accepts the -u switch to mean “make the
standard channels both unbuffered and binary.” This is tailor-made for
CGI – change your shebang line from “#!…python” to “#!…python -u” and
everything will work without changing your code (and without relying on
platorm-specific modules like msvcrt). Responsiveness may even improve
due to the lack of buffering – and that’s also true on platforms like Unix
which don’t do character translation.

A less convenient method is to execute some platform specific code to disable character translation inside your script. On Windows (MSVC), you should execute some code like this

import msvcrt
import os
import sys
msvcrt.setmode(sys.stdout.fileno(), os.O_BINARY)

I don’t know what the equivalent code is on Windows (CygWin) or OS/2. If anyone does, email it to me, and I’ll include it in this page.

OutputStream vs. Writer in jython servlets.

Under the J2EE Servlet interface, you have a choice of two different ways to output generated content. They are

1. Through an OutputStream (obtained by calling ServletResponse.getOutputStream()). OutputStreams do not carry out character translation on their output.
2. Through a Writer (obtained by calling ServletResponse.getWriter()). Writers carry out character translation on their output, i.e. they will change the value of bytes in the content output by the servlet, to ensure that it meets the character encoding requirements of the client.

Since compressed gzip content is a (dense) binary format, none of the output bytes should be translated. If any bytes are translated, the output may be corrupted and the recipient may be unable to decode it. Therefore, you must output compressed content through a (non-translating) OutputStream object.

Some links for related reading

• W3C: Compression and Performance

Some sample CGI code

So, without further ado, here is some sample CGI code that will transmit compressed HTML to gzip capable browsers.

#! /path/to/python -u
 
import string
import os
import sys
import gzip
import cStringIO
 
def compressBuf(buf):
    zbuf = cStringIO.StringIO()
    zfile = gzip.GzipFile(mode = 'wb',  fileobj = zbuf, compresslevel = 6)
    zfile.write(buf)
    zfile.close()
    return zbuf.getvalue()
 
def testAcceptsGzip():
    acceptsGzip = 0
    try:
        if string.find(os.environ["HTTP_ACCEPT_ENCODING"], "gzip") != -1:
            acceptsGzip = 1
    except:
        pass
    return acceptsGzip
 
def sendHtml(buf):
    sys.stdout.write("Content-type: text/html\r\n")
    if testAcceptsGzip():
        zbuf = compressBuf(buf)
        sys.stdout.write("Content-Encoding: gzip\r\n")
        sys.stdout.write("Content-Length: %d\r\n" % (len(zbuf)))
        sys.stdout.write("\r\n")
        sys.stdout.write(zbuf)
    else:
        sys.stdout.write("\r\n")
        sys.stdout.write(buf)
 
myHtml = """<html><body><h1>hello compressed world!</h1></body></html>"""
sendHtml(myHtml)

Some sample mod python code

And here is some sample mod python code that will transmit compressed HTML to gzip capable browsers.

import string
import os
import sys
import gzip
import cStringIO
from   mod_python import apache
 
def compressBuf(buf):
    zbuf = cStringIO.StringIO()
    zfile = gzip.GzipFile(mode = 'wb',  fileobj = zbuf, compresslevel = 6)
    zfile.write(buf)
    zfile.close()
    return zbuf.getvalue()
 
def testAcceptsGzip(req):
    if req.headers_in.has_key('accept-encoding'):
        encodings = req.headers_in['accept-encoding']
        return (string.find(encodings, "gzip") != -1)
    else:
        return 0
 
def handler(req):
    req.content_type = "text/html"
    myHtml = """<html><body><h1>hello compressed world!</h1></body></html>"""
    if testAcceptsGzip(req):
        zbuf = compressBuf(myHtml)
        req.headers_out['Content-Encoding'] = 'gzip'
        req.headers_out['Content-Length'] = '%d' % (len(zbuf))
        req.send_http_header()
        req.write(zbuf)
    else:
        req.send_http_header()
        req.write(myHtml)
    return apache.OK

Some sample jython servlet code

And here is some sample jython servlet code that will transmit compressed HTML to gzip capable browsers.

import  javax.servlet.http.HttpServlet
 
import  cStringIO
import  gzip
import  string
 
def compressBuf(buf):
    zbuf = cStringIO.StringIO()
    zfile = gzip.GzipFile(mode = 'wb',  fileobj = zbuf, compresslevel = 6)
    zfile.write(buf)
    zfile.close()
    return zbuf.getvalue()
 
def acceptsGzip(req):
    encodings = req.getHeader('accept-encoding')
    if encodings != None:
        return (string.find(encodings, "gzip") != -1)
    else:
        return 0
 
class compressor(javax.servlet.http.HttpServlet):
 
    def service(self, req, resp):
        resp.setContentType('text/html')
        myHtml = """<html><body><h1>hello compressed world!</h1></body></html>"""
        if acceptsGzip(req):
            binarychan = resp.getOutputStream()
            zbuf = compressBuf(myHtml)
            resp.setHeader('Content-Encoding', 'gzip')
            resp.setHeader('Content-Length', '%d' % len(zbuf))
            binarychan.write(zbuf)
        else:
            textchan = resp.getWriter()
            textchan.write(myHtml)