AtomEclipse

Semantics | Disclamer | Download & Setup | Lecture Slides | Contact

Teaching shared-memory concurrency to computer science undergrads can be a frustrating task. Nondeterministic thread scheduling is understandably jarring after several courses' worth of sequential programming; the added complications of locks, race conditions, and deadlock make this new concurrent world all the more disorienting. At the University of Washington, we have found it helpful to begin instruction of shared-memory concurrency control with atomic transactions. Atomic transactions allow programmers to execute parts of code as if the program were single-threaded.

Atomic transactions have relatively straightforward semantics compared to locks: code enclosed within an atomic block runs as if no other threads were interleaved with the computation, and other threads behave as if the transactional code happened "all at once." Within the runtime system, other threads may be interleaved in a way such that their memory accesses do not conflict with the current transaction's, and the transaction may abort or roll back if a conflict occurs, but these details are largely invisible to the programmer.

Unfortunately, atomic transactions are a new enough concept in programming languages that implementations (though they certainly exist) have not yet made their way into the popular distributions of mainstream languages like Java, C and C++. Therefore, instructors cannot demonstrate atomic transactions in class or use atomic transactions in homeworks. We have developed an educational tool called AtomEclipse to fill this void.

AtomEclipse is an Eclipse plugin that allows Java threads to run atomic transactions in Eclipse's debug mode. The plugin uses various hooks in the Java Debug Interface (JDI) to catch when threads enter and exit atomic blocks and prevent other threads from running accordingly. The project was developed by Laura Effinger-Dean with support from an Intel grant, and is intended for use in the University of Washington's CSE 303 course. If you would like to use AtomEclipse at your institution, please try it out and let us know how it works for you.

Semantics

With AtomEclipse, you can mark code points to enter and exit atomic sections by calling AtomicDebug.enterAtomic() and AtomicDebug.exitAtomic(), respectively. When a thread calls AtomicDebug.enterAtomic(), the plugin suspends any other running threads, so the calling thread is the only thread running. Calling AtomicDebug.exitDebug() resumes the suspended threads. For example, to create a thread-safe withdraw() method for a bank account class:

/* Withdraw money from the account. The method returns true
* if the withdrawal was successful and false otherwise.
*/
public boolean withdraw(int amount) {
  AtomicDebug.enterAtomic();
  int currentBalance = getBalance();
  if(currentBalance < amount)
    return false;
  setBalance(currentBalance - balance);
  AtomicDebug.exitAtomic();
}

Atomic sections may also be nested. Threads currently in an atomic section maintain a counter; calls to AtomicDebug.enterAtomic() and AtomicDebug.exitAtomic() increment and decrement the counter, respectively. When the counter hits zero, the suspended threads are resumed. So if we wanted to write a transfer() method that called the deposit method, the atomic sections compose:

/* Transfer money from this account to another. The method
* returns true if the transfer was successful and false
* otherwise.
*/
public boolean transfer(BankAccount other, int amount) {
  AtomicDebug.enterAtomic();
  if(this.withdraw(amount)) {
    other.deposit(amount);
    return true;
  }
  return false;
  AtomicDebug.exitAtomic();
}

If a thread terminates during an atomic section without issuing the proper calls to AtomicDebug.enterAtomic(), the waiting threads resume automatically. If a thread tries to run another thread during an atomic section via Thread.start(), the new thread is suspended until the atomic section completes.

Disclaimer

AtomEclipse is intended for demonstration purposes. It works well for the examples that we have tested, but we do not recommend using it in class without testing your code a few times. The plugin does not work unless you are using Eclipse's debug mode to run your program. The implementation does not provide any fairness guarantees in thread scheduling, so if a thread executing an atomic section goes into an infinite loop, the other threads will remain suspended forever. There is no abort/retry feature: a thread's actions within an atomic section cannot be undone, and once a thread enters an atomic section, it must complete the section before any other threads may run.

Download & Setup

Downloads:
AtomEclipseExamples.zip
AtomicDebug.jar

In order to use AtomEclipse, follow these steps:

  1. First, you need to have a working version of Eclipse (version 3.1 or higher). You can download Eclipse from http://www.eclipse.org/downloads/. Make sure to get the Java version.
  2. Install the plugin from WASP's update site:
    1. In Eclipse, click Help -> Software Updates -> Find and Install.
    2. Choose "Search for new features to install" and click Next.
    3. Click "New Remote Site..."
    4. Use site name "WASP Eclipse update site" and site URL http://wasp.cs.washington.edu/eclipse-update.
    5. Click Finish.
    6. Eclipse fetches a list of available plugins. Navigate to Wasp Eclipse update site -> Other -> AtomEclipse, and check the box next to AtomEclipse. Click next.
    7. Accept the license agreement. Click next.
    8. If you have administrative access for your machine, you can use the default installation location. Otherwise, you can specify a folder in which to install the plugin. Just pick a folder to which you have write access. Click Finish.
    9. A warning pops up that the plugin is not digitally signed. Click Install.
    10. Click Yes to restart Eclipse.
  3. Now the AtomEclipse should be installed. Click Window -> Show View -> Debug -> Atomic Debug. A "view" (a tabbed window) pops up, saying "Atomic Debug is disabled." Enable atomic debug by pressing the purple button.
  4. Now you have two choices: use our example project, or use AtomEclipse with your own code. We recommend starting with the example project, so you can get an idea of how the plugin works.
  5. Run your program (or one of the example programs) in debug mode:
    1. Right-click (Mac: Control-click) on the java file you want to run in the Package Explorer view.
    2. Choose Debug As -> Java Application.
    3. The program executes using atomic blocks. The Atomic Debug view displays the current atomic thread while running; to see the action more slowly, you can set breakpoints in the Java program and step through using the Eclipse debugger.

Lecture Slides

I used AtomEclipse in a guest lecture for CSE 303, Concepts and Tools for Software Development, in Fall 2007. Here are the slides: full version handouts version LaTeX source

Some of the slides are based on Dan Grossman's lecture from Spring '07. The code examples are included in the examples package linked to above.

Contact

AtomEclipse is under development - please contact Laura (effinger AT SEE ESS DOT washington DOT EE DEE YOU) if you have questions, comments, or bug reports!