Merge pull request #397 from gwildor28/master

Lock Pattern #71: Added mutex and semaphore modules to demonstrate locks

mutex/README.md

@@ -0,0 +1,30 @@
+---
+layout: pattern
+title: Mutex
+folder: mutex
+permalink: /patterns/mutex/
+categories: Lock
+tags: 
+ - Java
+ - Difficulty-Beginner
+---
+
+## Also known as
+Mutual Exclusion Lock
+Binary Semaphore
+
+## Intent
+Create a lock which only allows a single thread to access a resource at any one instant.
+
+![alt text](./etc/mutex.png "Mutex")
+
+## Applicability
+Use a Mutex when
+
+* you need to prevent two threads accessing a critical section at the same time
+* concurrent access to a resource could lead to a race condition 
+
+## Credits
+
+* [Lock (computer science)] (http://en.wikipedia.org/wiki/Lock_(computer_science))
+* [Semaphores] (http://tutorials.jenkov.com/java-concurrency/semaphores.html)

mutex/pom.xml

@@ -0,0 +1,42 @@
+<?xml version="1.0"?>
+<!--
+
+    The MIT License
+    Copyright (c) 2014 Ilkka Sepp�l�
+
+    Permission is hereby granted, free of charge, to any person obtaining a copy
+    of this software and associated documentation files (the "Software"), to deal
+    in the Software without restriction, including without limitation the rights
+    to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+    copies of the Software, and to permit persons to whom the Software is
+    furnished to do so, subject to the following conditions:
+
+    The above copyright notice and this permission notice shall be included in
+    all copies or substantial portions of the Software.
+
+    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+    IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+    FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+    AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+    LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+    OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+    THE SOFTWARE.
+
+-->
+<project xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd" xmlns="http://maven.apache.org/POM/4.0.0"
+    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
+  <modelVersion>4.0.0</modelVersion>
+  <parent>
+    <groupId>com.iluwatar</groupId>
+    <artifactId>java-design-patterns</artifactId>
+    <version>1.12.0-SNAPSHOT</version>
+  </parent>
+  <artifactId>mutex</artifactId>
+  <dependencies>
+    <dependency>
+      <groupId>junit</groupId>
+      <artifactId>junit</artifactId>
+      <scope>test</scope>
+    </dependency> 
+  </dependencies>
+</project>

mutex/src/main/java/com/iluwatar/mutex/App.java

@@ -0,0 +1,50 @@
+/**
+ * The MIT License
+ * Copyright (c) 2014 Ilkka Seppälä
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+ * THE SOFTWARE.
+ */
+package com.iluwatar.mutex;
+
+/**
+ * A Mutex prevents multiple threads from accessing a resource simultaneously.
+ * <p>
+ * In this example we have two thieves who are taking beans from a jar.
+ * Only one thief can take a bean at a time. This is ensured by a Mutex lock
+ * which must be acquired in order to access the jar. Each thief attempts to
+ * acquire the lock, take a bean and then release the lock. If the lock has 
+ * already been acquired, the thief will be prevented from continuing (blocked)
+ * until the lock has been released. The thieves stop taking beans once there
+ * are no beans left to take.
+ */
+public class App {
+
+  /**
+   * main method
+   */
+  public static void main(String[] args) {
+    Mutex mutex = new Mutex();
+    Jar jar = new Jar(1000, mutex);
+    Thief peter = new Thief("Peter", jar);
+    Thief john = new Thief("John", jar);
+    peter.start();
+    john.start();
+  }
+
+}

mutex/src/main/java/com/iluwatar/mutex/Jar.java

@@ -0,0 +1,67 @@
+/**
+ * The MIT License
+ * Copyright (c) 2014 Ilkka Seppälä
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+ * THE SOFTWARE.
+ */
+package com.iluwatar.mutex;
+
+/**
+ * A Jar has a resource of beans which can only be accessed by a single Thief
+ * (thread) at any one time. A Mutex lock is used to prevent more than one Thief
+ * taking a bean simultaneously. 
+ */
+public class Jar {
+
+  /**
+   * The lock which must be acquired to access the beans resource.
+   */
+  private final Lock lock;
+
+  /**
+   * The resource within the jar.
+   */
+  private int beans;
+
+  public Jar(int beans, Lock lock) {
+    this.beans = beans;
+    this.lock = lock;
+  }
+
+  /**
+   * Method for a thief to take a bean.
+   */
+  public boolean takeBean() {
+    boolean success = false;
+    try {
+      lock.acquire();
+      success = beans > 0;
+      if (success) {
+        beans = beans - 1;
+      }
+    } catch (Exception e) {
+      e.printStackTrace();
+    } finally {
+      lock.release();
+    }
+
+    return success;
+  }
+
+}

mutex/src/main/java/com/iluwatar/mutex/Lock.java

@@ -0,0 +1,34 @@
+/**
+ * The MIT License
+ * Copyright (c) 2014 Ilkka Seppälä
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+ * THE SOFTWARE.
+ */
+package com.iluwatar.mutex;
+
+/**
+ * Lock is an interface for a lock which can be acquired and released.
+ */
+public interface Lock {
+
+  void acquire() throws InterruptedException;
+
+  void release();
+
+}

mutex/src/main/java/com/iluwatar/mutex/Mutex.java

@@ -0,0 +1,67 @@
+/**
+ * The MIT License
+ * Copyright (c) 2014 Ilkka Seppälä
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+ * THE SOFTWARE.
+ */
+package com.iluwatar.mutex;
+
+/**
+ * Mutex is an implementation of a mutual exclusion lock.
+ */
+public class Mutex implements Lock {
+
+  /**
+   * The current owner of the lock.
+   */
+  private Object owner;
+
+  /**
+   * Returns the current owner of the Mutex, or null if available
+   */
+  public Object getOwner() {
+    return owner;
+  }
+
+  /**
+   * Method called by a thread to acquire the lock. If the lock has already
+   * been acquired this will wait until the lock has been released to 
+   * re-attempt the acquire.
+   */
+  @Override
+  public synchronized void acquire() throws InterruptedException {
+    while (owner != null) {
+      wait();
+    }
+
+    owner = Thread.currentThread();
+  }
+
+  /**
+   * Method called by a thread to release the lock.
+   */
+  @Override
+  public synchronized void release() {
+    if (Thread.currentThread() == owner) {
+      owner = null;
+      notify();
+    }
+  }
+
+}

mutex/src/main/java/com/iluwatar/mutex/Thief.java

@@ -0,0 +1,62 @@
+/**
+ * The MIT License
+ * Copyright (c) 2014 Ilkka Seppälä
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+ * THE SOFTWARE.
+ */
+package com.iluwatar.mutex;
+
+/**
+ * Thief is a class which continually tries to acquire a jar and take a bean
+ * from it. When the jar is empty the thief stops.
+ */
+public class Thief extends Thread {
+
+  /**
+   * The name of the thief. 
+   */
+  private final String name;
+
+  /**
+   * The jar
+   */
+  private final Jar jar;
+
+  public Thief(String name, Jar jar) {
+    this.name = name;
+    this.jar = jar;
+  }
+
+  /**
+   * In the run method the thief repeatedly tries to take a bean until none
+   * are left.
+   */
+  @Override
+  public void run() {
+    int beans = 0;
+
+    while (jar.takeBean()) {
+      beans = beans + 1;
+      System.out.println(name + " took a bean.");
+    }
+
+    System.out.println(name + " took " + beans + " beans.");
+  }
+
+}

mutex/src/test/java/com/iluwatar/mutex/AppTest.java

@@ -0,0 +1,34 @@
+/**
+ * The MIT License
+ * Copyright (c) 2014 Ilkka Seppälä
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+ * THE SOFTWARE.
+ */
+package com.iluwatar.mutex;
+
+import org.junit.Test;
+import java.io.IOException;
+
+public class AppTest{
+  @Test
+  public void test() throws IOException {
+    String[] args = {};
+    App.main(args);
+  }
+}