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....