An Example

To give you an example of what a concurrency invariant is, consider the invokeAndWait method in the javax.swing.SwingUtilities class: You give it a Runnable, and Java will execute it in the event thread, and then return to you once that is done. This normally works, but what if you call the method from the event thread? In that case, Java will put the Runnable at the end of the event queue, and then wait for it to be executed, but it never will be executed, because the current event is waiting for that Runnable to finish. Calling javax.swing.SwingUtilities.invokeAndWait from within the event thread is a recipe for an instant deadlock! Therefore, the concurrency invariant for that method is “do not run it in the event thread”.

Here’s the sample post I’ve written for javax.swing.SwingUtilities.invokeAndWait.

If you identify a concurrency invariant, please write a new post:

  • Put the fully-qualified class name, and if it's a method, the method name, in the title.
  • Describe the invariant in the post's body.
  • Select the appropriate categories:
    • Please select the category that represents the package that contains the class you are describing, if such a category exists. To keep it simple, we have only added the most commonly used packages. If the class is in a subpackage of a package that is listed, select the category of the closest parent package.
      • If you are describing the javax.swing.SwingUtilities class, please select the "javax.swing" category.
      • If you are describing java.util.concurrent.locks.ReentrantLock class, but there is no "java.util.concurrent.locks" category, please select "java.util.concurrent" instead.
    • If a common invariant is involved, please select one of the categories like "Not Event Thread" or "Only Event Thread".
    • If you can't find any package or invariant that matches, please select "Java SE" or a project, such as "DrJava", as category.
  • Press Publish!

If you feel like an invariant has been misidentified or if you have anything else to add, please post a comment.

The research staff of the Concutest project will periodically evaluate the posts on this blog and add new invariants to our publicly available database.

Thank you!