Code documentation
Development Tools
Code Structure
Techniques and Standards
Help and Web Site
How To
Functional Info
Background Info

JMRI Help:

Contents Index
Glossary FAQ

Donate to

JMRI Code: 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()
 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.)

If you do write a method that has to be called on a particular thread, please annotate it with a @InvokeOnGuiThread or @InvokeOnLayoutThread to ease later static checking.

If you have ensured that a method is thread safe and may be run on any thread, please mark it with @InvokeOnAnyThread

If you want to check at runtime that something is running on the intended thread:


That check does take a bit of time, so it should probably only be done on entry to a large chunk of code, or perhaps be protected by a check of log.isDebugEnabled(). If the call occurs on the wrong thread, a Log4JUtil.warnOnce logs the first occurance with traceback info. In addition to the @InvokeOnGuiThread, @InvokeOnLayoutThread and @InvokeOnAnyThread annotations mentioned here, there are @ThreadSafe, @NotThreadSafe, @Immutable, and @GuardedBy annotations that are useful. See the discussion on the JMRI SpotBugs page.

If you do need to launch a thread of your own, there are a few things to remember:

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 {
     } catch (InterruptedException e) {
    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.

Timed Events

The jmri.util.ThreadingUtil class provides the runOnGUIDelayed and runOnLayoutDelayed methods to make it easy to run some code after a delay. In general, you should use these whenever possible instead of explicit javax.swing.Timer or java.util.Timer objects.

We recommend you not use the java.util.Timer class directly because of significant issues:

The jmri.util.TimerUtil can help with these issues.

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/ file is an example of using threads for join, interrupt, etc. It also includes a BlockingQueue example.

The jmri.util.PropertyChangeEventQueue class 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.


Getting a thread-dump

When debugging threading issues, it can be helpful to get a "thread dump".

To do this when using an Oracle JVM (most common case), open a separate window and on that command line enter the command 'jvisualvm'. This will open a new window with tools for browsing all the Java currently running on your machine. Then

  1. In the upper left, double-click the line that shows your running JMRI instance. (You might have to open the "Local" selector to see it) If should say something about PanelPro or DecoderPro. It'll take a few seconds, but then the right side will open with new information.
  2. Select the "Threads" tab in the middle-upper on the right side.
  3. Click the "Thread Dump" button in upper right.
  4. A new tab will open with the dump. There's no direct way to save that, but you can copy and paste those contents into an editor to save them or an email to send them.

If for some reason you can't use jvisualvm, then:

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 maybe one from Ant or the IDE itself.