Package net.sf.freecol.client

FreeCol Client Package

This is the main client package.

survey of Thread objects in the FreeCol client

This is the way threads were used when this was written:

Anonymous sub-classes of Thread

  • Canvas (client shutdown hook)
  • ConnectController (loading game)
  • FreeCol (server shutdown hook)
  • InGameController (save game, choose Founding Father)
  • ReceivingThread (urgent messages)

(The shutdown hooks don't really count as they're not a normal use of a thread.)

Named sub-classes of Thread

  • Canvas (ChatDisplayThread, TakeFocusThread)
  • CanvasMouseMotionListener (ScrollThread)
  • MetaServer
  • ReceivingThread
  • Server
  • SoundPlayer (SoundPlayer)

Some code in FreeCol that does real work is run on the AWT thread. The AWT thread is used to paint the user interface and to notify the application of user interface events. When the AWT thread is busy, Java user interfaces look like grey boxes. Users often report this as a "hang" or a "crash".

This can be avoided by only using the AWT thread for things that must be run on it (such as to update the state of the user interface objects (JTable, etc.). Technically, all Swing methods should be invoked on the AWT thread).

What follows is not an invention, rather something that worked well on other projects.

The three-thread model of a GUI application

The three threads are:

  1. the AWT thread
  2. the network thread
  3. the work thread

the AWT thread

The AWT thread is started by Java and runs all callbacks (such as MouseListener). When a callback is invoked, the AWT thread does the work if it involves only manipulating Swing objects, otherwise it queues a job for the work thread. All Swing objects should be manipulated on the AWT thread. This is done as normal with invokeLater(Runnable). The behaviour ensures that the AWT thread is always ready to paint when the Operating System uncovers an application window.

The network thread

The network thread is blocked from listening most of the time. When it wakes up, it may interact with the work thread (typically by queueing a message that has been received) and then goes straight back to listening. This behaviour improves the throughput of the link.

The work thread

The work thread is idle most of the time and does jobs for the other threads when they are queued.

Advantages

The model is very simple and because the only places in the code where synchronization is required are where the AWT or network threads interact with the work thread, no synchronization is required over the rest of the code, which saves typing, is easier to understand and faster.

$Revision$

Since:
0.2.0