Software documentation

Development tools

Code Structure

Techniques and Standards

How To

Functional Info

Background Info

JMRI: Threading

The vast majority of JMRI code (and programmers) don't have to worry about threading. Their code gets invoked, and invokes other code, and threading takes care of itself. This is particularly true of event-based code, which responds to events from e.g. the GUI or a layout object changing, and calls methods on other objects, which may in turn create more events.

This simplicity comes from using a single thread for processing most of JMRI's activity: The Java Swing event thread.

Note that this does not mean that other things can't be happening. For example, this script fragment:

    state = sensors.provideSensor("mySensor").getState()
turnouts.provideTurnout("myTurnout").setState(THROWN)
print state == sensors.provideSensor("mySensor").getState()
can print either true or false, because changing that turnout can change associated sensors instantaneously.

There are times when you might want to do something a bit more complex using an additional thread:

We would prefer that you handle the threading issues that arise in that case via the jmri.util.ThreadingUtil class. ThreadingUtil provides utilities that make it easy to invoke needed functions on the right thread.

For example, if you want to read a bunch of data from a file, spend some time munging it, and then create a window to present it all, you might want to do all that work on a separate thread. At the end, when it's time to set your new frame visible, you have to to that on the Swing (GUI) thread. Here's the code to do that:

    frame = new JmriJFrame();  // frame declared as instance variable
// spend a long time reading data and configuring the frame
ThreadingUtil.runOnGUI( ()->{ frame.setVisible(); });
ThreadingUtil separates operations on the GUI (e.g. Java Swing) thread, and operations on the Layout (e.g. Sensors, Turnouts, etc) thread. There's no real difference now, but in the interest of perhaps someday needing to separate those, we've introduced the two versions now. Please try to pick the mostly-likely-right one when coding.

(N.B.: You'll find lots of older cases that use explicitly use javax.swing.SwingUtilities.invokeLater(r) or javax.swing.SwingUtilities.invokeAndWait(r); these should be migrated to the newer JMRI-specific methods as time is available to keep our code just a tiny bit cleaner and more flexible.)

Ending Threads

This is really about interrupt() and our use of it.

Bottom line recommendation: Never swallow InterruptedException! If you call a method that throws it, your choices are (from best to worst):

  1. InterruptedException means your operation has been interrupted: Some other piece of code has deliberately asked your operation to end. This is not an error, and shouldn't be treated as one. If you can, terminate what the code is doing and return to normal operation.
  2. If you can't reliably terminate whatever is being done, perhaps because you're code is a low-level part, Just pass the InterruptedException up: Don't catch it, just have your method says that it throws InterruptedException.
  3. Sometimes you can't change the signature of your method: Perhaps it's overriding a Java definition by inheritance. Only if you can't terminate cleanly or pass it up, you can mark the interrupt and continue:
            try {
                wait()
            } catch (InterruptedException e) {
                Thread.currentThread().interrupt();
            }
    
    This will let execution continue, as if you hadn't received the interrupt, but the next that execution hits a blocking call, that call will immediately get an interrupt too. Perhaps it can handle it better!
For more background, please read this article.

Other Items of Interest

Using a BlockingQueue from the java.util.concurrent package can remove the need to mess with thread synchronization and locking. That can be a huge win!

The java/test/jmri/util/ThreadingDemoAndTest.java file is an example of using threads for join, interrupt, etc. It also includes a BlockingQueue example.

The jmri.util.PropertyChangeEventQueueTest can handle listening to lots of NamedBeans without possibly missing or overlapping some notifications. The jmri.jmrit.automat.SigLet class is an example of using this.

Debugging

Getting a thread-dump

When debugging threading issues, it can be helpful to get a "thread dump". Note that if running under Ant or an IDE, you might get more than one dump: The one you're looking for from JMRI, plus many one from Ant or the IDE itself.