LCK08-J. Ensure actively held locks are released on exceptional conditions

An exceptional condition can circumvent the release of a lock, leading to deadlock. According to the Java API [[API 2006]]

A ReentrantLock is owned by the thread last successfully locking, but not yet unlocking it. A thread invoking lock will return, successfully acquiring the lock, when the lock is not owned by another thread.

Consequently, an unreleased lock in any thread will prevent other threads from acquiring the same lock. Programs must release all actively held locks on exceptional conditions. Intrinsic locks of class objects used for method and block synchronization are automatically released on exceptional conditions (such as abnormal thread termination).

Noncompliant Code Example (Checked Exception)

This noncompliant code example protects a resource using a ReentrantLock but fails to release the lock if an exception occurs while performing operations on the open file. When an exception is thrown, control transfers to the catch block and the call to unlock() fails to execute.

public final class Client {
  public void doSomething(File file) {
    final Lock lock = new ReentrantLock();
    InputStream in = null;
    try {
      lock.lock();
      in = new FileInputStream(file);
      // Perform operations on the open file
      lock.unlock();
    } catch (FileNotFoundException x) {
      // Handle exception
    } finally {
      if (in != null) {
       try {
          in.close();
        } catch (IOException x) {
          // Handle exception
        }  
      }
    }
  }
}

Note that the lock is still held, even when the doSomething() method returns.

This noncompliant code example also fails to close the input stream and, consequently, violates rule FIO04-J. Close resources when they are no longer needed.

Compliant Solution (finally Block)

This compliant solution encapsulates operations that could throw an exception in a try block immediately after acquiring the lock. The lock is acquired just before the try block, which guarantees that it is held when the finally block executes. Invoking Lock.unlock() in the finally block ensures that the lock is released, regardless of whether an exception occurs.

public final class Client {
  public void doSomething(File file) {
    final Lock lock = new ReentrantLock();
    InputStream in = null;
    lock.lock();
    try {
      in = new FileInputStream(file);
      // Perform operations on the open file
    } catch (FileNotFoundException fnf) {
      // Forward to handler
    } finally {
      lock.unlock();

      if (in != null) {
        try {
          in.close();
        } catch (IOException e) {
           // Forward to handler
        }
      }
    }
  }
}

Compliant Solution (Execute-Around Idiom)

The execute-around idiom provides a generic mechanism to perform resource allocation and clean-up operations so that the client can focus on specifying only the required functionality. This idiom reduces clutter in client code and provides a secure mechanism for resource management.

In this compliant solution, the client's doSomething() method provides only the required functionality by implementing the doSomethingWithFile() method of the LockAction interface, without having to manage the acquisition and release of locks or the open and close operations of files. The ReentrantLockAction class encapsulates all resource management actions.

public interface LockAction {
  void doSomethingWithFile(InputStream in);
}

public final class ReentrantLockAction {
  public static void doSomething(File file, LockAction action)  {
    Lock lock = new ReentrantLock();
    InputStream in = null;
    lock.lock();
    try {
      in = new FileInputStream(file);
      action.doSomethingWithFile(in);
    } catch (FileNotFoundException fnf) {
      // Forward to handler
    } finally {
      lock.unlock();

      if (in != null) {
        try {
          in.close();
        } catch (IOException e) {
          // Forward to handler
        }
      }
    }
  }
}

public final class Client {
  public void doSomething(File file) {
    ReentrantLockAction.doSomething(file, new LockAction() {
      public void doSomethingWithFile(InputStream in) {
        // Perform operations on the open file
      }
    });
  }
}

Noncompliant Code Example (Unchecked Exception)

This noncompliant code example uses a ReentrantLock to protect a java.util.Date instance – recall that java.util.Date is thread-unsafe by design. The doSomethingSafely() method must catch Throwable to comply with rule ERR01-J. Do not allow exceptions to expose sensitive information.

final class DateHandler {
  private final Date date = new Date();
  final Lock lock = new ReentrantLock();

  public void doSomethingSafely(String str) {
    try {
      doSomething(str);
    } catch(Throwable t) {
      // Forward to handler
    }
  }

  public void doSomething(String str) {
    lock.lock();
    String dateString = date.toString();
    if (str.equals(dateString)) {
      // ...
    }
    lock.unlock();
  }
}

A runtime exception can occur because the doSomething() method fails to check whether str is null, preventing the lock from being released.

Compliant Solution (finally Block)

This compliant solution encapsulates all operations that can throw an exception in a try block and releases the lock in the associated finally block.

final class DateHandler {
  private final Date date = new Date();
  final Lock lock = new ReentrantLock();

  public void doSomethingSafely(String str) {
    try {
      doSomething(str);
    } catch(Throwable t) {
      // Forward to handler
    }
  }

  public void doSomething(String str) {
    lock.lock();
    try {
      String dateString = date.toString();
      if (str != null && str.equals(dateString)) {
        // ...
      }
    } finally {
      lock.unlock();
    }
  }
}

Consequently, the lock is released even in the event of a runtime exception. The doSomething() method also ensures that the string is non-null to avoid throwing a NullPointerException.

Risk Assessment

Failing to release locks on exceptional conditions could lead to thread starvation and deadlock.

Related Vulnerabilities

GERONIMO-2234

Related Guidelines

Bibliography

      08. Locking (LCK)