Introduction

ASync

The ASync library allows all network I/O to be performed in a single-threaded, event-driven manner using the asynchronous (New I/O) packages of Java. To do this, an ASync instance is first created. Then, all ASync services that wish to perform I/O efficiently in a single-thread register themselves with this instance. When the run method of the ASync instance is invoked, all the services are in turn notified. These services are then free to schedule events with the ASync instance and register SelectableChannel objects with given interested operations. The single thread that invoked the run method of the ASync instance is responsible for notifying the appropriate service when a scheduled event occurs or a SelectableChannel is ready with an interested operation. Thus, ASync serves as an abstraction layer, allowing any number of services to use a single thread for all network I/O and event scheduling without interfering, much less being aware, of one another. For complete documentation, click here.

ASyncTCP

ASyncTCP is a service developed for ASync that allows easy management of both client and server TCP/IP connections. Each connection has an associated queue, into which a message can be put and carefully monitored by its respective handle until finally sent. All an enqueued message must do is provide a serialization routine, while a receiver attaches a listener on a connection to deserialize the message. For complete documentation, click here.

ASyncUDP

ASyncUDP is a service developed for ASync that allows for both sending and receiving UDP/IP datagrams easily. Similar to ASyncTCP, each destination has an associated queue, into which a message can be put and carefully monitored by its respective handle until finally sent. Each message provides a serialization routine, while a receiver attaches a listener to its server port to deserialize any received messages. For complete documentation, click here.

PonyRide

PonyRide is service developed for ASync that uses a simple protocol on top of UDP to mimic TCP, thereby allowing the client to traverse NATs more easily, and finely tune TCP-like parameters for maximum performance. The following characteristics of TCP are all implemented in PonyRide:

PonyRide is not included in the current release, but will be present in the 1.0 beta. See the timeline below for more details.

Heaps

The heaps package is an library of min-heaps used by ASync, allowing efficient composition of a global event queue from all service event queues. For complete documentation, click here.

Limitations

Right now the most severe limitation is that, for the current implementations of ASyncTCP, ASyncUDP, and PonyRide, the methods belonging to classes of each service can only safely be called by the ASync thread that is performing all the networking I/O. If you write a service for ASync, it is your responsibility to make methods exposed by your service thread-safe. For a solution to this problem in any service, use method addEvent of the ASync instance to pass an anonymous class containing the code to execute to the ASync thread. I hope to address this limitation of the ASyncTCP, ASyncUDP, and PonyRide services in a future release.

Dependencies

ASync requires the log4j logging package and a library for composing event queues called heaps. The log4j logging package is available here, while the event queue library can be found by following under Download.

Examples

The example ASyncExample.java uses a single thread and two ASyncTCP services to send 64KB of random data via TCP from port 7000 to 7001. For this example to work, log4j, async-0.9.7.jar, and heaps-1.5.jar must all be on your classpath. Note that this example requires the file CountingBarrier.java in the same directory. The use of CountingBarrier unfortunately makes the example harder to follow, but is needed to deal with the limitation outlined above regarding the methods of ASyncTCP not being thread-safe. Each collection of calls to unsafe methods is contained in an ASyncEvent object. The CountingBarrier allows the main thread to proceed to the next collection of calls only once the previous collection has been executed by the ASync thread.

More examples will soon follow.

Timeline

The following is a tentative outline for the various releases of ASync and PonyRide:

Version 1.0 beta will be the first release to include PonyRide along with ASync, ASyncTCP, and ASyncUDP. Once all bugs are fixed in PonyRide, version 1.0 stable will be released. The timeline for the 1.0 branch is undetermined.

Download

PonyRide is written in Java 5.0 and released under the BSD license. The latest beta is version 0.9.7, released April 28, 2006, which includes only ASync and the TCP and UDP messaging facilities. No stable version has been released yet. Both the source code and a JAR file containing the compiled class files can be downloaded from here. The file async-0.9.7.jar includes ASync, ASyncTCP, and ASyncUDP, while the file heaps-1.5.jar includes the min-heap library mentioned above in Dependencies. More information about the project can be found at the SourceForge Project Page. SourceForge graciously hosts this web site.

Contact

ASync & PonyRide are Copyright 2005-2006 Michael Parker.