Potential Games LLC

While profiling the runtime memory allocation in my game server, I found that my Coordinate class had far-and-away the most numerous instances (over 600,000 at one count). Even though small (each Coordinate includes latitude and longitude integers), this was also the largest contributor to live memory in the Java Virtual Machine. The JVM is very good at creating and disposing of small, short-lived objects. I suspect, however, that many of these Coordinate instances are being retained by server subsystems. For example, map logic, entity positions, and fog coverage all retain Coordinate objects. What is more, many of these Coordinate instances are likely to be redundant copies of the same [latitude, longitude] pair, especially because most maps in the world share the same coordinate space. This is exactly the time to employ the flyweight design pattern. The flyweight design pattern avoids allocating redundant objects by sharing instances. Instead of hundreds of Coordinate[12,12] being instantiated, only one is created. This reduces the amount of overall memory allocation, but at some cost. One cost is the bookkeeping (data structure and algorithm overhead) needed to store and look up existing objects. A Coordinate object is requested by its latitude and longitude, which I turn into a unique key. The simplest approach is to maintain a Map, but this has the downside of keeping every instance ever created in memory. To avoid the cost of retaining references to rarely requested Coordinates, I employed a LinkedHashMap with the access-order constructor flag, overriding the removeEldestEntry() method to produce a least-recently-used (LRU) collection. The least requested Coordinate objects are dropped from the collection, based on an arbitrary maximum capacity (which was determined by experimentally observing the profiling at different thresholds). Once the flyweight collection is full, it does incur higher baseline memory allocation, even when the server is idle, because the Coordinate instances cannot be garbage collected. As a further improvement (not yet implemented), the map could store weak references to the Coordinate objects, to avoid keeping them in memory when no longer needed. In practice, the LRU flyweight Coordinate mechanism appears to lower peak memory allocation and gives a more stable memory profile (not so much spiking and garbage collecting). Instead of hundreds of thousands of live Coordinate instances, there are at most tens of thousands held as flyweights and some stragglers that were dropped from the LRU collection. The overall goal was to reduce and stabilize long-term server memory allocation, which appears to be happening.

It's old news that Java's Swing GUI toolkit follows a deficient Model-View-Controller (MVC) architecture. In most cases, Swing fuses together the notion of the View and Controller, but offers a separate Model. At least, that's what the naming convention implies. For example, JComboBox should be a View-Controller to a ComboBoxModel. This particular case failed me today. Read the rest of this entry »

In a previous article, I described a Concealed Controller Pattern, which allows Java classes to be packaged separately, while maintaining access control to certain sensitive methods. In today's article, I discuss the shortcomings of Java's package capabilities and present a simple pattern (the Keyed Access Pattern) for overcoming one case. Read the rest of this entry »

This article provides a use case that chronicles my experience with the Java Logging API, as used for my MMORPG platform. Software developers can take this article as a cautionary tale against code reuse zealotry. It is often advantageous to follow your own software design goals rather than force your design around an existing system. Read the rest of this entry »

Students of software must be taught early the benefits of object oriented design, lest they succumb to the dark side of static programming. When designing a software component, the temptation can be to write globally accessible public static methods in lieu of instantiable objects. Even experienced developers must remain diligent to avoid being turned to this quicker, more seductive, approach. Read the rest of this entry »

This article describes an interesting design pattern that I utilized in my Potential RPG code. The following describes the pattern in general and how I've used it in my code. Has anyone seen this pattern in the wild? Does it have any other common forms or names? Read the rest of this entry »

Java interfaces are a wonderful thing; don't get me wrong. However, many interface contracts make assumptions about how the implementation will behave. What is more, Java offers no way to programmatically enforce such an interface contract. This article discusses a particular example of interface behavioral assumption and how to (partially) enforce the behavior programmatically. Read the rest of this entry »

Elderly swing-set factory employees using thread instead of chains forces product recall? No. Why would you think that? This article describes how the javax.swing.Timer utility can cause your Swing application to hang at shutdown, and how to fix it. The Timer utility is useful for repeating tasks on the Swing/AWT thread. They're handy enough to create in many places throughout GUI code. However, each one that remains active keeps the AWT thread alive, which prevents clean application shutdown (without resorting to System.exit()). Lacing the code with Timer instances makes it difficult to track them all down and stop them when the application is supposed to exit. To correct the situation for the MMORPG client, I created a simple factory class with a create(..) method for producing Timer instances. The factory maintains a reference to every Timer created. At application shutdown, the factory's stop() method is called, which tells each Timer to stop(). After replacing all Timer constructor calls with the factory's create(..) method, the MMORPG client exits cleanly. There are a few caveats. For one, you must be certain it is safe to stop Timers in this way (a Timer may be carrying out some critical pre-shutdown operation). In general, I only use Timers for GUI-related activities, and not to drive application logic. Another weakness is that the factory cannot guarantee the Timers will not be restarted, or that more timers will not be created, after stopping the factory. This could be guarded with a more sophisticated design, such as a TimerProxy class to prevent post-shutdown starting, refusing to create new timers after shutdown, or an isStopped() method for GUI code to query. For the MMORPG client, this simple factory pattern is sufficient to untie Timers from the AWT thread, allowing clean shutdown without resorting to System.exit().

For those who enjoy design patterns, I've written a ProxyIcon for the MMORPG client. The reason is to decrease memory allocation in the client, which is due in large part to graphic images, under the theory that most are not needed most of the time. This article describes the ProxyIcon (implementation details are left as an exercise for the reader). First, there is already a central factory of Icons. So, integrating a new proxy pattern only involved changing the factory. ProxyIcon implements the javax.swing.Icon interface, so users are none the wiser. ProxyIcon knows the source of the image to load. When any Icon methods are accessed, it makes sure the internal image is loaded. If not accessed for some timeout, the internal icon can be unloaded. The simplest implementation would have set the internal Icon reference to null, allowing the garbage collector to clean it up. Why the present perfect tense? Because there's an even better approach: ProxyIcon holds two references to the internal Icon: A hard reference and a soft reference. After the timeout, the hard reference is set null, but the soft reference is retained. Since the embedded icon is only referenced (never exposed) from the ProxyIcon object, this leaves only the soft reference. Java cleans up soft references (only) when memory is needed. If, however, the ProxyIcon is accessed before being cleaned up, the hard reference is reinstated. This provides the best of both worlds: Application logic can set policy on when to release resources but is backed up by the Java Virtual Machine's garbage collection logic to avoid unhelpful cleanup. The primary benefit, of course, is that unused icon resources can be deallocated. The software design benefit is that image users do not need to concern themselves with whether the icon is currently loaded or not. Notice that all ProxyIcon references stay in memory forever (in the factory). They could also be deallocated by using soft or weak references in the factory, but the objects themselves are (theoretically) miniscule compared to image memory consumption. Another minor benefit is lazy image loading. Instead of loading upon construction, the internal icon is loaded lazily upon first access. There are a number of icons that are requested in the code, but not always used. This feature has the benefit that the code can greedily ask for icons from the factory (e.g., as static variables) without impacting memory if not needed. One major gotcha is that Java itself may be holding cached references to the image data, which prevents garbage collection. I have not investigated this fully, but do not use Toolkit.getImage(), as it's API warns of just this problem. Also read the code for javax.swing.ImageIcon, which makes (undocumented) use of Toolkit.getImage(). Instead, use Toolkit.createImage() or ImageIO.read() with ImageIO.setUseCache(false). Further investigation is needed to determine exactly who has access to underlying image data depending on how it is loaded. For Alpha testers, look at $HOME/.potentialrpg/stat/IconFactory.stat, which shows:

timestamp, total, loaded, hard_referenced, average_ms_timeout, ms_stat_time