SuperMan bound by Java Monitors

Photo Taken from : http://goo.gl/2B5Sj

Its a dark time in the life of Super Man. Jor-El wants him to go on a voyage to prepare him for his ultimate destiny. Yet the Earth is faced with dooms-day and the Justice League needs their Man of Steel in action to save the world. But you cant do both at the same time since we have just one SuperMan. Also he cannot fight dooms day without first fulfilling his destiny and realizing his true powers. How do we call upon Superman without making the man go bonkers on what to do. This should be done in an orderly manner where one has to wait until the voyage is done.

We will make use of Java Monitors to help SuperMan listen to his Kryptonian father as well as come back in time to save the world from dooms day. First of all we define the Man of Steel;

/**
 * The awesome kryptonian man is represented by this class
 * 
 * @author Dinuka Arseculeratne
 *
 */
public class SuperMan {

 private boolean onVoyage = false;

 /**
  * Schedule a voyage for Superman. Note that this method first checks whether he is
  * already on a voyage, and if so calls the wait() method to hault the current thread
  * until notify is called and onVoyage is set to false.
  */
 public synchronized void goOnVoyage() {

  if (onVoyage) {
   try {
    System.out.println("SuperMan is already on a voyage. Please wait until he returns from his quest.");
    wait();
    System.out.println("His goyage is over, time for him to go on a new voyage....");
   } catch (InterruptedException e) {
    System.out.println(" I am SuperMan, i do not handle these petty exceptions");
   }

  }
  onVoyage = true;
  notify();

 }

 /**
  * This method calls Superman back from his current voyage. Again the method
  * checks whether Super man is not already on a voyage. If so the current thread is
  * Halted until he is schedule to go on a voyage because he needs to be on a voyage
  * to be called back in the first place.
  */
 public synchronized void returnFromVoyage() {

  if (!onVoyage) {
   try {
    System.out.println("SuperMan is not yet on a voyage. Please Wait.");
    wait();
    System.out.println("Great he has gone on a voyage, time to call him back!!");
   } catch (InterruptedException e) {
    System.out.println(" I am SuperMan, i do not handle these petty exceptions");
   }
  }
  onVoyage = false;
  notify();
 }
}

So we have defined SuperMan. Note that he has two methods defined. One which allows him to go on a voyage and another to call him back from his current voyage. As you can see SuperMan does not handle exceptions because, well.......... He is SuperMan and he is the exception :). You can see that before each call we check the boolean indicating whether he is on a voyage or not and depending on the method called, the wait() of the Object is called in order to halt the current thread that is calling the method until notify() is called by the thread that is currently operating on the object. Note that wait() and notify() should be called inside a synchronized method or block for it to work accurately. Because you first need to acquire a lock in order to halt or notify it.

Getting back to the previous issue, we know that both the Justice League and Jor-El need SuperMan but for different purposes. Lets see how this battle unravels with the following code snippet;

public class Test {

 public static void main(String[] args) {
  SuperMan superMan = new SuperMan();
  
  JusticeLeague justiceLeague = new JusticeLeague(superMan);
  justiceLeague.start();
  
  JorEl jorEl = new JorEl(superMan);
  jorEl.start();
  
 }

 

}

class JusticeLeague extends Thread{
 
 private SuperMan superMan = null;
 
 public JusticeLeague(SuperMan superMan)
 {
  this.superMan = superMan;
 }
 
 @Override
 public void run() {
  superMan.returnFromVoyage();
 }
}

class JorEl extends Thread{
 
 private SuperMan superMan = null;
 public JorEl(SuperMan superMan)
 {
  this.superMan = superMan;
 }
 
 @Override
 public void run() {
  superMan.goOnVoyage();
 }
 
}

Note that here we have JorEl and the JusticeLeagure operating on two different threads trying to access SuperMan concurrently. As you can see from our main method, the JusticeLeague wants to call back SuperMan in order to save the world. But fortunately he is not yet on a voyage so its illegal to ask him to return. Then comes JorEl asking his son to go on a voyage to fulfill his true destiny. It is only after this voyage that he can return to save planet Earth. If you run this now you can see that the JusticeLeague thread is halted until SuperMan goes on the voyage and notify is called. Just for fun try to comment out the notify() method and you will see the application will hang because now one thread will wait indefinitely until it is notified of the completion of the process.

If not for Java Monitors, SuperMan would have failed since he would have gone to face doomsday without first going on his voyage and fulfilling his destiny. And Java saves the world again.

Note : The story is fictional yet Java Monitors are real


Thank you for reading everyone. And have a great day ahead. If you feel like it, please do leave by a comment. Cheers!!

Locking with a semaphore : An example

Concurrency is one aspect that brings along interesting challenges along with it. If not correctly handled, it brings about race conditions that will baffle people because those issues just pop up from time to time and work flawlessly sometimes.

The Java language gives many ways of handling race conditions when dealing with concurrent threads accessing a common resource. Some include;

1. Using the volatile keyword
2. Using classes available in java.util.concurrent and java.util.concurrent.atomic 
3. Synchronized blocks
4. Using a Semaphore

Of course there might be many more that i might not be aware of. For today, the example i want to show you all is the one using a Semaphore. This was introduced from JDK 1.5, and provides the developer with the ability to acquire and release locks in a seamless way. Also the example i will be showing is a hypothetical scenario which i used just to depict what can be achieved using a semaphore and therefore please do not look at the intrinsic details of the code :)..

So the scenario as such, there is an in-memory cache holding objects of type "Person". Users can insert and retrieve records using the cache. The issue here is we are going to control concurrent access to our in-memory cache using semaphores. Now i do not want to bore you with more text so lets get to business and show some code;

 
import java.util.concurrent.Semaphore;

/**
 * This class will allow thread to acquire and release locks as required
 * 
 * @author dinuka.arseculeratne
 * 
 */
public class PersonLock {

 /**
  * We do not want multiple lock objects lying around so we make ths class
  * singleton
  */
 private PersonLock() {

 }

 /**
  * Bill Pugh's way of lazy initializing the singleton instance
  * 
  * @author dinuka.arseculeratne
  * 
  */
 private static class SingletonHolder {
  public static final PersonLock INSTANCE = new PersonLock();
 }

 /**
  * Use this method to get a reference to the singleton instance of
  * {@link PersonLock}
  * 
  * @return the singleton instance
  */
 public static PersonLock getInstance() {
  return SingletonHolder.INSTANCE;
 }

 /**
  * In this sample, we allow only one thread at at time to update the cache
  * in order to maintain consistency
  */
 private Semaphore writeLock = new Semaphore(1);

 /**
  * We allow 10 concurrent threads to access the cache at any given time
  */
 private Semaphore readLock = new Semaphore(10);

 public void getWriteLock() throws InterruptedException {
  writeLock.acquire();
 }

 public void releaseWriteLock() {
  writeLock.release();
 }

 public void getReadLock() throws InterruptedException {
  readLock.acquire();
 }

 public void releaseReadLock() {
  readLock.release();
 }
}

This class will handle the process of obtaining and releasing locks required to make our cache thread safe. I have used two separate locks here for reading and writing. The rationale behind this was to allow users to read data though it might be stale at the time of reading.

Note that i have used "ten" here which denotes that ten thread can simultaneously obtain locks and access the cache for read purposes. Next up you can see in the write lock, i have used the "one" which signifies that only one thread can access the cache at a time to put items to it. This is important in order to maintain consistency within the cache. That is, i do not want multiple threads trying to insert items to the map which would result in unpredictable behavior ( at least in some instances). There are mainly two ways by which you can acquire a lock using a semaphore.

 1. acquire() : is a blocking call which waits until the lock is released or the thread is interrupted
2.  tryAcquire() : is a non-blocking call which will return immediately and return true or false signifying whether the lock was obtained or not.

Here i have used the blocking acquire call because i want the thread to wait until the lock is available. Of course this will depend on your use case. You can also define a timeout period in the tryAcquire() method so  that the thread will not wait indefinitely for a lock.

Next up the storage class below shows how i have used the lock class to insert and read data within the cache.

 
import java.util.HashMap;
import java.util.Map;

/**
 * A mock storage to hold the person objects in a map
 * 
 * @author dinuka.arseculeratne
 * 
 */
public class PersonStorage {

 private Map<Integer, Person> personCache = new HashMap<Integer, Person>();

 private int counter = 0;

 /**
  * This class is made singleton and hence the constructor is made private
  */
 private PersonStorage() {

 }

 /**
  * Bill Pugh's way of lazy initializing the singleton instance
  * 
  * @author dinuka.arseculeratne
  * 
  */
 private static final class SingletonHolder {
  public static final PersonStorage INSTANCE = new PersonStorage();
 }
 
 /**
  * Use this method to get a reference to the singleton instance of
  * {@link PersonStorage}
  * 
  * @return the singleton instance
  */
 public static PersonStorage getInstance()
 {
  return SingletonHolder.INSTANCE;
 }

 /**
  * Inserts the person into the map. Note that we use defensive copying so
  * that even if the client changes the object later on, those changes will
  * not be reflected in the object within the map
  * 
  * @param person
  *            the instance of {@link Person} to be inserted
  * @return the key which signifies the location of the person object
  * @throws InterruptedException
  */
 public int putPerson(Person person) throws InterruptedException {
  
  Person copyPerson = person.copyPerson();
  personCache.put(++counter, copyPerson);
  
  return counter;
 }

 /**
  * Here as well we use defensive copying so that the value of the object
  * reference within the map is not passed in to the calling party.
  * 
  * @param id
  *            the id representing the location of the object within the map
  * @return the instance of the {@link Person} represented by the key passed
  *         in
  * @throws InterruptedException
  */
 public Person retrievePerson(int id) throws InterruptedException {
  PersonLock.getInstance().getReadLock();
  if (!personCache.containsKey(id)) {
   throw new RuntimeException("Key is not found");
  }
  PersonLock.getInstance().releaseReadLock();
  return personCache.get(id).copyPerson();
 }

}

Obviously the code will work without the locks as well, but the issue is that the application will be inconsistent and provide different results at each run. This is not something you want your application to do and hence with locks you guarantee your application works consistently.

And lastly a small test class to show how it will behave; not that in here we obtain the lock before calling the putPerson() method and release the lock within the finally block in order to guarantee the release of the lock.

 
/**
 * A test class to demonstrate the locking at work
 * 
 * @author dinuka.arseculeratne
 * 
 */
public class TestLock {

 public static void main(String[] args) throws InterruptedException {

  Thread t1 = new Thread(new Runnable() {

   @Override
   public void run() {
    
    Person p1 = new Person(1L, "Test1", "XYZ");
    try {
    PersonLock.getInstance().getWriteLock();
PersonStorage.getInstance().putPerson(p1);
    } catch (InterruptedException e) {
     // Exception handling need to be done
     e.printStackTrace();
    }
   finally{
          PersonLock.getInstance().releaseWriteLock();
    }
   }
  });

  Thread t2 = new Thread(new Runnable() {

   @Override
   public void run() {
    
    Person p2 = new Person(2L, "Test123", "ABC");

    try {
     PersonLock.getInstance().getWriteLock();

     PersonStorage.getInstance().putPerson(p2);
    } catch (InterruptedException e) {
     // Exception handling need to be done
    }
 finally{
          PersonLock.getInstance().releaseWriteLock();
    }
    
   }
  });

  t1.start();
  t2.start();

  System.out.println(PersonStorage.getInstance().retrievePerson(2));
 }
}

That concludes my short introduction to using Sempahores to make your code thread safe.For anyone who wants to play around with the code, you can obtain it from here. Try to remove the locks in the Storage class and see how it behaves on each run. You will see possible race conditions taking place.

Appreciate your comments and feedback on the same as always and thank you for reading.

Cheers....